Comment on page
Webhook
Handle webhook events
MoneyCollect uses webhooks to asynchronously notify merchants about related events.
- 1.A dynamic webhook endpoint URL can be passed with the
notifyUrlparameter while sending a payment transaction, or you can add a dedicated custom webhook endpoint in the MoneyCollect dashboard. - 2.The webhook requires the merchant to return a string message "
success" in response body to be considered as a successful notification. Other forms of returned messages will be considered as notification failed and the follow-up notifications will continue to be pushed. - 3.The follow-up webhook notifications will continue for 25 hours, a total of 12 times, and the notification interval is 30s/1m/2m/5m/10m/15m/30m/1h/2h/4h/8h/8h.
- 4.A single event can be pushed to the merchant's system multiple times. The merchant's system must be able to properly handle duplicate webhook notifications to avoid transaction state override issues. And in some very rare cases, a transaction state can be updated and MoneyCollect will send a new event notification regarding the same transaction. The merchant's system should be able to handle the status update as well.
- 5.The merchant system must perform signature verification on the content of the webhook, and verify whether the returned order amount is consistent with the order amount on the merchant side, so as to prevent data leakage and cause "false notifications", resulting in funds loss.
- 6.Webhook notifications are transferred from server to server. If the merchant's server has a whitelist control, please contact the MoneyCollect technical support team to provide webhook server IP addresses.
- 7.The webhook integration is mandatory and needs to be fully tested before going live for all merchants.
- 1.Payment
Event code | Event description |
|---|---|
payment.processing | Payment pending |
payment.succeeded | Payment succeeded |
payment.failed | Payment failed |
payment.requires_capture | Pre-authorized payment pending capture |
payment.canceled | Pre-authorized payment cancelled |
- 2.Refund
Event code | Event description |
|---|---|
refund.pending | Refund pending |
refund.succeeded | Refund succeeded |
refund.failed | Refund failed |
- 3.Invoice
Event code | Event description |
|---|---|
invoice.created | Occurs whenever a new invoice is created. |
invoice.deleted | Occurs whenever a draft invoice is deleted. |
invoice.payment_succeeds | Occurs whenever an invoice payment attempt succeeds. |
invoice.payment_failed | Occurs whenever an invoice payment attempt fails, due either to a declined payment or to the unavailable payment methods. |
Invoice.sent | Occurs whenever an invoice email is sent out. |
Invoice.updated | Occurs whenever an invoice changes (e.g., the invoice amount). |
Invoice.voided | Occurs whenever an invoice is voided. |
Request header included
request-time、signatureparameter；request-time represents webhook request time. To mitigate merchant server's replay attack， we suggest that the merchant can consider the webhook within three minutes before and after the request-time as a valid notification. The format of request-time is yyyy-MM-dd'T'HH:mm:ss； signatureis signature parameter. Merchants are advised to verify signatures during the docking test to ensure that the data is sent by the MoneyCollect server. Request body please refer to the specific webhook API；#Message example
curl -X POST "https://www.moneycollect.com/webhook"
-H 'Content-Type: application/json'
-H 'request-time:2022-01-01T12:23:45'
-H 'signature:DE16B432FEB4A74E3E8578EB1384351749B09409A41DCF3E63D22CD7F0571695'
-d '{"apiVersion":"v1","type":"payment.succeeded","created":"2022-01-01T14:21:01.200+08:00","data":{"id":"pt_1508690666081947649","clientSecret":"pt_1508690666081947649_secret_1C0B58DAE56D711A9EBC2B3CC42C0314","canceledAt":null,"cancellationReason":null,"actionStatus":null,"amountReceived":"0","amountCapturable":"0","created":"2022-01-01T14:20:59.574+08:00","riskInfo":{"riskScore":100,"riskMessage":"risk_pass"},"status":"succeeded","errorCode":null,"errorMessage":null,"amount":"20000","currency":"EUR","confirmationMethod":"automatic","customerId":"cus_1447380232473600002","description":"success","paymentMethod":"pm_1447380502720995330","receiptEmail":"[email protected]","setupFutureUsage":"on","orderNo":"Test36028","notifyUrl":"https://www.moneycollect.com/pages/PayResult.jsp","returnUrl":"https://www.moneycollect.com/pages/PayResult.jsp","website":"https://baidu.com","ip":"192.168.0.12","preAuth":"n"}}'
MoneyCollect will sign the webhook events it sends to your endpoints by including a signature in each event's Signature header. This allows you to verify that the events were sent by MoneyCollect, not by a third party.
Signature format: HmacSHA256 (request-time + "." + body, WebhookToken);
request-time: request-time in request header. As in the message example above: 2022-01-01T12:23:45 body: Request body；WebhookToken: you need to retrieve it from your MoneyCollect dashboard’s DevelopersPage-> Webhook.
Webhook
Webhook details page
Token
The token of each endpoint is different. Select the endpoint you want to view, click to enter the details page, and click 【Reveal】 to get the token.
If the token is compromised, you can invalidate the previous token and generate a new one.
In the above example, the concatenated string is：
2022-01-01T12:23:45.{"apiVersion":"v1","type":"payment.succeeded","created":"2022-01-01T14:21:01.200+08:00","data":{"id":"pt_1508690666081947649","clientSecret":"pt_1508690666081947649_secret_1C0B58DAE56D711A9EBC2B3CC42C0314","canceledAt":null,"cancellationReason":null,"actionStatus":null,"amountReceived":"0","amountCapturable":"0","created":"2022-01-01T14:20:59.574+08:00","riskInfo":{"riskScore":100,"riskMessage":"risk_pass"},"status":"succeeded","errorCode":null,"errorMessage":null,"amount":"20000","currency":"EUR","confirmationMethod":"automatic","customerId":"cus_1447380232473600002","description":"success","paymentMethod":"pm_1447380502720995330","receiptEmail":"[email protected]","setupFutureUsage":"on","orderNo":"Test36028","notifyUrl":"https://www.moneycollect.com/pages/PayResult.jsp","returnUrl":"https://www.moneycollect.com/pages/PayResult.jsp","website":"https://baidu.com","ip":"192.168.0.12","preAuth":"n"}}
Among the team members under the account, only 【Owner】, 【Administrator】, and 【Developer】 have the authority to view and operate webhooks. When assigning work, please remember to give the corresponding operators the correct account permissions.
Last modified 3mo ago