Authorize and Capture

How Authorize and Capture works in Maya

Authorize and Capture use case is also supported in Payments Processing Platform.

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

How to Integrate

1 Obtain your API Keys

ℹ️ If you already have your API keys and know how to use it, you may proceed to the next step.

The Payments Processing Platform APIs uses API keys to authenticate requests. API keys carry many privileges, your grant or permission to access and integrate with Maya’s endpoints.

Step 1: Prepare your Public GPG Keys to be submitted to Maya. Don’t have keys yet? Learn How

Step 2: Provide email address of the nominated recipient of the API Keys.

Step 3: Credentials and keys will be received via an encrypted email. You should be able to decrypt it using your public and private GPG keys.

📖 Different API keys will be provided for each environment: Sandbox or Production.

Authenticating with our API

Authentication is done via HTTP Basic Authentication. Depending on the API endpoint, the public (pk-....) or secret (sk-....) key must be provided as the username and the password left as blank.

Steps are as follows:

  1. Combine Username and Password (left blank) separated by ‘:’ (colon). If your API key is “pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah”, the resulting string is:
  1. Apply Base64 encoding to the resulting string from Step 1. Using the resulting string from Step 1, the Base64 encoded string will be:
  1. Indicate the authorization method i.e. “Basic” followed by a space then the Base64 encoded string in Step 2. An example is shown below.
Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=

See also: HTTP Basic Auth

2 Create Authorization

🧩 Tips

It is highly recommended that you perform the 3D Secure or 3D Secure 2 (3DS or 3DS2) authentication to increase your success rate and prevent transaction from getting declined by the issuing banks.

You will be responsible for performing the 3D Secure or 3D Secure 2 (3DS or 3DS2) authentication leg, including, but not limited to, integrating with its own or a 3rd party Merchant Plug-in (MPI).

Use this endpoint to request or instruct issuers to hold or reserve the funds from the customer’s account until authorization gets cleared.

Request is similar to Purchase/Sale, with the addition of authorizationType indicating the Authorization Type.

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

A successful authorization will remain authorized until a Capture call is performed, or the authorization hold expires.

📖 Authorization Hold Periods

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.

Funding instrument must be set to indicate the type of source of funds or where payment will be charged. Payments Processing Platform currently supports fundingInstrument: CARD

When card is used, you need to indicate the account type and card type where the transaction should be charged.

(Customer’s account type linked to the card)
(Type of the card used at the point-of-sale)
For E-commerce
Click to see full details

Maya’s Payments Processing Platform supports authorizations for 3D Secure or 3D Secure 2 (3DS or 3DS2) authenticated e-commerce transactions. You may specify the result of the authentication in the threeDSecure object (by providing the verification token) to complete an authenticated transaction.

      "verificationToken": "jqEmJkhI2+SDCAAAAAAJBwAAAAA=",
      "eci": "05",
      "enrolled": "Y",
      "authenticationStatus": "Y"
For Card-present
Click to see full details

Card-present transactions supports the following card entry methods:

  • EMV: Contact Chip (Integrated-Circuit Card)
  • EMV: Contactless Chip (Integrated-Circuit Card)
  • Magnetic Stripe
  • Contactless Magnetic Stripe

📖 EMV (chip-based) transactions

For chip-based requests, the emvIccData contains the Base64 encoded value of the binary TLV chip data read from the card. For example, for the following TLV data:


The resulting emvIccData should be:


Initiator and Intent

You can indicate the initiator and the intent of the transaction in the Straight Payment requests. The value in these fields may be used by Issuers when determining the approval status of an authorization transaction.

ℹ️ Recurring transactions (i.e., transaction.frequencyIndicator = RECURRING)

These transactions will be treated as merchant-initiated transactions, regardless of the value of transaction.initiator.

INITIATOR (transaction.initiator)
Click to see full details

The transaction initiator is the entity that initiated the authorization request. The following initiators are supported by the API:

🧠 Keep in mind

By default, transaction is treated as CONSUMER initiated if initiator was not specified.

CONSUMERDEFAULT Indicates that transaction is consumer initiated (e.g., consumer explicitly purchased an item from the merchant)
MERCHANT Indicates that transaction is merchant initiated (e.g., charging subsequent miscellaneous fees after the original transaction)
INTENT (transaction.intent)
Click to see full details

Transaction intent is a general description of the purpose of the authorization request. The following intents are supported by the API:

🧠 Keep in mind

If intent is not specified, transaction will be, by default, intended for PAYMENT.

PAYMENTDEFAULT Indicates that the authorization request is being done to collect payment from the consumer for goods/services rendered.
VAULTING Indicates that the request intends to store the consumer’s credentials after a successful authorization.

