Create Payin Order
HTTP Request
TIP
POST baseUrl + /api/payIn
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
RequestBody
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
currency | Y | string(32) | COP | Currency code(COP) |
payType | Y | int | pls refer topayin-paytype-enum | Payment Product Type |
amount | Y | decimal(20,2) | 10000 | 金额10000-5000000 |
reusableStatus | Y | boolean | false（false=不允许 true=允许） | Whether to allow repeated payments can only be false |
mchOrderNo | Y | string(32) | mchOrderNo1234 | Merchant order number (should be unique in the merchant system) |
expireTime | Y | long | 3600 | Expire time（Unit: Seconds） default 24 hours |
notifyUrl | Y | string(250) | http://abc.com/ | webhooks (callback) address |
nonceStr | Y | string(32) | 1628328xxxx | Random string |
remark | Y | string(32) | remark | Order remarks |
realName | Y | string(32) | Jeck | Payer Name |
phone | Y | string(32) | +57xxxxxxx | Payer phonenumber |
email | Y | string(32) | xyz@gamil.com | Payer phonenumber |
idType | Y | string(32) | pls refer toPayin Payer ID Type | Payin Payer ID Type payType=153可不传 |
idCard | Y | string(32) | 付款人证件号 payType=153可不传 | |
userType | Y | string(16) | pls refer to用户类型 | 用户类型 payType=157必传 |
bankId | Y | int | pls refer topayin-bank-list-query | Bank idpayType=157必传 |
goodsSubject | N | string(32) | apple | Product subject |
goodsBody | N | string(32) | apple | Product description |
TIP
Note that callback/webhook addresses only support https or http protocol addresses. If the address is an ip address, be sure to use a public domain name.
ResponseBody
| Parameter | Type | Description |
|---|---|---|
merchantId | long | MerchantId |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
amount | decimal(20,2) | Amount |
orderFee | decimal(20,2) | fee |
payCode | string(32) | 付款账户 VA |
payUrl | string(250) | Payment Url |
JSON 示例
json
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656908719283",
"orderNo": "PAYIN8232154612109344768",
"payCode": "646012000000015942",
"payUrl": null,
"amount": 100
}
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Query Payin Order
HTTP Request
TIP
POST baseUrl + /api/payInQuery
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
RequestBody
| Parameter | Required | Type | Example | Description |
|---|---|---|---|---|
mchOrderNo | N | string(32) | P123456 | Merchant order number |
orderNo | N | string(32) | PAYIN12345 | Platform order number |
nonceStr | Y | string(32) | 1628381288000 | Random string |
TIP
We recommend using orderNo (platform order number) first. At least one of the platform order number and merchant order number needs to be passed.
json
{
"msg": "SUCCESS",
"code": 200,
"data": {
"merchantId": "100001",
"mchOrderNo": "M1656752128806",
"orderNo": "PAYIN8231497473279467520",
"payType": "1",
"payCode": "646012000000015887",
"payUrl": null,
"amount": 100.0,
"fee": null,
"orderStatus": "PAYING",
"completionTime": null
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| Parameter | Type | Description |
|---|---|---|
merchantId | int | MerchantId |
mchOrderNo | string(32) | Merchant order number |
orderNo | string(32) | Platform order number |
channelOrderNo | string(32) | Channel order number |
payType | string(32) | pls refer to Payin PayType Enum |
payCode | string(32) | 支付码 |
payUrl | string(250) | Payment QR Code |
amount | decimal(20,0) | Amount |
fee | decimal(20,4) | fee |
orderStatus | string(32) | Order StatusPayin Order Status Enum |
completionTime | date | Complete time |
TIP
fee and completionTime only have a value if the order is successfully paid.
Async Webhook Notification
HTTP Request
TIP
POST : notifyUrlnotifyUrlis provided by the merchant
Request Headers
| HeaderName | Required | Value |
|---|---|---|
Content-Type | Y | application/json |
MerchantId | Y | MerchantId |
Sign | Y | Sign |
Webhook RequestBody
json
{
"orderStatus": "SUCCESS",
"amount": 10000.0,
"fee": 0,
"mchOrderNo": "2a6421c4-3758-4d1a-b47e-f7d0e7133f9e",
"merchantId": "100001",
"orderNo": "PAYDESKxxxxxxxxxxx",
"payUrl": "xxxxxxxxxxxx",
"completionTime": "2022-08-08 08:08:08",
"nonceStr": "xxxxxxxxxx"
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
| Parameter | Type | Description |
|---|---|---|
merchantId | int | MerchantId |
mchOrderNo | string(32) | Merchant order number (should be unique in the merchant system) |
orderNo | string(32) | Platform order number |
amount | decimal(20,2) | Amount |
fee | decimal(20,4) | fee (fee only after successful payment) |
payUrl | string(32) | Payment Url |
orderStatus | string(32) | Order Status |
completionTime | date | Completion time yyyy-MM-dd HH:mm:ss |
nonceStr | string(32) | Random string |
TIP
Please respond with SUCCESS if the process is successful. For other responses, we will consider the callback to have failed. After the callback fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the callback will be retried 10 times in total.