Modify payments
Learn how to capture, adjust, reverse or refund a payment.
Change payments
In this section
Capture, adjustment, reversal and refund actions are called modifications, because they change the state of a payment after the shopper has paid. Changing payments is the third step in the Datman flow: it comes after you take payments and before you pay out the funds.
The possible payment modifications are:
| Modification | Use it when | Payment state | API reference |
|---|---|---|---|
| Capture | You want to complete a pre-authorised payment, for example when the order is ready. You can capture the full amount or less. | Authorised, not captured | Capture a pre-authorised payment |
| Adjust authorisation | The final order total differs from the pre-authorised amount, and you haven't captured it yet. | Authorised, not captured | Adjust the amount of a pre-authorised payment |
| Reverse authorisation | You don't want to take the payment, and it hasn't been captured. The hold on the shopper's funds is released. | Authorised, not captured | Reverse a pre-authorisation |
| Refund | You want to return all or part of a payment to the shopper, for example when an item is out of stock. | Paid. A pre-authorised payment is captured in full first, then refunded. | Refund a payment |
How modification requests work
Each modification is its own request. They have the following in common:
- Authentication: send your
api_tokenheader. - Identify the payment: capture, adjustment and reversal take the payment's
xref(O<order_id>M<merchant_id>T<payment_id>), which you receive in the payment status webhook. A refund takes yourorder_idand themerchant_idinstead. - Amounts:
amountis in major units, for example 24.50 for GBP 24.50. - Response: the body contains
outcome, which is success or failed. A failed request hasoutcomefailed and amessage, returned with HTTP 200. Checkoutcome, not only the HTTP status. When a capture, adjustment or reversal reaches the acquirer, the HTTP status is the acquirer's: 201 when it accepts the request, or an error status.outcomeis then success even if the acquirer returned an error, andstatusis the acquirer's status for the change, for example received or authorised.
Example
Example Pizza Ltd (MID 10012345) pre-authorises GBP 24.50 for a delivery order. The shopper adds a drink, so Example Payments Partner adjusts the authorisation to GBP 27.75, then captures GBP 27.75 when the order leaves the shop. Later the shopper reports a missing drink, and Example Payments Partner refunds GBP 3.25.