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)	BRL	Currency code
payType	Y	int	200	pls refer to Payin PayType Enum
amount	Y	decimal(20,2)	[5,100000]	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://acb.com/	webhooks (callback) address
nonceStr	Y	string(32)	162838128	Random string
remark	Y	string(32)	remark	Order remarks
realName	N	string(32)	Jack	Payer Name
phone	N	string(32)	+57xxxxxxx	Payer phonenumber
email	N	string(32)	xyz@gamil.com	Payer email
idType	Y	string(32)	only support cpf	Payin Payer ID Type
idCard	Y	string(32)	Required when idType is not empty	Payer CPF number, passing CPF can improve the success rate
goodsSubject	N	string(32)	apple	Product subject
goodsBody	N	string(32)	apple	Product description

TIP

Please note:

• When idType is passed, the idCard parameter must be passed, and we will do basic CPF format verification. ( 123.456.789-09 / 12345678909) Both formats are supported.
• If you need to enable payee CPF verification on the bank side, please contact our operations colleagues to enable it. (After this function is turned on, collection orders will only accept payment from the payer corresponding to the CPF)

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

JSON Example:

{
  "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,2)	Amount
orderFee	decimal(20,2)	fee
payCode	string(32)	Payment account VA
payUrl	string(250)	Payment Url

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.

{
  "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
  }
}

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

{
  "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"
}

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.