Skip to main content

Pay-In · Colombia

TOPPAY TeamAbout 3 min

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.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/co/pay/prePay
Productionhttps://openapi.toppayment.com/co/pay/prePay

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

Request Header

FieldRequiredTypeDescription
Content-TypeMStringFixed value: application/json

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
orderNumMString(64)Merchant order number
amountMNumber(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.
productDetailMString(100)Product detail
methodOString(16)Payment method (Colombia)
Common: PSE; also NEQUI, BRE-B-LLAVE, CASH — Regional Payment Guide — Colombia
timestampMString(13)Timestamp in milliseconds
customerNameMString(64)Customer name
customerEmailMString(64)Customer email
customerPhoneMString(32)Customer phone
expiryPeriodONumber(1–9999)Validity in minutes
downNotifyUrlMString(255)Async callback URL
redirectUrlOString(512)Redirect after payment
documentTypeCString(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
documentNoCString(100)ID document number
Used together with documentType, required by some channels
Digit count is not validated against documentType; passed through as-is
payerBankCodeCString(32)Payer bank code
Required when method is PSE and the channel demands it; see the bank list in the regional guide
payerAccountNoCString(64)Payer wallet account
Required when method is NEQUI and the channel demands it; typically a local 10-digit number starting with 3
signMStringSignature — 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

Response

HTTP Response

FieldRequiredTypeDescription
Content-TypeMStringapplication/json

Response Body Parameters

FieldRequiredTypeDescription
successMBooleanSuccess flag
codeMString9999 = success
msgOStringMessage
timeStampMNumberServer time (ms)
dataMObjectPayload
orderNumMStringMerchant order number
platOrderNumMStringPlatform order number
amountMNumberAmount
feeMNumberFee
methodMStringPayment method (Colombia) — Regional Payment Guide — Colombia
productDetailMStringProduct detail
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
validTimeMNumberExpiry timestamp (ms)
cashierUrlMStringCashier URL
payDataMStringPay data / link
payDataTypeMStringe.g. CASHIER_URL
Content-type: application/json

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