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:

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).

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.

Schemes	Holding Period
MasterCard	`29 days`
Visa	`29 days` for Lodging (e.g. hotels, resorts, lodging reservation systems), Vehicle Rental, Cruise Lines `6 days` for merchants not included above.
JCB	`6 days`

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

Sample Checkout Payload

POST/checkout/v1/checkouts

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

POST/payments/v1/payments

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.

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

POST/payments/v1/payments/{paymentId}/capture

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.

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_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.

Authorize (Hold) and Capture

Use cases where you can use Authorize (Hold) & Capture: