Pre-authorize and capture

Most payments are a sale: the amount is charged as soon as your customer pays. With a pre-authorization, the card issuer only reserves the amount on your customer's card. You receive the money once you capture the payment. Until then, you can still void the part you no longer need.

Use a pre-authorization when the final amount or the delivery isn't certain at checkout, for example for hotel bookings, rentals or orders that ship later.

Card payments support pre-authorizations. See Payment methods for the other payment methods that support them.

Capture modesCopy Anchor Link

Set capture_mode on the transaction to choose what happens after your customer authorizes the payment.

Create a pre-authorizationCopy Anchor Link

Create an order with a credit-card transaction and set capture_mode to manual:

curl https://api.prod.smartpay.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 10000,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example card authorization",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "transactions": [
      {
        "payment_method": "credit-card",
        "capture_mode": "manual",
        "expiration_period": "P7D"
      }
    ],
    "customer": {
      "merchant_customer_id": "123456789",
      "email_address": "user@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "100 Main St",
      "postal_code": "SW1A 0AA",
      "city": "London",
      "country": "GB",
      "locale": "en",
      "phone_numbers": ["+441234566788"],
      "ip_address": "192.168.0.1"
    }
  }'

Redirect your customer to the payment_url of the transaction, as with any hosted payment page payment. In your own checkout, store the card in the vault and authenticate the transaction instead.

After your customer authorizes the payment, the transaction is reserved but not yet captured. Retrieve the order and check the transaction before you capture:

{
  "id": "6bf8a727-bef2-4420-8d41-af82f6f19f3d",
  "status": "completed",
  "transactions": [
    {
      "id": "59f5866a-c216-472e-b803-8a4e83c4578a",
      "payment_method": "credit-card",
      "capture_mode": "manual",
      "is_capturable": true,
      "status": "accepted"
    }
  ]
}

The response is shortened. is_capturable is true while you can still capture the transaction. To capture or void it, you need the order ID and the transaction ID.

While the amount is only reserved, the transaction has status accepted and the order is already completed: capturing doesn't change the order status. The transaction object will display the chosen capture_mode.

Expiration periodCopy Anchor Link

expiration_period is an ISO 8601 duration, such as PT30M (30 minutes) or P7D (7 days). It's optional, but we recommend setting it:

• Without it, the default of your project applies. For cards, the default is 30 minutes.
• Once the transaction has expired, you can't capture it anymore.
• With capture_mode set to delayed, the payment is captured automatically when the period ends.

CaptureCopy Anchor Link

A capture turns the pre-authorization into an actual payment: the reserved funds move from your customer's card to you. Capture the full amount that was authorized, or a partial amount, for example when an item is out of stock or a service costs less than expected.

Captures work on transactions created with capture_mode set to manual.

Capture the full amountCopy Anchor Link

Send a POST request to the captures endpoint of the transaction. No request body is needed:

curl https://api.prod.smartpay.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/captures/ \
  --user "$API_KEY:" \
  --request POST

The full authorized amount is captured. See Capture the full amount in the API reference.

Capture a partial amountCopy Anchor Link

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.prod.smartpay.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"
  }'

The remaining € 75.00 stays reserved: capture it later, or void it to release it to your customer. The captures together can't exceed the authorized amount. See Capture a partial amount in the API reference.

Capture automaticallyCopy Anchor Link

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

VoidCopy Anchor Link

A void cancels all or part of a pre-authorization. The voided amount is released to your customer and can't be captured anymore. Void the amount you no longer need, for example when your customer cancels the order or part of it.

Voids work on transactions created with capture_mode set to manual or delayed, as long as they haven't been captured yet. To return money after a capture, create a refund instead.

Void the full amountCopy Anchor Link

Send the full remaining authorized amount, in the smallest currency unit, to the voids/amount endpoint. This example releases a € 100.00 pre-authorization completely:

curl https://api.prod.smartpay.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/voids/amount/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 10000,
    "description": "Order cancelled"
  }'

The full remaining authorized amount is released. See Void an amount in the API reference.

Void a partial amountCopy Anchor Link

Send the amount to void, in the smallest currency unit, and optionally a description to the same voids/amount endpoint. This example reduces a € 100.00 pre-authorization by € 25.00:

curl https://api.prod.smartpay.gingerpayments.com/v1/orders/$ORDER_ID/transactions/$TRANSACTION_ID/voids/amount/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 2500,
    "description": "Void 25.00 of the full 100.00"
  }'

The pre-authorization is reduced to € 75.00, which you can still capture. See Void an amount in the API reference.

Void, capture or refund?Copy Anchor Link

Check the resultCopy Anchor Link

A capture and a void are orders of their own, linked to the original order. After a capture or a void, wait for the webhook or retrieve the order to confirm the new status. See Confirm the payment.