Manual Capture
Capturing of payments can be delayed once extra conditions are met. Conditions such as "order is delivered" for a food delivery or upon completing a stay at a hotel.
Maya Business Checkout and Vault supports such use case. To avail this feature for your business, contact your Maya Relationship Manager for more details.
Payment Flow
Sequence Diagram for Manual Capture
How to manually capture payments
The important field that should be set on the request body on either of the following endpoints Create Checkout or Create Payment of Vault is authorizationType
The authorizationType field can have either of the following values:
| Value | Description |
|---|---|
| NORMAL | Indicates a Normal Authorization transaction, this authorization request can be captured and cleared for amounts less than or equal to the authorization amount. |
| FINAL | Indicates a Final Authorization transaction, this authorization request can be only be captured and cleared for amounts equal to the authorization amount (i.e., partial captures are not supported). |
| PREAUTHORIZATION | Indicates a Preauthorization transaction, this authorization request can be captured and cleared for amounts greater than (not yet supported), less than, or equal to the authorization amount. On certain conditions, a preauthorization may have longer hold periods than normal authorizations. Please refer to Authorization Hold Periods for more details. |
Sample Body
Checkout
{
"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": {}
}
Vault
{
"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 Hold Periods
A successful Authorization is saved (held) until the transaction is not past its hold period. Authorizations past their corresponding hold period that do not have successful captures, or were not voided, will result to the authorization hold being dropped.
Payments will be left in AUTHORIZED state. Attempting to capture will transition to CAPTURE_HOLD_EXPIRED
The following table summarizes the authorization hold periods defined depending on certain conditions:
| Scheme | Normal Authorization Holding Period | Final Authorization Holding Period | Preauthorization Authorization Holding Period |
|---|---|---|---|
| MasterCard | 6 days | 6 days | 29 days |
| Visa | 6 days | 6 days | 6 days / 29 days* |
| JCB | 6 days | 6 days | 6 days |
For Visa, pre-authorized transactions can have longer hold periods (29 days) if the following conditions are met:
Merchant falls under one of the ff categories:
- Lodging (e.g. hotels, resorts, lodging reservation systems)
- Vehicle Rental
- Cruise Lines
Capture API
API Reference: Capture Payments
Captures an AUTHORIZED or CAPTURED payment. This will create a new payment record. This payment record can be voided or refunded.
State Transition Diagram: Capture Payment Statuses
Transition rules
State Transition Diagram: Manual Capture Authorization Payment Statuses
Capture
The first capture of an AUTHORIZED payment will transition the state to CAPTURED. Additional captures can be done while on this state.
At 11:59 PM of the day the first Capture was made the payment will transition to DONE. Captures can no longer be done at this state.
Voiding Authorization Payment
Voiding an AUTHORIZED payment will release the capture hold and change the payment state to VOIDED
Void and Refund Captured Payment
Voiding a PAYMENT_SUCCESS Capture payment will change the status to VOIDED.
Voiding all Capture payments of a CAPTURED payment will revert the state to AUTHORIZED. The capture cut-off will no longer apply.
PAYMENT_SUCCESS Capture payments can be refunded after the 12am cut-off time.
Webhooks
AUTHORIZED Payments do not fire the CHECKOUT_SUCCESS webhook.
PAYMENT_SUCCESS Capture Payments fire the the CHECKOUT_SUCCESS webhook.