Pre-authorizations
Reserve funds on your customer's card first and capture the amount later, for example when you ship the order.
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 within five days
Capture a pre-authorization within five days. After that, the card issuer may cancel the reservation and release the funds to your customer.
Capture modes
Set capture_mode on the transaction to choose what happens after your customer authorizes the payment.
capture_mode | What happens | Capture with the API |
|---|---|---|
| Not set | Sale. The amount is captured immediately. | Not needed |
manual | The amount is reserved until you capture or void it. | Yes, full or partial |
delayed | The amount is reserved and captured automatically at the end of the expiration_period. | No, but you can still void |
Create a pre-authorization
Create an order with a credit-card transaction and set capture_mode to manual:
curl https://api.pay.paytrim.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.
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.
Expiration period
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_modeset todelayed, the payment is captured automatically when the period ends.
Next steps
- Capture the payment, in full or in part.
- Void the payment if you no longer need some or all of the reserved amount.