Pay-In · Colombia

Request

The Pay-In API initiates collection transactions from customers. This page covers Colombia (country code co). Request/response fields are the same across markets; use your market’s method codes only. For split credits and multiple success callbacks under the same orderNum, see Regional Payment Guide — Colombia (Pay-In notification rules).

Request URL

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy country domain (e.g. global-co-openapi.toppayment.com) remains available.

Environment	URL
Sandbox	https://openapi.toppayment.com/sandbox/co/pay/prePay
Production	https://openapi.toppayment.com/co/pay/prePay

method (Pay-In payment codes for Colombia) is listed in Regional Payment Guide — Colombia.

Request Header

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json

Request Body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number
orderNum	M	String(64)	Merchant order number
amount	M	Number(32,8)	Transaction amount Colombia (pre-order / direct Pay-In): positive, integer or at most 2 decimal places, not all zeros, no three or more decimal places.
productDetail	M	String(100)	Product detail
method	O	String(16)	Payment method (Colombia) Common: PSE; also NEQUI, BRE-B-LLAVE, CASH — Regional Payment Guide — Colombia
timestamp	M	String(13)	Timestamp in milliseconds
customerName	M	String(64)	Customer name
customerEmail	M	String(64)	Customer email
customerPhone	M	String(32)	Customer phone
expiryPeriod	O	Number(1–9999)	Validity in minutes
downNotifyUrl	M	String(255)	Async callback URL
redirectUrl	O	String(512)	Redirect after payment
sign	M	String	Signature — see Signature

Request Body Example

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "CO1234561",
    "amount": 100.50,
    "productDetail": "Product",
    "method": "PSE",
    "timestamp": "1749451858772",
    "customerName": "Maria Lopez",
    "customerEmail": "[email protected]",
    "customerPhone": "+573001234567",
    "expiryPeriod": 1440,
    "downNotifyUrl": "https://example.com/notify",
    "redirectUrl": "https://example.com/return",
    "sign": "Generate per signature rules and replace"
}

Response

HTTP Response

Field	Required	Type	Description
Content-Type	M	String	application/json

Response Body Parameters

Field	Required	Type	Description
success	M	Boolean	Success flag
code	M	String	9999 = success
msg	O	String	Message
timeStamp	M	Number	Server time (ms)
data	M	Object	Payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
amount	M	Number	Amount
fee	M	Number	Fee
method	M	String	Payment method (Colombia) — Regional Payment Guide — Colombia
productDetail	M	String	Product detail
customerName	M	String	Customer name
customerEmail	M	String	Customer email
customerPhone	M	String	Customer phone
validTime	M	Number	Expiry timestamp (ms)
cashierUrl	M	String	Cashier URL
payData	M	String	Pay data / link
payDataType	M	String	e.g. CASHIER_URL

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767840272829,
    "data": {
        "orderNum": "CO1234561",
        "platOrderNum": "PRE2009093829059153920",
        "amount": 100.50,
        "fee": 2.0,
        "method": "PSE",
        "productDetail": "Product",
        "customerName": "Maria Lopez",
        "customerEmail": "[email protected]",
        "customerPhone": "+573001234567",
        "validTime": 1767926672819,
        "cashierUrl": "https://example.cashier/pay",
        "payData": "https://example.cashier/pay",
        "payDataType": "CASHIER_URL"
    }
}

Notification

Same callback contract as other Pay-In markets: body fields, status string values, and SUCCESS acknowledgment — see Transaction Status Codes.

For platOrderNum and paid amounts when multiple credits occur, see Regional Payment Guide — Colombia.

Example callback (illustrative)

{
    "platOrderNum": "PRE2009165141186183168",
    "version": "v1",
    "orderNum": "CO12345621",
    "amount": 100.50,
    "fee": 2,
    "customerName": "Maria Lopez",
    "customerEmail": "[email protected]",
    "customerPhone": "+573001234567",
    "status": "SUCCESS",
    "sign": "…"
}

Respond with:

SUCCESS