Authorize (Hold) and Capture
The Auth and Capture use case explained in this document is limited schemes only. If you have further questions, please contact your Maya Relations Manager or email [email protected].
A use case that will allow you as a merchant to request a hold for a certain amount on your customer’s card to their card’s issuing bank, to temporarily lock the funds for that particular payment and then capture it later once fulfilled.
Use cases where you can use Authorize (Hold) & Capture:
- Authorize the amount first but only capture the funds once you've shipped the physical goods.
- Authorize the amount at the start of a free trial and then capture the funds at start of subscription.
- Perform a manual fraud review before capturing the funds and fulfilling the order.
How Authorize (Hold) and Capture works in Maya
Authorize (Hold) and Capture use case is currently supported in Maya Checkout, Maya Card Payment Vault. Contact your Maya Relationship Manager if you opt to enable this capability.
Clearing or posting the authorized payments to the cardholder’s account balance may vary, depending on the Card Schemes rules and Issuing Bank process. This includes:
- Releasing of the excess on hold amount, when authorized amount is greater than the captured amount.
- Crediting of refunds to the customer’s account for the refunded capture payments.
Issuing banks will hold the authorized amount from your customer’s card, not until you send a request to void the authorization or it has exceeded the holding period.
When authorization exceeded the holding period, dropping or releasing the on hold amount is up to the rules and processes of the issuing bank.
Authorization Types and Holding Period
Authorization holding periods and amount that can be captured may vary per authorization type. See the table below for a high level overview:
| authorizationType | Amount to capture | Holding Period |
|---|---|---|
NORMAL | less than or equal to the authorized amount | 6 days |
FINAL | equal to the authorized amount | 6 days |
PREAUTHORIZATION | less than or equal to the authorized amount | 6 or 29 days* see more details |
Keep in mind
Authorizations past their corresponding hold period that do not have successful captures, or not voided, will result to the authorization hold being dropped.
In issuing banks, on hold funds will be released and made available again for spending by the cardholder when authorization hold is dropped.
Limitations
The following features/capabilities are NOT supported in the current implementation in Maya:
- Incremental authorizations
- Extension of authorization holding period via API.
- Amend (to add or reduce) the authorization amount
- Capture an amount that is greater than the authorized amount.
1 Create a Hold or an Authorization
To create an authorization, you need to add and set the authorizationType field on the request body you will be sending to Checkout and Vault endpoints.
authorizationType field is required to treat the request as authorization, applying authorization processing logic and rules (such as holding period).
NORMAL
Holding period: 6 days
A type of authorization request that can be captured and cleared for amounts less than or equal to the authorization amount.
FINAL
Holding period: 6 days
An authorization request indicating that the amount is final. This type of authorization can only be captured and cleared for amounts equal to the authorization amount.
PREAUTHORIZATION
Holding period: varies
A type of authorization request that can be captured and cleared for amounts less than or equal to the authorization amount. On certain conditions, preauthorizations have longer hold periods than normal authorizations. See Authorization Hold Period below for each supported card schemes.
| Schemes | Holding Period |
|---|---|
| MasterCard | 29 days |
| Visa | 29 days for Lodging (e.g. hotels, resorts, lodging reservation systems), Vehicle Rental, Cruise Lines6 days for merchants not included above. |
| JCB | 6 days |
Maya currently does NOT support amending the amount of an authorization
Authorization State
Various payment results are possible such as failed due to authentication, account validity, request, and authorization hold expiry. The standing of an authorization can be identified by the payment state.
During Creation and Authentication
During this phase, authentication (such as 3DS) and generation of tokens is being done prior to the processing of authorization.
| State | Webhook | Description |
|---|---|---|
PENDING_TOKEN | Not applicable | This is the initial state of an authorization when created. No hold or movement of funds during this state. |
PENDING_PAYMENT | Not applicable | This is when checkout page or payment form is loaded. Waiting for the user to input card details / wallet details. |
FOR_AUTHENTICATION | Not applicable | When the payment credentials were submitted and user is redirected to the 3DS page |
AUTHENTICATING | Not applicable | When the 3DS authentication is on going |
PAYMENT_EXPIRED | Not applicable | If user was not able to provide payment card details or was not able to complete the 3DS authentication at a given time. |
AUTH_FAILED | Not applicable | When user has failed the authentication process. |
AUTH_SUCCESS | Not applicable | When user has completed the authentication process. |
During Processing
Authorization will proceed to this phase when the authorization standing has transitioned to AUTH_SUCCESS during creation and authentication phase.
Authorizations can be voided, but not refunded.
| State | Webhook | Description |
|---|---|---|
PAYMENT_PROCESSING | Not applicable | This is when the authorization has been sent for processing and request has sent to the issuing bank via the schemes. |
PAYMENT_FAILED | Not applicable | When the transaction did not pass the validation checks. |
AUTHORIZED | AUTHORIZED | A state when a hold was successfully placed on the funds of the customer’s Maya account |
CAPTURE_HOLD_EXPIRED | Not applicable | This is when the authorization has exceeds the authorization holding period. |
VOIDED | Not applicable | The state when the request to void the authorization was successfully done. |
Authorizations will be left in
AUTHORIZEDstate when it past their corresponding hold period that do not have successful captures, or not voided. When captured, expired authorization will transition toCAPTURE_HOLD_EXPIREDstate.
2 Capture the Authorization
To capture an authorization, you may call the /payments/v1/payments/{paymentId}/capture endpoint, providing the paymentId acquired during authorization.
You can only capture an authorization in either AUTHORIZED or CAPTURED states, otherwise capture attempts will fail.
Maya currently does NOT support capturing an amount greater than the authorized amount.
Authorization State
Upon successful capture, the authorization standing will be transitioned to CAPTURED.
Keep in mind
The first successful capture attempt of an
AUTHORIZEDauthorization will transition the state toCAPTURED. Additional captures can be done while on this state.
At11:59PMof the day the first Capture was made the payment will transition toDONE.
| State | Webhook | Description |
|---|---|---|
CAPTURED | PAYMENT_SUCCESS | This is when the authorization has been successfully captured. Additional captures can be done while on this state. |
DONE | Not applicable | Final state of a captured authorization where succeeding captures can no longer be done. |
Capture Payment State
Capturing an authorization will create a new capture payment record, for each capture attempt, that would transition to the following payment states.
| State | Webhook | Description |
|---|---|---|
PENDING_PAYMENT | Not applicable | This is the initial state of payment transaction when created. |
PENDING_PROCESSING | Not applicable | When validation checks are being done. |
PAYMENT_SUCCESS | PAYMENT_SUCCESS | When the transaction pass the validation checks and has been processed. |
PAYMENT_FAILED | PAYMENT_FAILED | When the transaction did not pass the validation checks. |
VOIDED | Not applicable | The state when the request to void the payment was successfully done. |
REFUNDED | Not applicable | The state when payment has been refunded. |
Void an Authorization
When an authorization is cancelled, a void request can be sent to release the on-hold amount from your customer’s account / card.
You can only void an AUTHORIZED authorization or as long as:
- Authorization is not past the hold period (not in
CAPTURE_HOLD_EXPIREDstate) - No capture payment is done yet (not in
CAPTUREDorDONEstate) - Authorization is not in
VOIDstate. If an authorization has already been voided, succeeding cancellation attempts will fail.
Upon voiding, authorization will transition to VOIDED state.
Void and Refund a Capture Payment
When to Void
- Capture payments in
PAYMENT_SUCCESSstate can only be voided on the day it was processed, or before the12amcut-off time. Upon voiding, capture payment will transition toVOIDEDstate.
Keep in mind
When all capture payments are voided, authorization with
CAPTUREDstate will be reverted back toAUTHORIZEDstate.
When to Refund
- Capture payments in
PAYMENT_SUCCESSstate can be refunded after12amcut-off time. Upon refund, capture payment will transition toREFUNDEDstate.
Note that Authorizations will be left in
DONEstate even after Capture Payment has successfully refunded.
Create webhooks for real-time payment status
It is highly recommended to implement webhooks to manage the payment status updates. For more information, refer to Webhooks for Payment Solutions.
Updated 9 days ago