Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Embedded Finance
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Business Account Help Center
API Reference
Back to home
OverviewChoose your payments solutionGet started with payments
Supported currencies
Online payments
Online payments overviewPayment Method Onboarding RequirementGet started with online paymentsHosted Payment Page
Drop-in Element
Embedded Elements
Mobile SDK
Plugins
Native API
Guest user checkoutRegistered user checkoutPlace a hold on a payment method
CancellationsRefunds3D Secure authentication
Network TokenizationDevice fingerprintingMulti-currency pricingError response codes
Automatic Currency Conversion
Payment Links
Invoice integrations
Manage payments
Payment methods
Test and go live
Troubleshooting
Tax filing

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 need to capture the funds before the authorization expires. You can capture less than the original amount, but cannot capture more. If the authorization expires before you capture the funds, the funds are released and the payment status changes to “Cancelled”.

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: By default the authorization expires in 7 days. You can request extended authorization time-periods for the following cases (see more details in step 2):
    • Visa: Up to 31 days for cruise, lodging, or vehicle rental businesses
    • MasterCard: 30 days for all businesses
  • Klarna: 28 days for all businesses

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.

Note:
Shell

(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 to:

  • Visa:
    • Cruise, lodging, or vehicle rental businesses: 31 days
    • Other businesses: 7 days
  • Mastercard: 30 days

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 you to 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
Note:
  • You have to specify the authorization type at the time of creating the payment and you cannot extend the hold period retrospectively
  • If you are integrating via Hosted Payment Page JS, Drop-in or Embedded Elements JS, please refer to the detailed guidance on how to specify authorization type (for embedded elements, please refer to the guidance on the specific element type that you are using)
  • Currently, you cannot specify pre-auth on payments made via Payment Links
Shell

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.

Shell

(Optional) Cancel the payment

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

On this page