Payment status webhooks

When the status of a payment changes, Datman sends a paymentStatus webhook to inform your server of the change. Use this guide to learn which payment events Datman sends webhooks for, and how to identify them.

Datman sends one kind of webhook for payment events:

• paymentStatus, which informs your server that a payment was authorised, refused, adjusted, captured or cancelled, or that a capture failed.

RequirementsCopy Anchor Link

Before you begin, take into account the following requirements, limitations, and preparations.

Identify payment status webhooksCopy Anchor Link

You can identify payment status webhooks and the event they describe by looking at the following fields:

Note that order_id is your original order reference and customer_id is your original shopper reference, from the request that created the payment.

Datman sends webhooks for the following payment events:

• Payment authorised
• Authorisation adjusted
• Payment captured
• Capture failed
• Authorisation cancelled

The following sections provide code samples for the events that trigger webhooks. These samples consider a use case where a shopper pays Example Pizza Ltd (MID 663412) GBP 24.50 for an order. All amounts in this webhook are strings in major units, for example 24.50.

Payment authorisedCopy Anchor Link

After the shopper pays, Datman sends a paymentStatus webhook to inform your server of the result of the authorisation. The webhook provides information about the payment, such as:

• The amount and currency of the payment.
• Your order_id and customer_id.
• Datman's xref for the payment. Save it, because you need it to match later webhooks for the same payment.
• Card and check details, such as card_type, card_bin, last4_digits, avs_result, cvc_result and three_ds_authenticated.

When the payment is authorised, the webhook has status authorisation and success true.

Payment authorised

{
  "order_id": "ORD-100245",
  "amount": "24.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213045M663412T4821937",
  "status": "authorisation",
  "success": "true",
  "date": "2026-10-15 12:34:56+01:00",
  "three_ds_authenticated": "true",
  "three_ds_authenticated_response": "Y",
  "card_bin": "411111",
  "last4_digits": "1111",
  "expiry_date": "03/2030",
  "avs_result": "4 AVS not supported for this card type",
  "cvc_result": "1 Matches",
  "card_type": "visa"
}

Payment refusedCopy Anchor Link

If the payment is refused, the webhook has:

• status authorisation
• success false
• reason: why the payment was refused, for example CVC Declined.

Payment refused

{
  "order_id": "ORD-100246",
  "amount": "24.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213046M663412T4821938",
  "status": "authorisation",
  "success": "false",
  "date": "2026-10-15 12:34:56+01:00",
  "cvc_result": "2 Does not match",
  "card_type": "visa",
  "reason": "CVC Declined"
}

Authorisation adjustedCopy Anchor Link

After you adjust the amount of a pre-authorised payment, Datman sends a paymentStatus webhook with:

• status authorisation_adjustment
• success true if the new amount is authorised, or false with a reason if it is not.
• amount: the new authorised amount.

For example, if Example Pizza Ltd adds a GBP 2.00 tip to the order, the webhook has amount 26.50.

Authorisation adjusted

{
  "order_id": "ORD-100245",
  "amount": "26.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213045M663412T4821937",
  "status": "authorisation_adjustment",
  "success": "true",
  "date": "2026-10-15 12:40:02+01:00"
}

Payment capturedCopy Anchor Link

When a pre-authorised payment is captured, for example after you make a capture request, Datman sends a paymentStatus webhook with:

• status capture
• success true
• split_fee_status: present only if the order has split fees. It contains the outcome and message of the split fee.

Payment captured

{
  "order_id": "ORD-100245",
  "amount": "26.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213045M663412T4821937",
  "status": "capture",
  "success": "true",
  "date": "2026-10-15 13:05:41+01:00"
}

Capture failedCopy Anchor Link

If a capture can't be completed, Datman sends a paymentStatus webhook with:

• status capture_failed, or status capture with success false.
• reason: why the capture failed.

Capture failed

{
  "order_id": "ORD-100245",
  "amount": "26.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213045M663412T4821937",
  "status": "capture_failed",
  "success": "false",
  "date": "2026-10-16 13:05:41+01:00"
}

Authorisation cancelledCopy Anchor Link

After you reverse a pre-authorisation, Datman sends a paymentStatus webhook with:

• status cancellation
• success true if the authorisation was reversed.

Authorisation cancelled

{
  "order_id": "ORD-100245",
  "amount": "24.50",
  "currency": "GBP",
  "customer_id": "CUST-55021",
  "xref": "O88213045M663412T4821937",
  "status": "cancellation",
  "success": "true",
  "date": "2026-10-15 12:50:10+01:00"
}

Verify the signatureCopy Anchor Link

Each paymentStatus webhook carries an HMACSignature header: the HMAC-SHA256 of the request body, computed with your webhook secret and hex-encoded. Verify it before you process the webhook. For the steps and code samples, see Verify webhook signatures.

Note that Datman includes the HMACSignature header only when a webhook secret is set up for your account. We recommend that you make sure that you have a webhook secret before you go live, so that you can verify every webhook.

See alsoCopy Anchor Link

• Webhooks
• Verify webhook signatures
• Hosted payment page
• Payment status notification in the API Explorer