Testing and Validating Your Maya Checkout Integration

Overview

Maya provisioned two separate environments of Maya Checkout, one of which is the sandbox environment intended for integration testing.

The Sandbox environment is designed to help you:

• Optimize and debug your integration.
• Understand how Maya Checkout behaves in real-world flows.
• Ensure your system processes payments, webhooks, and errors correctly—before going live.

Access to Sandbox is granted during onboarding.

---

Before You Test

Make sure you have the following ready:

• Completed Maya Checkout Onboarding
• Access to Maya Manager 1.0 (Sandbox)
• Sandbox API Keys (Public pk-... and Secret sk-...)
• A working non-production setup:
  • Integrated with Maya Checkout APIs
• Able to receive webhooks for payment updates
• Known issues already resolved

---

Testing Scope and Scenarios

What You Can Test in Sandbox

Sandbox supports simulated flows for:

• Payments
  • Card payments (Visa, Mastercard, JCB)
  • Maya Wallet login payments
  • Maya QRPh payments (via Sandbox Maya App)
• Advanced Flows
  • Authorize (Hold) and Capture (for card payments)
  • Voids and Refunds
  • Fraud Protection
  • Payment Facilitator (PayFac) integrations

For QRPh testing, you’ll need the Sandbox Maya App (Android only):

1. Contact your Maya Relationship Manager.
2. Provide: Merchant Name, Merchant ID, and tester details.
3. Receive a private download URL.

What You Cannot Test in Sandbox

Some features are Production-only:

• Payments using:
  • Other e-wallets (GCash, ShopeePay, WeChat, etc.)
  • American Express (Amex) cards
  • QRPh scanning from non-Maya apps
• Settlement reports
• Performance or Load Testing
• Timeout/latency simulations

---

Debugging and Testing

You “own” your Sandbox. This means:

• Your team is responsible for building, debugging, and testing your integration.
• Maya Checkout provides checkout scenarios, but you must design end-to-end test cases that cover your own workflows (e.g., order handling, reconciliation, accounting).

Pro Tips for Developers:

• Always log:
  • API requests & responses
  • Webhook payloads
• Use unique requestReferenceNumber values for every request.
• Test all outcomes: success, failure, cancel, and expiration.
• Review Understanding Errors in Maya Checkout for error handling.

---

How to Test Your Maya Checkout Integration

1. Prepare your non-production application

Ensure that the following IPs and keys are configured correctly in your sandbox:

1.1 Domains and IP Addresses

1.2 Sandbox API Keys

Make sure that your sandbox is using the correct sandbox API keys generated from the Maya Manager 1.0.

2. Verify Your App Setup

• Can call Maya Checkout APIs.
• Can receive webhook events.
• Refer to the integration guides according to your implementation:
  • Accept One-time Payment using Maya Checkout
  • Authorize (Hold) and Capture Payments in Maya Checkout
  • Accept Payments as a Payment Facilitator in Maya Checkout

3. Simulate Checkout Flows

1. Click your Checkout button.
2. Complete the Checkout form with Sandbox test data (cards, accounts).
3. Validate results:

• Redirect page matches the expected status (success, failure, cancel).
• Logs capture API + webhook data.
• Internal transaction status matches Maya Manager 1.0.
• For PayFacs: validate pf.* metadata in webhook payloads.

---

Sandbox Testing Use Cases for Maya Checkout

This section outlines key scenarios and simulation data.

1. Successful Payments

Your platform/system must:

• Process webhook events (PAYMENT_SUCCESS).
• Correctly update transaction status internally.

1.1 Card payments

How to simulate:

1. Initiate Checkout.
2. Enter a Sandbox Success Card.
3. Confirm webhook event (PAYMENT_SUCCESS).

Sandbox Card (Success):

In compliance with PCI, you should not use production / live cards in the Sandbox environment.

Refer to the full card list in the Maya Developer Hub.

Common Mistakes: Using a production card

1.2 Maya Wallet login payments

How to simulate:

1. Start Checkout.
2. On the Checkout form, select Maya under QR and e-Wallets.
3. Click Login to Pay.
4. Enter Sandbox Wallet credentials.
5. Confirm webhook (PAYMENT_SUCCESS).

Sandbox Account (Success):

Common Mistakes: Using a production Maya Account

1.3 Maya QRPH payments (via Sandbox Maya App & account)

