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

Webhook message

Request format

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":"[e-mail]","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.

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":"[e-mail]","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.

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.

{
  "apiVersion": "v1",
  "type": "payment.succeeded",
  "created": "2024-05-11T08:46:38.804Z",
  "data": {
    // ......  data here
  }
}

{
  "apiVersion": "v1",
  "type": "endpoint_payment.payment_succeeded",
  "created": "2024-05-11T08:52:42.559Z",
  "data": {
    // ......  data here
  }
}

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.