Place a hold on a payment method

When you create a payment, you can place a hold on an eligible payment method to reserve the funds for a few days and capture them later. The payment will stay in “Authorized” status during this period.

Authorization helps guarantee the payment amount by holding it on the customer’s payment method. A typical use case is that hotels would normally ask the guest to authorize a deposit at arrival to cover any potential additional charges and then capture the actual charges during checkout. During the whole stay, the funds will be held on the guest’s credit card.

You should capture funds as soon as you confirm the final charge with your customer. You can capture less than the original authorization amount with a partial capture, but you cannot capture more.

Important: Do not leave authorizations open indefinitely. The issuing bank or card scheme may reject your capture request if an authorization is left open for several months, and you will not receive the funds. Even if the funds can settle, you may receive disputes due to improper authorization handling.

Please note that placing a hold is currently only supported for cards (including Apple Pay and Google Pay) and Klarna payment methods and the authorization expiry window differs by payment method:

• Card payments: Most card schemes allow you to place a hold on a standard payment for 7 days. You can request extended authorization periods for the following cases (see more details in step 2):
  • Visa: Up to 30 days (For POS payments, Visa limits the authorization window to 5 days. The extended 30-day window is only reserved for cruise, lodging, or vehicle rental businesses.)
  • Mastercard: Up to 30 days
• Klarna: Up to 28 days

Step 1: Define the capture mode of your payment

By default, we will automatically capture your payment to request the funds immediately at the end of a successful payment flow. To indicate that you want to delay the capture, specify auto_capture as false when you are confirming the PaymentIntent with the eligible payment method. This parameter instructs us to only authorize the amount but not capture it in the real-time payment flow.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_tkZsvKMHzf37yTFqlztZ5NYEAvD/confirm \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "payment_method": {
6      "card": {
7        "cvc": "123",
8        "expiry_month": "12",
9        "expiry_year": "2030",
10        "name": "John Doe",
11        "number": "4111111111111111",
12        "number_type": "PAN"
13      }
14    },
15    "payment_method_options": {
16      "card": {
17        "auto_capture": false
18      }
19    },
20    "request_id": "285ecfc8-4c53-4543-8b9b-87d75e8666b9"
21  }'

(Optional) Step 2: Request extended authorization window

By default, we will perform standard authorization requests for your card payments. For Visa and Mastercard payments, you can further specify the authorization_type as pre_auth to extend the hold period.

Please note that card schemes and issuers, may also have their own rules on authorization expiry. Some issuers may expire an authorization before or after the official scheme expiry period has been reached. Often this allows you to still capture the funds successfully even when the authorization has expired. However, there can be a fee for late capture or an increase in the interchange fee and the risk of cardholder chargebacks may increase. Therefore, we recommend that you capture the funds within the official authorization expiry period.

We recommend that you only use pre-authorization if you need to place the hold for more than 7 days, as you will incur higher scheme fees when using pre-authorization:

• Visa: 2 bps
• Mastercard: 5 bps

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_tkZsvKMHzf37yTFqlztZ5NYEAvD/confirm \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "payment_method": {
6      "card": {
7        "cvc": "123",
8        "expiry_month": "12",
9        "expiry_year": "2030",
10        "name": "John Doe",
11        "number": "4111111111111111",
12        "number_type": "PAN"
13      }
14    },
15    "payment_method_options": {
16      "card": {
17        "auto_capture": false,
18        "authorization_type": "pre_auth"
19      }
20    },
21    "request_id": "285ecfc8-4c53-4543-8b9b-87d75e8666b9"
22  }'

Step 3: Capture the funds

When you are ready to request the funds, you can instruct the capture request for your payment. You can capture less than the original authorized amount by specifying the actual figure in your request.

1curl -X POST https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_tkZsvKMHzf37yTFqlztZ5NYEAvD/capture \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4-d '{
5  "amount": 100,
6  "request_id": "285ecfc8-4c53-4543-8b9b-87d75e8666b9"
7}'

(Optional) Cancel the payment

If you don’t need to request the funds in the end, you can choose to cancel the payment.