Authorize (Hold) and Capture Payments in Maya Checkout

Overview

Some businesses prefer to authorize a payment first and then capture it later, rather than charging immediately. This gives you flexibility to:

• Verify funds before providing goods or services
• Delay the final charge until delivery or confirmation
• Cancel the authorization if the order cannot be fulfilled

This guide walks you through how to implement Auth and Capture in Maya Checkout using the REST API.

---

Before You Begin

Before you start integrating, learn more About Maya Checkout and understand the key concepts for a successful integration.

Prerequisites

Confirm that the following are ready before you start:

• Completed Maya Checkout Onboarding:
  • For direct-to-production commitment, follow the Getting Started in Maya Checkout (Maya Business Manager)
  • For sales-assisted, follow the Getting Started in Maya Checkout (Maya Manager 1.0)
• Requested Authorize (Hold) and Capture feature activation
• Access to Maya Business Manager or Maya Manager 1.0
• API Keys: Public Key (pk-...) and Secret Key (sk-...)
• Correct environment setup (Sandbox or Production)
• A Webhook endpoint to listen for payment updates

---

How Auth and Capture Works

When a payment is authorized, the issuing bank places a hold on the customer’s card for the authorized amount.

Funds are released if:

• You void the authorization, or
• The hold period expires without a capture.

Card scheme and issuing bank rules ultimately control how holds, releases, and refunds are processed.

Enabling Authorize (Hold) and Capture in Maya Checkout

The Authorize (Hold) and Capture feature is available in Maya Checkout for card payments only.

To use Authorize (Hold) and Capture features in Maya Checkout:

• Request activation from your Maya Relationship Manager before starting integration.
• Once approved, implement the Authorize (Hold) and Capture flow by following this guide.

Authorization and Capture Intents

When using Authorize (Hold) and Capture in Maya Checkout, two types of intents are involved:

• Authorization Intent
  • Represents the hold placed on the customer’s funds after completing Maya Checkout.
  • Each authorization intent has its own unique id.
• Capture Intent
  • Represents the capture transaction tied to a specific authorization intent.
  • Each capture intent also has a unique id.

Key Rules for Capture Intents

You can create multiple capture intents for a single authorization intent, provided that:

• All captures are created on the same day as the first successful capture attempt.
• The total captured amount does not exceed the authorized amount.

Supported Authorization Types in Maya Checkout

You must specify the authorization type by setting the authorizationType field in your request.
Authorization rules differ in terms of capture amount and hold period.

PREAUTHORIZATION hold periods:

Under certain conditions, preauthorizations have longer hold periods than normal authorizations.

If an authorization is not captured or voided within the hold period, the issuing bank will automatically drop the hold and release the funds.

Limitation

Maya Checkout currently does not support:

• Incremental authorizations
• Extending hold periods via API
• Amending the authorization amount
• Capturing more than the authorized amount

---

Implementing Authorize (Hold) and Capture in Maya Checkout

Step 1: Build Your Integration

1.1. Create Your Checkout Button

• Add a Checkout button where your customers will start the payment process.
• The button should trigger a call to the Create Checkout API.

1.2. Prepare Your Response Pages

• Prepare dedicated result pages to show request outcomes (e.g., success, failure, cancellation).
• Host these pages in your system.
• Use these page URLs in the redirectUrl object when creating a checkout.

This ensures customers are always redirected back to your platform with clear feedback on their payment status.

Step 2: Create an Authorization Intent

2.1 Prepare the Checkout request

When a customer clicks the Checkout button:

• Build your request following the Create Checkout API specifications
• Make sure to include:
  • all required fields
  • authorizationType (NORMAL/ FINAL / PREAUTHORIZATION) to create an authorization intent instead of a one-time payment
  • redirectUrl for your hosted response pages

2.2 Call the Create Checkout API

• Send a POST request to /checkout/v1/checkouts
• Receive checkoutId (the paymentId) and redirectUrl from Maya

2.3 Redirect to Maya Checkout

• Use the redirectUrl from the response to send your customer to the Maya-hosted checkout page.
• Checkout sessions are valid for 1 hour. If expired, generate a new checkout request.

Step 3: Capture the Authorized Transaction

3.1 Monitor Authorization Status

