Authorize (Hold) and Capture

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:

authorizationTypeAmount to captureHolding Period
NORMALless than or equal to the authorized amount6 days
FINALequal to the authorized amount 6 days
PREAUTHORIZATIONless than or equal to the authorized amount6 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).


authorizationType: 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.


authorizationType: 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.


authorizationType: 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.

SchemesHolding Period
MasterCard 29 days
Visa29 days for Lodging (e.g. hotels, resorts, lodging reservation systems), Vehicle Rental, Cruise Lines

6 days for merchants not included above.
JCB6 days

⚠️ Maya currently does NOT support amending the amount of an authorization

Sample Checkout Payload

Click to see sample
{
  "authorizationType": "NORMAL",
  "totalAmount": {
    "value": 100,
    "currency": "PHP",
    "details": {
      "discount": 0,
      "serviceCharge": 0,
      "shippingFee": 0,
      "tax": 0,
      "subtotal": 100
    }
  },
  "buyer": {
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "birthday": "1995-10-24",
    "customerSince": "1995-10-24",
    "sex": "M",
    "contact": {
      "phone": "+639181008888",
      "email": "[email protected]"
    },
    "shippingAddress": {
      "firstName": "John",
      "middleName": "Paul",
      "lastName": "Doe",
      "phone": "+639181008888",
      "email": "[email protected]",
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH",
      "shippingType": "ST" // ST - for standard, SD - for same day
    },
    "billingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    }
  },
  "items": [
    {
      "name": "Canvas Slip Ons",
      "quantity": 1,
      "code": "CVG-096732",
      "description": "Shoes",
      "amount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      },
      "totalAmount": {
        "value": 100,
        "details": {
          "discount": 0,
          "serviceCharge": 0,
          "shippingFee": 0,
          "tax": 0,
          "subtotal": 100
        }
      }
    }
  ],
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "requestReferenceNumber": "1551191039",
  "metadata": {}
}

Sample Vault Payload

Click to see sample
{
  "authorizationType": "NORMAL",
  "paymentTokenId": "zHaqT073VaBlLkEelWUvFOXOQPIyNSxqiyod3KfzFDVVYwVYiWauCOorsuIXQ6THsMrVVdDEPCT11vdW2PdvoaISmrfXoWRhWgwRUQyyX0hjV6sjVZ3DLmkltdUEUz6ZsFue9ka9otYM24xbrS6F7zBRYuC8W6m586G3745hg",
  "totalAmount": {
    "amount": 100,
    "currency": "PHP"
  },
  "buyer": {
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "birthday": "1995-10-24",
    "customerSince": "1995-10-24",
    "sex": "M",
    "contact": {
      "phone": "+639181008888",
      "email": "[email protected]"
    },
    "shippingAddress": {
      "firstName": "John",
      "middleName": "Paul",
      "lastName": "Doe",
      "phone": "+639181008888",
      "email": "[email protected]",
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH",
      "shippingType": "ST" // ST - for standard, SD - for same day
    },
    "billingAddress": {
      "line1": "6F Launchpad",
      "line2": "Reliance Street",
      "city": "Mandaluyong City",
      "state": "Metro Manila",
      "zipCode": "1552",
      "countryCode": "PH"
    }
  },
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success",
    "failure": "https://www.merchantsite.com/failure",
    "cancel": "https://www.merchantsite.com/cancel"
  },
  "requestReferenceNumber": "1551191039",
  "metadata": {}
}

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.



StateWebhookDescription
PENDING_TOKENNot applicableThis is the initial state of an authorization when created. No hold or movement of funds during this state.
PENDING_PAYMENTNot applicableThis is when checkout page or payment form is loaded. Waiting for the user to input card details / wallet details.
FOR_AUTHENTICATIONNot applicableWhen the payment credentials were submitted and user is redirected to the 3DS page
AUTHENTICATINGNot applicableWhen the 3DS authentication is on going
PAYMENT_EXPIREDNot applicableIf user was not able to provide payment card details or was not able to complete the 3DS authentication at a given time.
AUTH_FAILEDNot applicableWhen user has failed the authentication process.
AUTH_SUCCESSNot applicableWhen 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.



StateWebhookDescription
PAYMENT_PROCESSINGNot applicableThis is when the authorization has been sent for processing and request has sent to the issuing bank via the schemes.
PAYMENT_FAILEDNot applicableWhen the transaction did not pass the validation checks.
AUTHORIZEDAUTHORIZEDA state when a hold was successfully placed on the funds of the customer’s Maya account
CAPTURE_HOLD_EXPIREDNot applicableThis is when the authorization has exceeds the authorization holding period.
VOIDEDNot applicableThe state when the request to void the authorization was successfully done.

ℹ️ Authorizations will be left in AUTHORIZED state when it past their corresponding hold period that do not have successful captures, or not voided. When captured, expired authorization will transition to CAPTURE_HOLD_EXPIRED state.


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 AUTHORIZED authorization will transition the state to CAPTURED. Additional captures can be done while on this state.

At 11:59PM of the day the first Capture was made the payment will transition to DONE.



StateWebhookDescription
CAPTUREDPAYMENT_SUCCESSThis is when the authorization has been successfully captured. Additional captures can be done while on this state.
DONENot applicableFinal 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.



StateWebhookDescription
PENDING_PAYMENTNot applicableThis is the initial state of payment transaction when created.
PENDING_PROCESSINGNot applicableWhen validation checks are being done.
PAYMENT_SUCCESSPAYMENT_SUCCESSWhen the transaction pass the validation checks and has been processed.
PAYMENT_FAILEDPAYMENT_FAILEDWhen the transaction did not pass the validation checks.
VOIDEDNot applicableThe state when the request to void the payment was successfully done.
REFUNDEDNot applicableThe 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_EXPIRED state)
  • No capture payment is done yet (not in CAPTURED or DONE state)
  • Authorization is not in VOID state. 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_SUCCESS state can only be voided on the day it was processed, or before the 12am cut-off time. Upon voiding, capture payment will transition to VOIDED state.

🧠 Keep in mind

When all capture payments are voided, authorization with CAPTURED state will be reverted back to AUTHORIZED state.

When to Refund

  • Capture payments in PAYMENT_SUCCESS state can be refunded after 12am cut-off time. Upon refund, capture payment will transition to REFUNDED state.

ℹ️ Note that Authorizations will be left in DONE state 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.