Create Payment V2 using connectToken

Overview

This guide explains how to integrate the Create Payment V2 API into your website or application.

By the end of this guide, you will be able to:

Understand the required pages and flows for a checkout journey
Create a payment transaction using a connectToken
Monitor payment status using webhook payment events
Retrieve customer information from the API responses and webhook payloads

Before You Begin

Note: To access this API, contact your Maya Account Manager to have this enabled for you.

Prerequisites

Ensure the following are ready before integration:

Completed the Partner onboarding
Have access to Maya Business Manager or Maya Manager 1.0
Generated the API Keys: Public Key (pk-...) and Secret Key (sk-...)
Have correct environment setup (Sandbox or Production)
Completed the Generate connectToken for Payment V2 implementation
Implemented the webhook endpoints. Refer to Configuring Webhooks for Payment V2
- A webhook endpoint to receive payment updates
- A webhook endpoint to receive a customer document
Confirmed with your Maya Account Manager that this solution is enabled for your merchant account.

Key Exchange and Encryption Setup

You must complete a PGP key exchange with Maya during onboarding. This key pair enables secure file transfer and decryption of documents sent by Maya.

Key Usage

The public key is specific to each Partner and is used by Maya to encrypt files.
The private key (retained by the Partner) is used to decrypt these files.
Any documents encrypted with a previous public key cannot be decrypted by a newly generated key.

If you lose your private key or if it expires:

A new key pair must be generated and shared with Maya.
Only documents encrypted after the key update can be decrypted using the new key.
Older documents remain encrypted under the previous key.

How to Generate the Key Pair

Generate a 4096-bit RSA key pair using a PGP-compliant tool or library of your choice (e.g., OpenPGP.js, GPG, or similar).
Set an expiry date, but do not set a passphrase for the public key file.
Once generated, export the public key in ASCII-armored format (.asc) and coordinate it with your Maya Account Manager.

Reference: OpenPGP.js | OpenPGP JavaScript Implementation

Key Specification

Property	Specification
Algorithm	OpenPGP RSA
Key Size	4096 bits
Output Format	ASCII-armored (`.asc`)
User ID	Your organization/contact name and email
Private Key Protection	Strong passphrase (recommended)
Revocation	Create and securely store a revocation certificate
What to Share with Maya	Public key only
What to Keep Private	Private key, passphrase, and revocation certificate

Integration Steps

Step 1: Create Your Response Pages

Prepare dedicated result pages to show transaction outcomes (e.g., success, failure, cancellation).
Host these pages in your system.
Use these page URLs in the redirectUrl object when calling the Create Payment V2 endpoint.

This ensures customers are always redirected back to your platform with clear feedback on their payment status.

Step 2: Create a Payment Request

2.1 Prepare the payment request

Construct your request based on the Create Payment V2 specifications (refer to CREATE PAYMENT REQUEST USING CONNECTTOKEN)

Required configurations:

connectToken - the access_token value from Maya Connect. Refer to Generate connectToken for Payment V2
paymentOption - always set to mayaWallet
paymentMethod.method - always set to REDIRECT
purpose - always set to retrieve-profile,cash-in
redirectUrl - Your hosted response pages (from Step 1)
Include all required fields from the API schema

2.2 Call the Create Payment V2 API

Send a POST request to /payments/v2/payments
A successful response includes the following important fields:
- id (the paymentId)
- customerProfile - an object, contains the customer information
- paymentMethod.methodInfo.redirectUrl - the web page for Maya Receipt

Security Note: The customerProfile object is only returned in the Create Payment V2 API response.
It is not included in webhook payloads or retrieval API responses.

Sample API Response:

{
  "result": "SUCCESS",
  "data": {
    "id": "26100da5-76dd-4abb-a43f-19532b64475f",
    "requestReferenceNumber": "07e73843-a7a2-43a2-ac39-9700a7178bae",
    "totalAmount": { "value": "1", "currency": "PHP", "details": null },
    "items": null,
    "customerId": "3ad59856-1b8d-40b8-ba2f-2fb3ca833ed8",
    "buyer": {
      "id": "3ad59856-1b8d-40b8-ba2f-2fb3ca833ed8",
      "description": "Orion - [email protected]",
      "createdAt": "2025-10-30T01:52:09.954Z",
      "updatedAt": "2025-10-30T01:52:10.039Z",
      "firstName": "Orion",
      "lastName": "Salen",
      "middleName": "Smith",
      "contact": { "email": "[email protected]", "phone": "+639204996436" }
    },
    "metadata": null,
    "paymentStatus": "PAYMENT_SUCCESS",
    "canVoid": true,
    "canRefund": true,
    "canCapture": false,
    "createdAt": "2025-10-30T01:52:07.984Z",
    "updatedAt": "2025-10-30T01:52:09.684Z",
    "paymentAt": "2025-10-30T01:52:09.684Z",
    "merchantId": "EFS100006434",
    "isPaid": true,
    "processorRefNo": "c3918523-d224-46f3-a422-905243599eae",
    "tokenId": null,
    "fundSource": {
      "accountType": "BASIC_CONSUMER_WALLET",
      "description": "46e8",
      "id": "8a77140a-c970-428e-8c3a-5a65da0d1e6d",
      "paymentMethod": "REDIRECT",
      "paymentOption": "mayaWallet",
      "type": "maya-wallet",
      "details": {
        "hash": "Yl06/s3zXgDXQAX0ZRW7bF0uvj02VcpeJcV2+NUYoqA=",
        "firstName": "Orion",
        "lastName": "Salen",
        "middleName": "Smith",
        "msisdn": "+639204996436",
        "email": "[email protected]",
        "customerProfile": {
          "nationality": "PH",
          "birthday": "01-01-1965",
          "occupation": { "natureOfWork": "OTHERS" },
          "gender": "FEMALE",
          "permanentAddress": {
            "line1": "0123 Sampaguita",
            "line2": "Woodland Village",
            "locality": "Plaridel",
            "city": "Bulacan",
            "province": "Bulacan",
            "zipCode": "3004",
            "countryCode": "PH"
          },
          "identifications": [
            { "type": "SSS_ID", "value": "5566778899" },
            { "type": "TIN_ID", "value": "123456789012" },
            { "type": "POSTAL_ID", "value": "1356916396" },
            { "type": "PH_NATIONAL_ID", "value": "1356916396" },
            { "type": "VOTERS_ID", "value": "P0000000AA" }
          ],
          "civilStatus": "SINGLE"
        }
      }
    },
    "paymentOption": "mayaWallet",
    "paymentMethod": {
      "method": "REDIRECT",
      "methodInfo": {
        "redirectUrl": "https://payments-web-staging.maya.ph/v2/payments/26100da5-76dd-4abb-a43f-19532b64475f/processing"
      }
    },
    "refundedAmount": "0"
  }
}

2.3 Redirect the Customer

Redirect the customer to the Maya-hosted Receipt page using the paymentMethod.methodInfo.redirectUrl

When the customer clicks the 'Continue' button or when the timer expires, Maya will automatically redirect the customer to your configured redirectUrl.success (defined in the Create Payment V2 request)

Step 3: Monitor Payment V2 Status

Using Webhook Payment V2 Events

Webhooks notify your system of events (e.g., payment success, failure).

Sample Webhook Payload:

{
      "id": "26100da5-76dd-4abb-a43f-19532b64475f",
      "isPaid": true,
      "status": "PAYMENT_SUCCESS",
      "amount": "1",
      "currency": "PHP",
      "canVoid": true,
      "canRefund": true,
      "canCapture": false,
      "createdAt": "2025-10-30T01:52:07.984Z",
      "updatedAt": "2025-10-30T01:52:09.684Z",
      "description": "Charge for [email protected]",
      "fundSource": {
        "type": "maya-wallet",
        "id": "8a77140a-c970-428e-8c3a-5a65da0d1e6d",
        "description": "******46e8",
        "details": {
          "hash": "Yl06/s3zXgDXQAX0ZRW7bF0uvj02VcpeJcV2+NUYoqA=",
          "firstName": "******",
          "middleName": "******",
          "lastName": "******",
          "msisdn": "******",
          "email": "******",
          "profileId": "******",
          "masked": "******"
        }
      },
      "receiptNumber": "682991664814",
      "requestReferenceNumber": "07e73843-a7a2-43a2-ac39-9700a7178bae",
      "paymentTokenId": "******",
      "receipt": {
        "transactionId": "c3918523-d224-46f3-a422-905243599eae",
        "batchNo": "20251030",
        "receiptNo": "682991664814",
        "approval_code": "599eae",
        "approvalCode": "599eae"
      },
      "approvalCode": "599eae"
    }

Step 4: Receive the `DOCUMENT_READY` Webhook

Maya sends the DOCUMENT_READY event to your webhook endpoint.

Sample Webhook

{
    "id": "26100da5-76dd-4abb-a43f-19532b64475f",
    "type": "DOCUMENT_READY",
    "time": "2025-10-30T01:52:13.588Z",
    "data": {
      "url": "https://public-kyc-docs-staging.s3.ap-southeast-1.amazonaws.com/kyc-docs/26100da5-76dd-4abb-a43f-19532b64475f.zip.pgp?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAUMSO7TMM4RLSBYIK%2F20251030%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20251030T015213Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjECoaDmFwLXNvdXRoZWFzdC0xIkcwRQIhAOqHziKkaviEa%2F1On5wqI4h5F5V4ySDkte6pwBBrXN3wAiBj2mQtBbWqyi%2Fc9t%2F%2Fcn%2FLESfVSPhv%2FnJ8e%2FWRxOHB3CqRAwjj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDMwMTg4NzEwMTcyMSIMQD%2FSU74dhpCY3a%2BqKuUCEu4%2FSPcD3PNZmZ9T3rPb0OIrYU%2BGC1vjJKU%2F%2FkQvqALVjsE%2BvldlN%2FxxV7Obz0RZ5I0ReRNmtPOKyBcvEWnbwO2tjtZ%2BjCAXnja5fAsn2OGyVzp5oo084bRboNJdp%2FrA0rHZKp2UX6yLDxIVGyreh7E7mmbRoL6vJQY06Omnt%2Beiyit%2BDP0owc9KmmGl%2FRMDYKIfLH241xwFuka0dktXsY2xkR3sG85l8sosFt0D4wck8G6WzPLW0oKnnP0jk5d4CV8EANT7iGxOmkkIDIwOpYra0z%2BmasIcISTB6oEcQVvAGnNwSRHpuDIsBYaP2x50tFBZWelC10Iv7mXYAHFd1kWmUeCsBmLBjYWm6xck3q%2BI9f2R4mtXwtbPeKROXKeCpD5xm1g%2FxCJMoD0FP2rpcMRe8WoLgTaAW6Eycs57JWJQ7wWbDU7Et6OTpwr%2B%2FDgGCu9ujTrnXm0SbPdi1jHX5bjXAjpnMKyJi8gGOp0B4jSTVxh%2BPJicX8XpGksMwYPM7KEpTfULGGqApZgJ%2BDQoYcOQQu9KjFlARaQ%2BCDAclc44DW1J22ZD%2BU%2FSO8DHChQZa2Et3KYQctvAJIdohN4EFvM%2FSvx9VgeejHkmrFuVrhRXGXs3VIWqb5fRXv%2FBFb2Q5Y885yrlKbsQJ2QHp2wklOrKAKRPJG2YvWUlCpeYtlG0gieNzqZbg%2FOSdQ%3D%3D&X-Amz-Signature=2b286627e882bcaeb1a101cc0a2a5ef8c382bcd14b3e85ccc64e074fb57342f9&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
      "paymentId": "26100da5-76dd-4abb-a43f-19532b64475f",
      "identityDocuments": [
        {
          "type": "SSS_ID",
          "expiryDate": "",
          "dateIssued": "",
          "value": "5566778899"
        },
        {
          "type": "TIN_ID",
          "expiryDate": "",
          "dateIssued": "",
          "value": "123456789012"
        },
        {
          "type": "POSTAL_ID",
          "front": "639770066261-IDL5VA-POSTAL_ID.jpeg",
          "expiryDate": "01-01-2050",
          "dateIssued": "",
          "value": "1356916396"
        },
        {
          "type": "PASSPORT",
          "back": "639770066261-U4OCRG-PASSPORT_BACK.jpeg",
          "front": "639770066261-U4OCRG-PASSPORT.jpeg",
          "expiryDate": "05-01-2025",
          "dateIssued": "",
          "value": ""
        },
        {
          "type": "PH_NATIONAL_ID",
          "front": "639770066261-CQ0RI3-PHILSYS_DIGITAL.jpeg",
          "expiryDate": "01-01-2050",
          "dateIssued": "",
          "value": "1356916396"
        },
        {
          "type": "DRIVERS_LICENSE",
          "back": "639770066261-03FEUR-DRIVERS_LICENSE_BACK.jpeg",
          "front": "639770066261-03FEUR-DRIVERS_LICENSE.jpeg",
          "expiryDate": "05-01-2023",
          "dateIssued": "",
          "value": ""
        },
        {
          "type": "VOTERS_ID",
          "front": "639770066261-B3OBXG-VOTERS_ID.jpeg",
          "expiryDate": "02-17-2040",
          "dateIssued": "",
          "value": "P0000000AA"
        }
      ]
    }
  }