• After the customer completes checkout, the authorization intent transitions to AUTHORIZED state.
• Maya sends a webhook event confirming authorization.
• See Understanding Payment Statuses in Maya Checkout to learn how payment statuses work and how they transition in Maya Checkout

3.2 Create a Capture Intent

• Endpoint: POST /payments/v1/payments/{checkoutId}/capture
• Include the paymentId from Step 2.2: Call the Create Checkout API
• Response confirms the capture result

Capture can only proceed once the status is AUTHORIZED.

When doing Multiple Captures:

• The first successful capture will transition the authorization intent to the CAPTURED state.
• Additional captures can be created while the authorization intent is in the CAPTURED state.
• At 11:59 PM of the day the first Capture was made, the authorization intent will transition to DONE (final state), where succeeding captures can no longer be done.

When Capturing Expired Authorizations:

• If an authorization is not captured or voided before its hold period expires, it remains in AUTHORIZED but can no longer be captured
• Once a capture is attempted on an expired authorization, the authorization intent transitions to CAPTURE_HOLD_EXPIRED
• The request will fail and return the error PY0103 Payment is already expired

Step 4: Monitor Real-Time Transaction Events

Always validate the transaction outcome and reconcile the order status in your system with the webhook notification or GET Payment results.

4.1 Recommended: Use Webhooks

Webhooks notify your system of events (e.g., payment success, failure, cancellation).

To get started with webhooks, see Configuring Your Webhook for Maya Checkout.

4.2 Fallback: Retrieve Transaction Status

If webhooks fail (e.g., network issues), use these APIs:

• GET /payments/v1/payments/{paymentId} → Retrieve by payment ID
• GET /payments/v1/payment-rrns/{rrn} → Retrieve by request reference number
• GET /payments/v1/payments/{paymentId}/status → Retrieve payment status

---

Endpoints

By now, you should understand the essentials of integrating Maya Checkout, including:

• The core requirements to authorize and capture payments
• Which endpoints to call during the authorize and capture flow
• When to use each endpoint
• Which API key (Public or Secret) is required

The table below summarizes the most relevant endpoints for a standard Maya Checkout integration.

---

FAQs

Q: My transaction in Sandbox keeps failing. How can I fix this?

Answer:

• Check that your code follows the required steps
• Review the Sandbox Health page to confirm service availability
• If the service is up, retrieve the error code and search the Maya Developer Hub for troubleshooting guides

Q: Why am I getting timeouts in Sandbox?

Answer:

• First, check the Sandbox Health page
• If the service is operational but issues persist, escalate via the Support Page

Q: Can I extend a hold period via API?

A: No. Hold periods are fixed by the card scheme or issuing bank and cannot be extended programmatically.

Q: Can I capture more than the authorized amount?

A: No. Capture requests must be less than or equal to the originally authorized amount.

Q: Can I perform multiple captures for a single authorization?

A: Yes. Multiple partial captures are supported, as long as the total captured amount does not exceed the original authorization and multiple captures happen on the same day.

Q: What happens if I don’t capture BEFORE the hold expires?

A: The issuing bank automatically releases the hold, and the reserved funds become available to the customer again.

Q: What happens if I capture AFTER the hold expires?

A: If you try to capture a payment after the authorization hold has expired, the request will fail and return the error PY0103: Payment is already expired. The attempt will also trigger the transition of the Authorization intent to CAPTURE_HOLD_EXPIRED.

---

Next Steps

You have successfully implemented Maya Checkout to authorize payments first and capture them later. To strengthen your integration and prepare it for production, we recommend exploring the following:

1. Understand Payment Statuses
   • Learn how Maya Checkout payment statuses work and how they transition, so you can correctly track transactions end-to-end. See Understanding Payment Statuses in Maya Checkout
2. Set Up Webhooks
   • Configure webhooks to receive reliable, real-time payment updates. See Configuring Your Webhook for Maya Checkout.
3. Manage Voids and Refunds
   • Review the best practices in Managing Voids and Refunds in Maya Checkout to handle cancellations and refunds properly.
4. Handle Errors Effectively
   • Go through Understanding Errors in Maya Checkout to see error types, decline codes, and recommended handling strategies.
5. Test Your Integration
   • Follow the Testing and Validating Your Maya Checkout Integration guide to ensure your implementation behaves correctly in Sandbox before going live.