Accept Payments as a Payment Facilitator in Maya Checkout

Overview

Maya Checkout allows businesses to process payments for their sub-merchants under a Payment Facilitator (PayFac) setup. In this model, you act as the primary merchant, while your sub-merchants accept electronic payments seamlessly under your account.

This guide explains how to integrate Maya Checkout via REST API as a PayFac, from onboarding to transaction handling.

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 PayFac setup
• 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

What is a Payment Facilitator?

A Payment Facilitator (PayFac) is a merchant service provider that simplifies payment acceptance for sub-merchants.

Instead of each sub-merchant undergoing one-time underwriting, PayFac applies continuous underwriting, where risk checks occur for every transaction.

Transactions are processed under the PayFac’s account but tagged with sub-merchant information for reporting, settlement, and compliance.

Enabling PayFac in Maya Checkout

1. Contact your assigned Maya Relationship Manager to enable PayFac for your account.
2. Once approved, you must include sub-merchant details in all checkout requests.

Integrating Maya Checkout as a Payment Facilitator

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. Create 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 a Maya Checkout Transaction

2.1. Prepare the Checkout request

When a customer clicks the Checkout button:

• Build your request following the Create Checkout API specifications
• Include the required fields
• Include redirectUrl (your response pages)
• Make sure to include the metadata object with PayFac fields

Metadata Object:

Sample Request Payload:

{
  "totalAmount": {
    "value": 100,
    "currency": "PHP"
  },
  "redirectUrl": {
    "success": "https://www.merchantsite.com/success?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
    "failure": "https://www.mechantsite.com/failure?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
    "cancel": "https://www.merchantsite.com/cancel?id=5fc10b93-bdbd-4f31-b31d-4575a3785009"
  },
  "requestReferenceNumber": "5fc10b93-bdbd-4f31-b31d-4575a3785009",
  "metadata": {
    "subMerchantRequestReferenceNumber": "sub-ref-0987654321",
    "pf": {
      "smi": "submerchant001",
      "smn": "Sub Merchant Co.",
      "mci": "Mandaluyong City",
      "mpc": "608",
      "mco": "PHL",
      "mcc": "5812",
      "postalCode": "1554",
      "contactNo": "0211111111",
      "addressLine1": "66-70 Sheridan cor United Sts"
    }
  }
}

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: 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.

3.1 Use Webhooks

• Webhooks notify you of payment results. To get started with webhooks, see Configuring Your Webhook for Maya Checkout
• Match transactions using:
  • id (checkout ID/payment ID)
  • subMerchantRequestReferenceNumber (sub-merchant transaction ID)
  • pf.* fields (for reporting and reconciliation)

Sample Webhook Payload (PayFac):

{
  "id": "uuid",
  "items": null,
  "metadata": {
    "subMerchantRequestReferenceNumber": null,
    "pf": {
      "smi": "smi_value",
      "smn": "smn_value",
      "mci": "mci_value",
      "mpc": "PHP",
      "mco": "CN",
      "mst": null,
      "mcc": null,
      "postalCode": null,
      "contactNo": null,
      "state": null,
      "addressLine1": null
    }
  },
  "requestReferenceNumber": "req3u3stRef3r3nceNumber",
  "receiptNumber": "224903381464",
  "createdAt": "2022-09-06T03:19:58.000Z",
  "updatedAt": "2022-09-06T03:55:16.000Z",
  "paymentScheme": "visa",
  "expressCheckout": true,
  "refundedAmount": "0",
  "canPayPal": false,
  "expiredAt": "2022-09-06T03:55:43.000Z",
  "status": "COMPLETED",
  "paymentStatus": "PAYMENT_SUCCESS",
  "buyer": {
    "firstName": "buyer first name",
    "lastName": "last name",
    "billingAddress": {},
    "shippingAddress": {}
  },
  "merchant": {
    "currency": "PHP",
    "email": "[email protected]",
    "locale": "en",
    "homepageUrl": "https://www.merchant.com/",
    "isEmailToMerchantEnabled": true,
    "isEmailToBuyerEnabled": true,
    "isPaymentFacilitator": false,
    "isPageCustomized": false,
    "supportedSchemes": [
      "Mastercard",
      "Visa"
    ],
    "canPayPal": false,
    "payPalEmail": null,
    "payPalWebExperienceId": null,
    "expressCheckout": true,
    "name": "FUCENT GATEWAY CORP "
  },
  "totalAmount": {
    "value": "10",
    "currency": "PHP",
    "details": null
  },
  "redirectUrl": {
    "success": "http://www.success.com",
    "cancel": "http://www.failure.com"
  },
  "transactionReferenceNumber": "uuid",
  "paymentDetails": {
    "last4": "0000",
    "cardType": "visa",
    "maskedCardNumber": "******0000",
    "3ds": false,
    "paymentAt": "2022-09-06T03:55:16.000Z"
  }
}

3.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 for Payment Facilitators, including:

• The core requirements for Payment Facilitators
• Which endpoints to call during the payment 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: My webhook payload does not contain sub-merchant details. Why?

A: If metadata was not provided in the request, it will not appear in webhook notifications. Make sure you passed the required PayFac metadata (subMerchantRequestReferenceNumber and pf.* fields) when creating the checkout.

Q: Can I use the same Checkout integration for both direct merchant payments and PayFac sub-merchant payments?

A: Yes. If PayFac is enabled on your account, you can send standard checkout requests with or without PayFac metadata. When PayFac metadata is included, transactions are tied to the sub-merchant. Otherwise, transactions are processed under your main merchant account.

Q: How long are Checkout sessions valid?

A: Checkout sessions are valid for 1 hour. If expired, create a new checkout request with updated metadata and redirect URLs.

Next Steps

You have successfully implemented Maya Checkout to accept payments as a Payment Facilitator. To build a more robust and production-ready integration, 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.