Normally, authorizations with the VAULTING intent are voided/refunded afterwards, as the results are only used for validating the consumer’s credentials.

This value should be set even if the client intends to collect payment from the authorization request as well, as long as the client intends to store the credentials afterwards.

Reference Numbers

The following reference numbers can be set to provide additional tagging for each transaction during reconciliation processes:

In Request Header


A reference number sent by the API caller to tag the transaction in Payments Processing Platform.

In Request Body


A reference number sent by the merchant involved in the transaction.

ℹ️ If the API caller is a merchant, this field can be populated with the same value as the Request-Reference-No, or omitted in favor of the value of Request-Reference-No.

ℹ️ Payment Gateways can use this field to include the reference number sent by their transacting merchant to identify the transaction.


A reference number sent by the sub-merchant involved in a transaction sent by a payment facilitator.

Using Vaulted/Stored Credentials

Vaulted card transaction no longer contains the card security code (CSC). However, Issuers may decline transactions more often due to the lack of a secondary authentication mechanism (since both 3D Secure or 3D Secure 2 (3DS or 3DS2), and CSC validation are no longer performed).

🧩 Tips

Indicate that the credit card information of the transaction came from its storage by setting payer.fundingInstrument.card.vaulted to true.

This will help relax the acceptance requirements of issuers, since it is assumed that you have already previously authenticated the cardholder by different means.

3 Capture Authorization

Call this endpoint to complete the authorization transaction and making it ready to be cleared. You must provide the paymentTransactionReferenceNo of the authorization.

Captured transactions are included at the end of the day’s batch processing for clearing. The cardholder will be billed upon successful clearing of a captured transaction.

Merchants can perform either full or partial captures

You can only capture an authorized or captured transactions, otherwise capture attempts will fail.

Full Captures

You only need to provide the paymentTransactionReferenceNo of the authorization transaction to be captured. Payments Processing Platform will automatically capture the entire value of the transaction.

Partial Captures

You need to provide paymentTransactionReferenceNo and the amount to be captured. You may continue to send partial capture requests until the entire amount for the transaction has been captured.

🚧 Maya currently does NOT support capturing an amount greater than the authorized amount.

Final Capture

Use this endpoint to execute a final capture on a successful Authorization transaction. With this, you can perform either full or partial captures where any remaining uncaptured amount on an authorization will be voided by the schemes and issuer.

⚠️ Final captured transactions can NO longer be captured again afterwards.

Conditional Void

Use this endpoint to void a successful transaction providing the paymentTransactionReferenceNo.

Where paymentTransactionReferenceNo pertains to either:

  • paymentTransactionReferenceNo generated in Authorization requests, or
  • captureTransactionReferenceNo generated for Capture


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 authorization or as long as:

  • Authorization is not past the hold period
  • No capture payment is done yet
  • Authorization is not in yet voided state. If an authorization has already been voided, succeeding cancellation attempts will fail.


You can only void a successful capture payments on the day it was processed, or before the 11:59:59 PM (PH Standard Time) cut-off time. Upon voiding, capture payment will transition to VOIDED state.

ℹ️ In case a response is not received by the API client (e.g., timeout or connectivity error occurred), the client may send a void request with the following fields from the previous purchase request:

  • paymentRequestReferenceNo
  • merchantId
  • amount

However, if paymentRequestReferenceNo is already provided, the fields above are ignored.

Conditional Refund

Successful capture payments can be refunded after the 11:59:59 PM (PH Standard Time) cut-off time.

ℹ️ Keep in mind

Crediting of refunds to the customer’s account for the refunded capture payments may vary, depending on the Card Schemes rules and Issuing Bank process.

Clients can perform either full or partial refunds

Full Refunds

  • You just need to provide the transactionReferenceNo of the transaction to refund the full amount.

Partial Refunds

  • You need to provide transactionReferenceNo and the amount to be refunded. You may continue to send partial refund requests until the entire amount for the transaction has been refunded.

ℹ️ You can do multiple and partial refunds, as long as the total refund amount does not exceed the full amount of the transaction.

⚠️ Transaction retains only up to a period of 90 days in its Sandbox environment and 390 days in its Production environment.

Transactions beyond the above mentioned periods can be processed manually. Your authorized representative may request for a manual refund processing through Maya’s Merchant Aftersales Team ([email protected]).

4 Test your Work

Test your services by simulating transactions in our sandbox environment. You may use the test accounts available in Sandbox Test Credentials and Cards .


Use the Transaction Inquiry endpoints to track and monitor your transactions.