Capture payments
Capture the full or a partial amount of a pre-authorized payment, or let Ginger Payments capture it automatically.
A capture turns a pre-authorization into an actual payment: the reserved funds move from your customer's card to you. You can capture:
- The full amount that was authorized.
- A partial amount, for example when an item is out of stock or a service costs less than expected.
One capture per transaction
You can capture a pre-authorized transaction only once. After a full or partial capture, the rest of the reserved amount is released to your customer and you can't capture it later.
Captures work on transactions created with capture_mode set to manual. You need the order ID and the transaction ID, which are both in the response when you create the order.
Capture the full amount
Send a POST request to the captures endpoint of the transaction. No request body is needed:
curl https://api.dev.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/captures/ \
--user "$API_KEY:" \
--request POSTThe full authorized amount is captured.
Capture a partial amount
Send the amount to capture, in the smallest currency unit, and a description to the captures/amount endpoint. This example captures € 25.00 of a € 100.00 pre-authorization:
curl https://api.dev.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/captures/amount/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"amount": 2500,
"description": "Capture 25.00 of the full 100.00"
}'| Field | Required | Description |
|---|---|---|
amount | Yes | Amount to capture in the smallest currency unit. Must not be more than the authorized amount. |
description | Yes | Description of the capture. |
The remaining € 75.00 is released to your customer.
Capture automatically
To capture after a fixed period without an API call, set capture_mode to delayed when you create the order. The payment is captured automatically when the transaction's expiration_period ends. This example captures 7 days after your customer authorizes the payment:
curl https://api.dev.gingerpayments.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "EUR",
"amount": 10000,
"merchant_order_id": "EXAMPLE001",
"description": "Example delayed capture",
"return_url": "https://www.example.com/order/EXAMPLE001",
"transactions": [
{
"payment_method": "credit-card",
"capture_mode": "delayed",
"expiration_period": "P7D"
}
],
"customer": {
"merchant_customer_id": "123456789",
"email_address": "user@example.com"
}
}'You can't capture a delayed transaction manually. To prevent part or all of the automatic capture, void the amount you don't want to capture before the period ends.
Check the result
After a capture, retrieve the order or wait for the webhook to confirm the new status.