Authorization and Hold Help

General
1

What steps are involved in setting up an authorization hold and subsequent capture?

2

To set up an authorization hold and subsequent capture in Maya Checkout:

  1. Enable the feature: Contact your Maya Relationship Manager to activate the Authorize (Hold) and Capture capability for your account.

  2. Prepare your integration: Ensure you have:

    • Valid API keys (Public and Secret)
    • A configured sandbox or production environment
    • Redirect URLs for success, failure, and cancellation pages

  3. Create an authorization request: When initiating a payment, include the authorizationType field in your Create Checkout request:

    • NORMAL: Capture up to the authorized amount (max 6-day hold)
    • FINAL: Must capture the full authorized amount (6-day hold)
    • PREAUTHORIZATION: For industries like travel or rentals; hold periods vary by card scheme (up to 29 days for Visa/MasterCard in specific cases)

  4. Redirect the customer: Send the customer to the Maya-hosted checkout page using the redirectUrl returned in the API response. The session expires after 1 hour.

  5. Wait for authorization confirmation: After the customer completes payment, the transaction status becomes AUTHORIZED. Monitor this via:

    • Webhook event: AUTHORIZED
    • Or by polling the GET Payment Status endpoint

  6. Capture the payment: Once authorized, call the /payments/v1/payments/{paymentId}/capture endpoint to capture funds. You may:

    • Perform a full capture (equal to authorized amount)
    • Perform multiple partial captures on the same day, as long as the total does not exceed the authorized amount

  7. Handle expiration: If not captured within the hold period (6 or 29 days), the authorization transitions to CAPTURE_HOLD_EXPIRED and can no longer be captured. Funds are automatically released by the issuing bank.

Important limitations:

  • You cannot amend the authorized amount
  • You cannot extend the hold period via API
  • You cannot capture more than the authorized amount
  • Captures must occur on the same day as the first successful capture to remain valid

After the first capture, the authorization transitions to CAPTURED. At 11:59 PM (PH time) on the capture day, it becomes DONE, and no further captures are allowed.

For Sandbox concerns and other technical implementation inquiries, please get in touch with us via:

  • Sandbox Health Page: Check real-time service status updates.
  • Maya Developer Hub Service Desk: File
    a ticket in Sandbox.

To Know More:

We value your input and would love to hear your insights. Please submit you feedback here.