Notes:

The url is a pre-signed link valid for 12 hours.
The identityDocuments correspond to those found in customerProfile.details.identifications in the Create Payment V2 API response.

Step 5: Extract the pre-signed `url`

Once you receive a DOCUMENT_READY webhook event, follow these steps to download and decrypt the file:

5.1. Download the Encrypted File

Use the data.url value from the webhook payload to download the encrypted .zip.pgp file. The filename corresponds to the Payment ID.

5.2. Decrypt the File

Use your PGP private key to decrypt the .pgp file. You can use any PGP-compatible tool or library.

References:

5.3. Access the Decrypted ZIP

After decryption, you’ll get a .zip file containing the KYC documents.

5.4. Extract the ZIP File

Unzip the decrypted file to access the available media assets.

The assets are named and organized according to the entries in the identityDocuments object.

Note: Some identity documents listed in the webhook payload may not have corresponding media assets in the ZIP file. This is expected behavior and depends on the documents actually submitted by the customer.

Endpoints

Name	Method	Key Type	Endpoint	Description
Create Payment V2	POST	Public	`/payments/v2/payments`	Creates a payment record using `connectToken`.
Create Webhook	POST	Secret	`/payments/v1/webhooks`	Registers a webhook URL for a specific transaction event on which the merchant wants to be notified of.

API Sequence

Narrative:

