Webhook

Handle webhook events

MoneyCollect uses webhooks to asynchronously notify merchants about related events.

MoneyCollect webhook endpoints

  1. 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.

  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.

Webhook event type

  1. Payment

Event codeEvent 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

  1. Refund

Event codeEvent description

refund.pending

Refund pending

refund.succeeded

Refund succeeded

refund.failed

Refund failed

  1. Invoice

Event codeEvent 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.

Webhook message

Request format

Request header included request-timesignatureparameter;

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":"112374@gmail.com","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"}}'

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 DevelopersPage-> 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:

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":"112374@gmail.com","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"}}

For more details, please check the API Reference.

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