How to simulate:

1. Start Checkout.
2. On the Checkout form, select QRPh under QR and e-Wallets.
3. Log in to Sandbox Maya App using the Sandbox test account.
4. Scan QR from Checkout page.
5. Confirm webhook (PAYMENT_SUCCESS).

Sandbox Account (Success):

Common Mistakes:

• Using the production Maya App.
• Using non-Maya Apps (e.g., GCash, ShopeePay).

2. Declined payments

Your platform/system must:

• Handle errors.
• Process webhook events (PAYMENT_FAILED).

See the error pages for best practices and proper handling of declined payments.

2.1 Card Payment Declines

How to simulate:

1. Initiate the checkout.
2. Enter sandbox card details specific to declines in the Maya Checkout form.
3. Verify the error and the corresponding webhook event (PAYMENT_FAILED).

Sandbox Cards (Declines):

Refer to the full card list in the Maya Developer Hub.

2.2 Maya E-wallet Payment Declines

How to simulate:

1. Initiate the checkout.
2. On the Checkout form, select Maya under QR and e-Wallets
3. Click Login to Pay
4. Use the Sandbox Account (Decline)
5. Verify the error and the corresponding webhook event (PAYMENT_FAILED).

Sandbox Account (Decline):

3. Fraud-prevention checks

Check how your integration behaves when transactions trigger fraud checks.

How to simulate:

1. Initiate the checkout.
2. Enter the special “high risk” sandbox cards in the Maya Checkout form.
3. Verify successful payment and the corresponding webhook event (PAYMENT_FAILED).

4. Transaction operations

4.1 Cancel

Cancel the Maya checkout transaction before it is authenticated.

How to simulate:

1. Initiate the checkout.
2. On the Maya Checkout page, click Back to Merchant.
3. Verify whether you are routed to the provided redirect URL for cancellation
4. Verify the canceled payment and the corresponding webhook event (PAYMENT_CANCELLED).

4.2 Expired

The created Maya checkout transaction has expired.

How to simulate:

1. Initiate the checkout.
2. Do not complete the payment and wait until the checkout expires (1 hour)
3. Verify the expired payment and the corresponding webhook event (PAYMENT_EXPIRED).

4.3 Void

Void a successful checkout transaction.

How to simulate:

1. Go to the Maya Manager 1.0 dashboard and find the transaction.
2. Choose the transaction and click Void.

4.4 Refund

Refund a successful checkout transaction.

How to simulate:

1. Go to the Maya Manager 1.0 dashboard and find the transaction.
2. Choose the transaction and click Refund.

Additional Validations for Auth (Hold) and Capture:

• Ensure to test manual capture and partial capture
• Monitor the payment statuses and transitions during authorizing and capturing payments

Additional Validations for Payment Facilitators:

• Ensure your app sends the required metadata.
• Verify metadata appears in webhook payloads.

---

Pro tips for testers

• Ensure that your Sandbox tests cover all major payment scenarios before requesting Production access.
• Do not reuse Sandbox credentials in Production; you must replace them with your Production API keys and MID.
• Validate webhook handling again in Production to ensure no missed events.

---

FAQs

Q: My Sandbox transactions fail. What should I check?

A: Verify you’re using Sandbox keys and URLs.

• Validate your JSON payloads.
• Check the Sandbox Health Page.

Q: Why am I not receiving webhooks?

A: Confirm the webhook is registered in Business Manager. Ensure the endpoint is public and returns 200 OK.

Q: Can I test GCash or WeChat in Sandbox?

A: No. Only Maya Wallet is supported in Sandbox. Other wallets can only be tested in Production.

Q: How do I prove test completion?

A: Email [email protected] and your Relationship Manager with:

• Merchant Name + MID
• Screenshot of 200 OK webhook response
• One successful Visa, Mastercard, and JCB transaction

Q: Can I request my own mobile number for Sandbox?

A: Yes, but use public test accounts whenever possible. Contact your Relationship Manager if needed.

---

Next Steps

• Submit a Go-Live Request via email to:
  • [email protected]
  • Your Maya Relationship Manager
• Include in your request:
  • Merchant Name
  • Merchant ID (MID)
  • Screenshot of 200 OK webhook response
  • Screenshot of one successful transaction per scheme (Visa, Mastercard, JCB)