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

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:

ValueDescription
NORMALIndicates a Normal Authorization transaction, this authorization request can be captured and cleared for amounts less than or equal to the authorization amount.
FINALIndicates 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).
PREAUTHORIZATIONIndicates 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:

SchemeNormal Authorization Holding PeriodFinal Authorization Holding PeriodPreauthorization Authorization Holding Period
MasterCard6 days6 days29 days
Visa6 days6 days6 days / 29 days*
JCB6 days6 days6 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

State Transition Diagram: Capture Payment Statuses

Transition rules

State Transition Diagram: Manual Capture Authorization Payment Statuses

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.