Payment Link API

• The Payment API returns a payment URL. Merchants should redirect the user to this URL to complete the payment.

• Request URL
• Request Method
• Way Code
• Header
• Body
• Request Example
• Response Results
• Accepted Response Example

Tips

• All requests use the POST method and the data format is JSON.

Request URL

• /v1/paypro/payIn

Request Method

• Method: POST
• Content-Type: application/json

Way Code

wayCode	Description
PSE	Online Banking Payment (ACH)
WALLET	Nequi Digital Wallet Payment
BREB	Payment Key (Colombia's new-generation real-time payment. A unique payment key is generated for the user to copy into their banking app. The user can modify the amount.)

Header

Header	Required	Type	Description
merchantNo	Yes	String	Merchant number

Body

Parameter Name	Required	Type	Description
sign	Yes	String	Sort all fields except sign alphabetically and concatenate them as key1=value1key2=value2.... Use the app secret as the salt for MD5 encryption. The result must be lowercase.
timestamp	Yes	Long	13-digit Unix timestamp in milliseconds, for example 1715941383720
tradeNo	Yes	String	Unique merchant transaction number. A timestamp plus a random number is recommended.
amount	Yes	String	Payment amount in COP, expressed as an integer string. Decimals are not supported.
name	Yes	String	User's full name
mobile	No	String	User's 10-digit Colombian mobile number, starting with 3
email	No	String	User's email address
wayCode	Yes	String	Deposit method code
idType	Conditional	String	ID type: CC (Citizen ID), CE (Foreigner ID), NIT (Tax ID), or PA (Passport). Required for PSE, WALLET, and BREB.
idCardNumber	Conditional	String	ID number matching idType: CC and CE require 6–10 digits; NIT and PA require 9 digits. Required for PSE, WALLET, and BREB.
bankCode	Conditional	String	Bank code. Required for PSE. Use the applicable code from the Colombia bank-code list.
notifyUrl	Yes	String	HTTPS endpoint that receives asynchronous server-to-server transaction notifications
returnUrl	Yes	String	URL to which the user's browser is redirected after the payment flow
remark	Yes	String	Merchant remark returned unchanged in the response

Request Example

{
  "timestamp": 1750911986148,
  "amount": "10000",
  "wayCode": "PSE",
  "idType": "CC",
  "idCardNumber": "1114818656",
  "bankCode": "0001",
  "tradeNo": "LoMwIKtsIKOWMpEJwTDtO",
  "remark": "Test remark",
  "email": "payer@example.com",
  "mobile": "3123456789",
  "name": "test name",
  "notifyUrl": "https://merchant.example/payment/notify",
  "returnUrl": "https://merchant.example/payment/result",
  "sign": "516c96dcc5816133cabf14d205de4069"
}

Response Results

Parameter Name	Required	Type	Description
msg	Yes	String	Request result. A value of success only means the request was accepted and must not be used as the transaction result.
code	Yes	String	Request response code. 0000 only means the request was accepted. Refer to the error-code documentation for other values.
timestamp	Yes	Long	Transaction timestamp
success	Yes	Boolean	Whether the API request was accepted
data	Yes	Object	Response object
data.tradeNo	Yes	String	Merchant transaction number
data.platFormTradeNo	Yes	String	Paypro transaction number, unique
data.status	Yes	String	Transaction status: 0000 success, 0015 processing, or 00029 failed.
data.desc	Yes	String	Status description
data.remark	Yes	String	Merchant remark returned unchanged
data.paymentUrl	Yes	String	Payment redirect URL

Accepted Response Example

{
  "msg": "success",
  "code": "0000",
  "timestamp": 1728609277476,
  "success": true,
  "data": {
    "tradeNo": "test_00000008",
    "platFormTradeNo": "68o0uwogz7mnzutt",
    "status": "0015",
    "desc": "Create",
    "remark": "test",
    "paymentUrl": "https://checkout.example/payment/68o0uwogz7mnzutt"
  }
}