Unified Transfer is in active development. As a pioneer merchant, you will be informed of the updates through your Maya Relationship Manager.
Overview
This page defines key terms, acronyms, and solution-specific concepts used throughout the Unified Transfer documentation. Understanding these terms will help you navigate the documentation more effectively.
Authentication & Security
Access Token
A credential for accessing protected resources. Obtained via OAuth 2.0 Client Credentials flow, typically expires after 1 hour.
Bearer Token
An access token included in the Authorization header as Bearer {token}.
Client Credentials Grant
An OAuth 2.0 flow for machine-to-machine authentication using Client ID and Client Secret.
FAPI (Financial-grade API)
A highly secure profile of OAuth 2.0 designed for financial services. Mandates additional security measures like request signing.
HSM (Hardware Security Module)
A physical device for safeguarding cryptographic keys. Recommended for production private key storage.
JWKS (JSON Web Key Set)
A JSON structure containing public keys. Partners must host a JWKS endpoint at https://your-domain.com/.well-known/jwks.json.
JWS (JSON Web Signature)
A standard for digitally signing JSON data. Required in the x-jws-signature header for all API requests.
Key ID (kid)
A unique identifier for a cryptographic key. Included in the JWS header to indicate which key was used for signing.
Key Rotation
Periodically replacing cryptographic keys to reduce compromise risk.
Key Vault
Secure storage for cryptographic keys, secrets, and certificates. Cloud-based or on-premises.
OAuth 2.0
An industry-standard authorization framework for machine-to-machine authentication. The Unified Transfer uses the Client Credentials Grant flow.
Private Key
A cryptographic key that must be kept secret. Used to sign API requests. Must be stored securely (HSM, key vault, encrypted storage).
Public Key
A cryptographic key that can be shared publicly. Published in your JWKS endpoint for signature verification.
Request Signing
The process of digitally signing API requests using JWS to ensure request integrity and authenticity.
Signature Verification
The process of validating JWS signatures using public keys to confirm request authenticity.
Transactions & Processing
Asynchronous Processing
A processing model where the API returns immediately with PROCESSING status. Final status is delivered via callback.
Batch Processing
Scheduled transaction processing through the PESONet network, typically processed same-day or next business day.
Callback
An HTTP POST request sent by Maya to your endpoint with transaction status updates.
Confirmation Deadline
The time limit (1 hour from initiation) to confirm a transfer. After this, the transaction moves to LAPSED status.
Idempotency Key
A unique UUID in the x-idempotency-key header to prevent duplicate transactions. Same key with same body returns the existing transaction.
Originator Transaction ID
A unique identifier provided by the partner for each transaction. Sent in the x-originator-transaction-id header. Must be unique per partner transaction.
Real-time Processing
Immediate transaction processing through the InstaPay network, providing instant fund availability.
Status Notification
Asynchronous updates about transaction status delivered via callback notifications.
Transaction Lifecycle
The complete journey of a transfer from initiation through final status (INITIATED → PROCESSING → APPROVED/DECLINED). For detailed information about each transaction state, see Transaction States.
Transaction Monitoring
Built-in tracking and logging of all transfer activities for compliance and audit purposes.
Transfer ID
A unique UUID assigned by Maya to identify a fund transfer transaction. Also referred to as id in API responses.
Two-Phase Transaction Model
The transaction flow consisting of two phases: Initiate (validates and returns transaction ID) and Confirm (begins asynchronous processing).
Networks & Accounts
Account Number
The unique identifier for an account. Can be a traditional account number or mobile number for e-wallets.
ACH (Automated Clearing House)
An electronic network for financial transactions in the Philippines. Supports InstaPay and PESONet channels.
Credit Account
The destination account to which funds will be transferred. The receiver's account.
Debit Account
The source account from which funds will be withdrawn. Must belong to the authenticated partner.
Financial Institution Code
A unique code for a financial institution, also known as SWIFT/BIC code. 11 characters: bank code (4) + country code (2) + location code (2) + branch code (3).
InstaPay
Real-time electronic fund transfer service. Maximum 50,000 PHP per transaction for non-Maya accounts.
PESONet
Batch electronic fund transfer service. Maximum 300,000 PHP per transaction.
SWIFT/BIC Code
International standard for identifying banks. Example: PAPHPHM1XXX (Maya Philippines).
Compliance & Regulatory
AML (Anti-Money Laundering)
Regulations to prevent money laundering. Enforced through transaction purpose, source of income, and relationship data.
Compliance Data
Required information for regulatory compliance, including KYC details, transaction purpose, and source of income.
KYC (Know Your Customer)
Regulatory requirements to verify customer identity. Required for both sender and receiver.
Receiver
The person or entity receiving the funds. Must provide identification, address, contact, and relationship to sender.
Relationship to Receiver
The relationship between sender and receiver. Must use predefined values (e.g., "Father", "Mother", "Spouse", "Self").
Sender
The person or entity initiating the fund transfer. Must provide identification, address, contact, and employment details.
Source of Income
The origin of the funds. Must use predefined values (e.g., "Salary", "Business Proceeds", "Remittance").
Transaction Purpose
The reason for the fund transfer. Must use predefined values (e.g., "Family Support/Allowance", "Education-related expense").
Work Nature
The occupation or business type of the sender. Must use predefined values (e.g., "Banking", "BPO Companies", "OFW").
API & Integration
API Rate Limiting
Controls on the number of API requests allowed within a specific time period to prevent system overload.
Callback Endpoint
A URL hosted by the partner to receive asynchronous transaction status updates from Maya.
Endpoint
A specific URL where an API can be accessed. Example: POST /v1/transfers/p2p.
Header
Metadata sent with HTTP requests or responses. Examples: Authorization, Content-Type, x-jws-signature.
HTTP Status Code
A three-digit code indicating the request result. Examples: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized).
Inquiry Endpoint
API endpoints to check transaction status anytime. Query by Transfer ID or Originator Transaction ID.
JWKS Endpoint
A publicly accessible URL at https://your-domain.com/.well-known/jwks.json containing the public key for signature verification.
Onboarding
The process of registering as a partner, completing documentation, and receiving credentials.
Partner
A financial institution or organization onboarded to use the Unified Transfer.
Production
The live environment where real fund transfers occur. Requires separate credentials from Sandbox.
Request Body
The JSON payload sent in an API request.
Response Body
The JSON payload returned by the API.
REST API
An architectural style for building web services using HTTP methods (GET, POST, PUT, DELETE).
Retry Strategy
Maya's mechanism for delivering callbacks. Up to 5 attempts: initial attempt, immediate retry, then scheduled retries at 5, 15, and 45 minutes after each previous retry fails. Retries occur on 3xx, 4xx, 5xx responses or timeouts.
Sandbox
A test environment for development and testing without affecting real transactions.
UTC (Coordinated Universal Time)
The time standard used by the API. All timestamps are in UTC (offset 0) for consistency across time zones.
Error Handling
Account Validation Errors
Errors related to account existence, format, or validation.
Circuit Breaker
A pattern to prevent cascading failures by stopping requests when error rates exceed thresholds.
Exponential Backoff
A retry strategy where delay between retries increases exponentially.
Integration Errors
Errors related to client integration, authorization, and access control.
Non-Retriable Errors
Errors that should not be retried without fixing the underlying issue, typically client errors (4xx).
Retriable Errors
Errors that can be safely retried, typically system errors (5xx).
System Errors
Errors related to service availability, timeouts, and temporary system issues.
Transaction Errors
Errors related to business rule violations, insufficient funds, and limits exceeded.
FAQs
Q: What's the difference between Transfer ID and Originator Transaction ID?
A: Transfer ID is assigned by Maya to uniquely identify each transaction, while Originator Transaction ID is your own unique identifier that you provide for tracking purposes.
Q: Are Bearer Token and Access Token the same thing?
A: Access Token is the credential itself, while Bearer Token refers to how it's used in the Authorization header (Bearer {access_token}).
Q: What's the difference between Sandbox and Production environments?
A: Sandbox is for testing with simulated data, while Production handles real fund transfers. They require separate credentials and have different base URLs.
Next Steps
Now that you’re familiar with the key terms used in Unified Transfer, proceed to How API Authentication Works in Unified Transfer to understand the API Authentication model and to learn how OAuth 2.0 and JWS request signing are implemented before making your first API call