Payment Callback (Webhook)

KidaPay can send webhook events that notify your application any time order status has been paid.

Depending on how you fulfill your payment, you will be informed about the status changes after the payment has been authenticated. You might also use webhooks as the basis to:

• Update a customer’s membership record in your database when a subscription payment succeeds
• Email a customer when a subscription payment fails
• Log an accounting entry when a transfer is paid

This is the ONLY thing needed on the backend to keep track of the Payment status.

---

Request

1. Callback data is sent in POST method.
2. Content-Type: application/json
3. Authentication will be the token provided in CreateOrder.
4. KidaPay sends payment notification while your application returns response 200 (OK) HTTP status code. You should respond in json format with content:

 {
     "status": 200
 }

5. Pay attention to token. The token sent in the body, is provided by merchants. Merchants will use it to validate the callback request (to prevent fraud attemps callbacks).

Example

	const body = { 
		merchant_order_id: merchant_order_id, // provided by CreateOrder
		order_id: order_id,
		status: 'PAID',
		price_amount: 0.14,
		price_currency: 'USD',
		pay_amount: 1,
		pay_currency: 'CNY',
		created_at: '2019-04-24T17:23:54.311Z'),
		created_at_t: 1556126634311,
		token: token,                          // token provided by CreateOrder
		meta: {
			payment: 'ALIPAY', // ALIPAY or WECHAT
			total_amount: 1.00, // Amount in CNY, ￥8.50
			trade_no: 123, // Only in Alipay
			out_trade_no: 123, // merchant_order_id
		}
	}
	return request(merchant_callback_url, { // url provided by CreateOrder
		method: 'POST',
		body: body
	})

Data Structure

Param	Type	Description
order_id	string	KidaPay order ID
merchant_order_id	string	Order ID of the merchant. Should be used to identify order or invoice.
status	string	KidaPay payment status.
price_amount	string	The price set by the merchant; Example: 9.99
price_currency	string	Currency in which the merchant's goods/services are priced; Example: USD
created_at	Date	Invoice creation time; Example: '2019-04-24T17:23:54.311Z'
created_at_t	Long(Epoch)	Invoice creation time; Example: 1556126634311
token	string	Your token provided by CreateOrder to validate Payment Callback. 这里的token是由商户平台产生的，在CreateOrder时候，在body传入（如果创建时未填写该字段，则回调时候不会传入）。这个来检验回调的真伪，例如用户支付成功，KidaPay会给商户回调地址发通知，但是可能有人伪造KidaPay，伪造告诉商户支付成功。商户应该在回调检验时候，检验该token的正确性。
meta	json	Option: provide third party information. e.g. Alipay or WechatPay. An example of Alipay is provided as example.

Retry Time

The KidaPay server attempts to send callbacks multiple times until the send is either successful or the KidaPay server gives up. The KidaPay server attempts retries using an exponential back on the following schedule:

• 1-minute delay
• 2-minute delay
• 4-minute delay
• 8-minute delay
• 16-minute delay
• 32-minute delay
• 64-minute delay
• 128-minute delay
• 256-minute delay
• Retry attempt times double for up to 3 days