Webhook
Handle webhook events
MoneyCollect uses webhooks to asynchronously notify merchants about related events.
MoneyCollect webhook endpoints
A dynamic webhook endpoint URL can be passed with the
notifyUrl
parameter while sending a payment transaction, or you can add a dedicated custom webhook endpoint in the MoneyCollect dashboard.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.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.
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.
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.
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.
The webhook integration is mandatory and needs to be fully tested before going live for all merchants.
Webhook event type
Payment
Refund
Invoice
Webhook message
Request format
Request header included request-time
、signature
parameter;
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
;
signature
is 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;
Signature format
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 Developers
Page-> Webhook
.
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:
For more details, please check the API Reference.
Notification Message Type Handling
To accommodate the notification types of legacy merchants, two types of notifications will be sent (see the examples of notification content below):
Notifications with a type starting with "endpoint_" are those that newly integrated merchants are required to receive, verify the signature for, and process the data.
Notifications without the "endpoint_" prefix in the type should be directly ignored by newly integrated merchants, otherwise, the signature verification will not pass.
Webhook settings permissions
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 updated