Internal transfer failed webhook
Find out which webhook Datman sends when an internal transfer fails.
When you move funds between two of your merchants with an internal transfer, Datman sends a webhook to the webhook_url of the transfer to inform your server of the result. Use this guide to learn what Datman sends when the transfer fails, and how to identify it.
When an internal transfer fails, Datman sends the following webhook:
internalTransferFailed, which informs your server that the transfer failed and why.
If the transfer succeeds, Datman sends an internalTransferSucceeded webhook instead.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | A Datman integration that makes internal transfers. |
| Webhooks | Make sure that: - Your server can receive and accept webhooks. - You send your webhook URL in webhook_url when you create the transfer.- You have a transfer signing key from Datman, so that you can verify the X-Datman-Signature header. |
| Limitations | Datman sends this webhook once and doesn't send it again if your server doesn't accept it. |
Identify internal transfer failed webhooks
You can identify this webhook by looking at the following fields:
| Parameter | Description | Value |
|---|---|---|
request_id | The request_id returned when you created the transfer. | For example, 3f1c2b6a-8d4e-4f0a-9b7c-1e2d3c4b5a69 |
reason | Why the transfer failed. | For example, Insufficient funds |
status | Not present in this webhook. | — |
The following section provides a code sample for this event. The sample considers a use case where Example Pizza Ltd (MID 663412) tries to pay a GBP 3.50 delivery fee for an order to another of your merchants (MID 663500), but doesn't have enough funds.
Transfer failed
If the transfer fails, Datman sends an internalTransferFailed webhook. The body has a reason and no status. The webhook provides information about the transfer, such as:
- The
reasonwhy the transfer failed. - The
request_idof the transfer, and yourreference. - The
amountof the transfer, in minor units. For example, 350 is GBP 3.50. - The
source_merchant_idanddestination_merchant_idfrom your request. - The
transfer_category_codeanddescriptionfrom your request. - Your
order_id, if you sent it.
Note that currency is not present for every transfer, and that source_merchant_id and destination_merchant_id can be strings or numbers.
Transfer failed: insufficient funds
{
"reason": "Insufficient funds",
"request_id": "3f1c2b6a-8d4e-4f0a-9b7c-1e2d3c4b5a69",
"currency": "GBP",
"source_merchant_id": "663412",
"destination_merchant_id": "663500",
"amount": 350,
"transfer_category_code": 1,
"description": "Delivery fee for order ORD-100245",
"reference": "REF-100245-DLV",
"webhook_url": "https://partner.example.com/webhooks/transfers",
"order_id": "ORD-100245"
}Failure reasons
The reason field can have the following values:
| Reason | Description |
|---|---|
| Insufficient funds | The source merchant doesn't have enough funds for the transfer. |
| Transfer failed | The transfer couldn't be completed. |
Note that reason is free text, and can contain other messages that describe why the transfer failed.
Verify the signature
Each internalTransferFailed webhook carries an X-Datman-Signature header: the HMAC-SHA256 of the raw request body, computed with your transfer signing key and hex-encoded. Verify it before you process the webhook. For the steps and code samples, see Verify webhook signatures.