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)	VND	Currency code
payType	Y	int	200	pls refer to Payin PayType Enum
amount	Y	decimal(20,0)	10000	Amount
reusableStatus	Y	boolean	false	Currently it can only be false
mchOrderNo	Y	string(32)	mch12345	Merchant order number (should be unique in the merchant system)
expireTime	Y	long	3600	Expiration time, default 3600 seconds
notifyUrl	Y	string(250)	https://merchant.com/webhooks	webhooks (callback) address
nonceStr	Y	string(32)	1863484722378907648	Random string
remark	Y	string(32)	remark	Order remarks
realName	Y	string(32)	Jack	Payer Name
phone	Y	string(32)	+57xxxxxxx	Payer phonenumber
email	Y	string(32)	xyz@gamil.com	Payer email
idType	Y	string(32)	暂无	Payin Payer ID Type
idCard	Y	string(32)		Payer ID number

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

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "100001",
    "mchOrderNo": "M1656908719283",
    "orderNo": "PAYIN8232154612109344768",
    "payCode": "646012000000015942",
    "payUrl": null,
    "amount": 100
  }
}

Parameter	Type	Description
merchantId	long	MerchantId
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
amount	decimal(20,0)	Amount
orderFee	decimal(20,0)	fee
payCode	string(32)	Payment account VA
payUrl	string(250)	Payment Url

Query Payin Order

API EndPoint

POST baseUrl + /api/payInQuery

Request Parameters

Parameter	Required	Type	Example	Description
mchOrderNo	N	string(32)	1386556575370063873	Merchant order number
orderNo	N	string(32)	PAYIN8551843837024997376	Platform order number
nonceStr	Y	string(32)	9459931608	Random string

TIP

We recommend using orderNo (platform order number) first. At least one of the platform order number and the merchant order number must be passed.

Request Example

curl -L 'baseUrl/api/payInQuery' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"mchOrderNo":"1386556575370063873","nonceStr":"9459931608","orderNo":"PAYIN8551843837024997376"}'

Response Parameters

Parameter	Type	Description
merchantId	int	Merchant id
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
channelOrderNo	string(32)	Channel order number
payType	string(32)	Payin PayType Enum
payCode	string(32)	Payment Code
payUrl	string(250)	Payment url
amount	decimal(20,0)	Amount
fee	decimal(20,4)	Fee
orderStatus	string(32)	Payin Order Status Enum
completionTime	yyyy-MM-dd HH:mm:ss	Completion time

Response Example

Paying

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "PAYING",
    "completionTime": null,
    "nonceStr": null
  }
}

Success

{
  "msg": "SUCCESS",
  "code": 200,
  "data": {
    "merchantId": "1002001",
    "mchOrderNo": "1386556575370063873",
    "orderNo": "PAYIN8551843837024997376",
    "payType": "43",
    "payCode": "",
    "payUrl": "https://m.dana.id/link/pay?bizNo=202412021112128001101660361270",
    "payDeskUrl": "https://idpaydesk2.brcashypro.com/views/pay.html?PAYIN8551843837024997376",
    "amount": "20000",
    "fee": "1700",
    "orderStatus": "SUCCESS",
    "completionTime": "2024-12-02 15:40:50",
    "nonceStr": null
  }
}

Async Webhook Notification

The webhooks url is provided by the merchant

POST Merchant NotifyUrl

Webhook Request Parameters

Parameter	Type	Description
merchantId	int	Merchant id
mchOrderNo	string(32)	Merchant order number
orderNo	string(32)	Platform order number
amount	decimal(20,2)	Amount
fee	decimal(20,4)	Fee
orderStatus	string(32)	Order status
payUrl	string(32)	Payment url
payCode	string(32)	Payment VA/QRCODE
payType	string(32)	Pay product type
completionTime	yyyy-MM-dd HH:mm:ss	Completion time
nonceStr	string(32)	Random string

Webhook Request Example

curl -L 'merchant.com/webhooks/payin' \
-H 'MerchantId: 1002001' \
-H 'Sign: A6FC73F7D22EC8B4A064C8FFCC592CBF' \
-H 'Content-Type: application/json' \
-d '{"amount":20000.00,"completionTime":"2024-12-02 12:07:06","fee":2500.0000,"mchOrderNo":"1386503284355244033","merchantId":"1002001","nonceStr":"1733116026894","orderNo":"PAYIN8551790545658687488","orderStatus":"SUCCESS","payCode":"OR.GPNQR..INOPROID_BS","payType":"41","payUrl":"https://payurl.com"}'

Webhooks-Success

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "SUCCESS",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

Webhooks-Fail

{
  "amount": 20000.0,
  "completionTime": "2024-12-02 12:07:06",
  "fee": 2500.0,
  "mchOrderNo": "1386503284355244033",
  "merchantId": "1002001",
  "nonceStr": "1733116026894",
  "orderNo": "PAYIN8551790545658687488",
  "orderStatus": "FAIL",
  "payCode": "OR.GPNQR..INOPROID_BS",
  "payType": "41",
  "payUrl": "https://payurl.com"
}

TIP

When the webhooks response HTTP status code is 200, 301 or 302, we believe that the merchant has successfully received and processed the callback. For other statuses, we believe that the merchant has failed to process the callback.

After the webhooks fails, it will be retried in 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 minutes, and the webhooks will be retried 10 times in total