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 |
| documentType | C | String(16) | ID document type: CC / CE / NIT / PAS (case-insensitive). Required by some channels; the order is rejected by those channels when absent. See Regional Payment Guide — Colombia |
| documentNo | C | String(100) | ID document number Used together with documentType, required by some channelsDigit count is not validated against documentType; passed through as-is |
| payerBankCode | C | String(32) | Payer bank code Required when method is PSE and the channel demands it; see the bank list in the regional guide |
| payerAccountNo | C | String(64) | Payer wallet account Required when method is NEQUI and the channel demands it; typically a local 10-digit number starting with 3 |
| sign | M | String | Signature — see Signature |
C(conditional): These extension fields depend on the specific channel. Whether they are mandatory follows the channel configuration issued by operations. They are ignored when the channel does not need them, and the order is rejected when the channel requires them but they are absent.
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
