Technical Documentations
Maya Tech BlogGo to Maya Business Manager

Getting Started with Unified Transfer

⚠️

Unified Transfer is in active development. As a pioneer merchant, you will be informed of the updates through your Maya Relationship Manager.

Overview

This guide walks you through the full integration journey for the Unified Transfer, from partner onboarding and security setup to testing in Sandbox, and finally going live in Production.

Before you begin, make sure you have read About Unified Transfer to understand its requirements, architecture, and key concepts.

By the end of this guide, you will know the tools, credentials, and configurations required before writing any code.

Getting Started

Step 1: Define Your Setup

  • Identify the processing channels you want to support: Maya (in-house, real-time), InstaPay (ACH, real-time), PESONet (ACH, batch), or any combination of these
  • Determine your transaction volume and value requirements
  • Understand the compliance data you need to collect (KYC/AML requirements)

Step 2: Set Up Required Infrastructure

The Unified Transfer requires FAPI-compliant security and callback infrastructure.

2.1. Create and Host Your JWKS Endpoint

For complete guidance, refer to the following guides:

2.2. Build Your Callback Endpoint

The Unified Transfer processes transfers asynchronously and sends status updates to your callback endpoint.

To build your callback, see Implementing Callback for Unified Transfer

2.3. Generate your GPG Keys

GPG Keys will only be used to encrypt client credentials before sending them to your nominated key recipient.

For more information on acquiring your client credentials, see Bearer Authentication.

Step 3: Contact Maya for Partner Onboarding

The onboarding process is still a work in progress, expect this section to be updated.

The Unified Transfer requires formal partner onboarding with Maya.

3.1. Initiate the onboarding process

Contact your Maya Relationship Manager to begin:

  • Email: Maya Relationship Manager email address
  • Subject: "Unified Transfer - Partner Onboarding Request"

Include in your request:

  • Company name and business registration details
  • Contact person and technical lead information
  • Intended use case and transaction volume estimates
  • Preferred processing channels (Maya, InstaPay, PESONet, or a combination)
  • Your JWKS endpoint URL (from Step 2.1)
  • Your callback endpoint URL (from Step 2.2)
  • Your GPG Keys (from Step 2.3)
  • The email address of your nominated key recipient

3.2. Complete documentation requirements

Maya will provide a list of required documents, which typically include:

  • Business registration certificates
  • Financial institution licenses (if applicable)
  • Compliance certifications
  • Technical contact information
  • Security and data protection policies

3.3. Approval & Account Activation

Once verified and approved, Maya will:

  • Create your partner account in their system
  • Send your client credentials (Client ID and Client Secret) to your nominated key recipient for the Sandbox. Note: Production credentials will be provided after Maya's acceptance testing approval
  • Register your JWKS endpoint URL
  • Configure your callback endpoint URL

Step 4: Configure & Implement

4.1. Review How API Authentication Works in Unified Transfer

4.2. Review the Technical Documentation and API specification:

Step 5: Test Your Integration in Sandbox

Minimum test coverage required:

  • Successful transfer flow: Initiate → Confirm → Receive callback with APPROVED status
  • Error scenarios: Invalid accounts, insufficient balance, missing compliance data, expired confirmation
  • Inquiry endpoints: Status checks by transaction ID and originator transaction ID
  • Callback handling: Verify your endpoint receives and processes callbacks correctly
  • Compliance data: Test with complete KYC/AML information

Step 6: Submit Testing Results

Once testing is complete, submit your results to Maya:

The test results submission process is still a work in progress, expect this section to be updated.

Recipients:

Include:

  • Partner name and account details
  • Summary of test scenarios completed
  • Screenshots of successful transactions (all statuses)
  • Screenshots of callback responses (2xx status codes)
  • Screenshots of error handling
  • Confirmation that the JWKS endpoint is accessible
  • Confirmation that the callback endpoint is ready for production

Step 7: Go Live in Production

When ready, coordinate with your Maya Relationship Manager to transition to Production.

Before Going to Production

  • Complete all Sandbox testing and submit your sign-off
  • Obtain Maya's acceptance testing approval
  • Review your error handling and monitoring procedures
  • Prepare your production environment:
    • Set up production JWKS endpoint
    • Configure production callback endpoint
    • Implement production monitoring and alerting
    • Set up production key management
  • Update your application with production values:
    • OAuth credentials: Maya will send the production OAuth 2.0 credentials (Client ID and Client Secret) to your nominated key recipient.
    • API endpoints (for production environment URLs, see the Environments section in the About Unified Transfer.

After Going Live in Production

  • Conduct pilot testing with small transaction amounts
  • Monitor all transactions closely for the first few days
  • Verify callbacks are being received and processed
  • Submit your final signoff to Maya
  • Gradually increase transaction volume

Production Support

For production issues or support, contact [email protected] with your partner account details and transaction IDs.

Estimated Activities and Timelines

Considering internal complexities like engineering resources, security setup, compliance requirements, and team coordination, the integration with the Unified Transfer can take anywhere from weeks to months.

Note that this are all rough estimates and the activities depend on the integrating partner's resources and timelines.

PHASEESTIMATESTASKS
Prepare the required infrastructure onboarding~1 weekGenerate your RSA keys, create and host your JWKS endpoint, and set up your callback infrastructure
Partner Onboarding1-2 weeksSubmission of documentation, compliance verification, and account creation. Sandbox credentials are provided during this phase.
Building the Integration3-6 weeksDevelop your integration, implement request signing, build callback handling, and integrate with your systems. Timeline varies based on complexity.
Testing in Sandbox1-2 weeksComplete end-to-end testing in Sandbox, test all scenarios, and provide signoff to Maya.
Transition to Production1-2 weeksMaya's review and approval process. Production credentials were provided during this phase.
Go Live1 weekPilot testing in Production with real transactions, monitoring, and final signoff.

FAQs

Q: Do I need to complete onboarding before I can test?

A: Yes, you must be onboarded as a partner and receive your OAuth 2.0 credentials before you can access the Sandbox environment.

Q: Can I test without setting up a JWKS endpoint?

A: No, the JWKS endpoint is required for FAPI-compliant request signing. All API requests must include a valid JWS signature.

Q: What happens if my callback endpoint is down?

A: Maya will attempt delivery up to 5 times total: initial attempt, immediate retry, then scheduled retries at 5 minutes, 15 minutes, and 45 minutes after each previous retry fails. If all attempts fail, you must use the inquiry endpoints to check transaction status.

Q: Can I use the same credentials for Sandbox and Production?

A: No, Sandbox and Production have separate credentials. Never use production credentials in Sandbox or vice versa.

Q: When should I use InstaPay vs PESONet?

A: Use InstaPay for real-time transfers up to ₱50,000, and PESONet for higher-value transfers up to ₱300,000 that can be processed in batches.

Next Steps

You have now completed the setup for Unified Transfer and are ready to integrate.