Understanding Payment Statuses in Maya Checkout

Overview

When integrating Maya Checkout, it’s crucial to understand the payment lifecycle. Each transaction passes through a series of statuses that represent its current state: from creation to completion, expiration, or failure.

Instead of polling the API for updates or relying solely on the synchronous API responses, your system should listen for server-to-server webhook events. This ensures you always receive the final payment status.

This guide covers:

• What each payment status means
• How statuses transition from one to another
• Which webhooks are emitted
• Best practices for handling statuses

Key rule for developers when integrating with Maya Checkout

Always wait for webhook events before updating your order system. Do not rely solely on synchronous responses.

---

Payment Statuses in Maya Checkout

Some statuses are final (irreversible, no further transitions possible) or semi-final (safe for merchants to treat as “paid,” but may still be reversed, voided, or refunded), while other statuses are transient (impermanent or temporary).

Initial & Pending States

These statuses indicate that the payment request/session has been created but not yet completed.
No merchant-side actions are required yet.

Authentication States

At this stage, the payment goes through authentication. No actions from your system are needed at this stage.

Processing State

The transaction is under review by Maya and the issuing bank or e-wallet provider.

Decision and Semi-Final States

These represent the key decision points in the lifecycle.

Final States

These represent irreversible or closed statuses.

---

Payment Lifecycle in Maya Checkout

For One-time Payment Flow

For Authorize (Hold) and Capture Flow

Authorize (Hold) Intent:

Capture Intent:

---

Best Practices for Developers

1. Always Listen to Webhooks

• Do not rely on redirect URLs or synchronous API responses. These may only indicate that the checkout flow was initiated, not the final result.
• Use webhook events as the single source of truth for updating your order system.

2. Handle Semi-Final States with Caution

Some statuses are safe to act on, but can still change later:

• PAYMENT_SUCCESS – funds confirmed but can still be voided or refunded.
• AUTHORIZED – funds held; can still be voided, otherwise capture required.
• CAPTURED – capture request accepted; still reversible by refund.

Your system must be able to process voids or refunds even after you’ve fulfilled the order.

3. Manage Timeouts & Expirations

• PAYMENT_EXPIRED – treat as final; the customer must start a new checkout session.
• CAPTURE_HOLD_EXPIRED – funds were authorized but expired without capture; funds are released from being held

Do not attempt to retry automatically. Instead, prompt the customer to re-initiate payment.

4. Handle Failures Gracefully

• PAYMENT_FAILED – this status always includes an error code or reason.
• Check the errorMessage field in the webhook payload to determine next steps.
• Do not retry automatically unless advised by Maya API documentation.

5. Build for Reliability

• Idempotency: Ensure webhook processing is idempotent; your system should handle duplicate webhook events safely.
• Status Sync: Update your internal status only after receiving and validating the webhook event.
• Logging: Log webhook payloads for debugging and reconciliation.

---

FAQs

Q: Where can I get the payment status?

A: You can get the payment status from multiple sources:

• Webhook notifications, which provide the most reliable and real-time updates
• GET Payment endpoint

Q: Can a payment status change after it is marked as PAYMENT_SUCCESS?

A: Yes. Once a payment is marked PAYMENT_SUCCESS, it is considered semi-final. You can still perform related actions, such as refunds or voids, depending on the payment type and capture flow.

Q: How do statuses differ between one-time payments and authorize/capture?

Answer:

• One-time payment: The status moves directly to PAYMENT_SUCCESS (or PAYMENT_FAILED) once payment is complete.
• Authorize and Capture: The payment may first move to AUTHORIZED before being CAPTURED or VOIDED.

Q: How should I handle unknown or unexpected statuses?

A: If you encounter an unknown status:

1. Log the event for debugging and auditing
2. Retry by checking the payment via the GET Payment endpoint
3. Contact Maya support if the status persists and is not documented

---

Next Steps

You now have a better understanding of the different payment statuses in Maya Checkout and how they move from one state to another. To move forward:

1. Implement Webhook Handling
   • Follow the Configuring Your Webhook for Maya Checkout to set up secure, reliable event handling.
2. Incorporate Status Handling into Your System
   • Update your flow to account for pending, semi-final, and final states.
3. Test with Sandbox Transactions
   • Simulate success, failure, expiration, and reversal scenarios to ensure your system behaves correctly. Follow the Testing and Validating Your Maya Checkout Integration guide.