The user signs in to their Partner application account.
From the Partner's application, the user navigates the Partner's cash-in page
On the Partner's cash-in page, the user clicks the Login to Maya button. This action triggers the Partner's application to begin the OAuth 2.0 authorization process. (Refer to Generate connectToken for Payment V2)
The Partner's application redirects the user’s browser to Maya Connect using the following path parameters:
- response_type=code
- client_id={yourClientId}
- redirect_uri={https://your.redirect/uri}
- prompt=login
- user_id={+63userMobileNumber}
- state={yourState}

The redirect URI must match exactly the Partner's URL registered in Maya Connect.

After the user successfully logs in, completes OTP verification, and provides consent for access, Maya Connect redirects the user back to the Partner’s redirect_uri, appending the authorization code and state parameters.
The Partner's application calls the /token endpoint of Maya Connect, sending the authorization code to obtain an access_token.
Maya Connect validates the request and returns a short-lived access_token, which the Partner will use to perform subsequent Maya API calls.
The Partner's application sends a payment request to the Payment V2 endpoint, passing all required fields, including:
- connectToken = the access_token received from the Maya Connect (refer to #7).
- purpose = cash-in,retrieve-profile
- paymentOption = mayaWallet
- paymentMethod = REDIRECT
Payment V2 responds synchronously with the payment result, customerProfile, and the paymentMethod.methodInfo.redirectUrl that leads to the Maya Receipt page.
The Partner's application redirects the user’s browser to paymentMethod.methodInfo.redirectUrl, allowing the user to review the Maya Receipt.
The user clicks the Continue button on the Maya Receipt page.
After confirmation, Payment V2 redirects the user to the Partner's redirectUrls (e.g., success or failure page) defined in the API request.
User returns to the Partner's application
Payment V2 sends a PAYMENT_SUCCESS webhook event to the Partner containing:
- id = paymentId
- state = PAYMENT_SUCCESS
Payment V2 sends another webhook event, DOCUMENT_READY, to the Partner containing:
- id = paymentId
- url = <pre-signed URL>

The url points to the encrypted ZIP file containing the customer’s KYC documents.

FAQs

Q: If we set the `paymentMethod.method` to `REDIRECT`, will Maya automatically redirect user to the Maya Receipt Page after calling the Create Payment V2 endpoint?

A: No. Your system must get the paymentMethod.methodInfo.redirectUrl value from the Create Payment V2 API response and use it to redirect the user to the Maya receipt page.

Next Steps

Test your integration in the sandbox. You may use the sandbox account below for testing:
- User ID / MIN: 09900100900
- Password: Password@1
- OTP: 123456

Note: Identity documents for this sandbox account are mock data only

Create Payment V2 using connectToken

Overview

Before You Begin

Prerequisites

Key Exchange and Encryption Setup

How to Generate the Key Pair

Integration Steps

Step 1: Create Your Response Pages

Step 2: Create a Payment Request

2.1 Prepare the payment request

2.2 Call the Create Payment V2 API

2.3 Redirect the Customer

Step 3: Monitor Payment V2 Status

Using Webhook Payment V2 Events

Step 4: Receive the `DOCUMENT_READY` Webhook

Step 5: Extract the pre-signed `url`

5.1. Download the Encrypted File

5.2. Decrypt the File

5.3. Access the Decrypted ZIP

5.4. Extract the ZIP File

Endpoints

API Sequence

FAQs

Q: If we set the `paymentMethod.method` to `REDIRECT`, will Maya automatically redirect user to the Maya Receipt Page after calling the Create Payment V2 endpoint?

Next Steps

Payment APIs

Developer resources

More

Overview

Before You Begin

Prerequisites

Key Exchange and Encryption Setup

How to Generate the Key Pair

Integration Steps

Step 1: Create Your Response Pages

Step 2: Create a Payment Request

2.1 Prepare the payment request

2.2 Call the Create Payment V2 API

2.3 Redirect the Customer

Step 3: Monitor Payment V2 Status

Using Webhook Payment V2 Events

Step 4: Receive the DOCUMENT_READY Webhook

Step 5: Extract the pre-signed url

5.1. Download the Encrypted File

5.2. Decrypt the File

5.3. Access the Decrypted ZIP

5.4. Extract the ZIP File

Endpoints

API Sequence

FAQs

Q: If we set the paymentMethod.method to REDIRECT, will Maya automatically redirect user to the Maya Receipt Page after calling the Create Payment V2 endpoint?

Next Steps

Payment APIs

Developer resources

More

Step 4: Receive the `DOCUMENT_READY` Webhook

Step 5: Extract the pre-signed `url`

Q: If we set the `paymentMethod.method` to `REDIRECT`, will Maya automatically redirect user to the Maya Receipt Page after calling the Create Payment V2 endpoint?