POST https://pg-staging.maya.ph/payments/v2/payments

When you ask Maya to authorize a payment, Maya will do account validations, such as account status and balance check. If it passes these validations, a hold is placed on the funds in your customer’s linked Maya account.

Authorization Types

What happens during Authorization:

During the process of creating an authorization, Maya will create a new authorization record, which will be assigned with a unique identification number (id). Subsequently, this authorization record will go through different transitions across various authorization states until it eventually reaches the AUTHORIZED state.

1. Maya creates a new authorization record with an initial state of PENDING_PAYMENT. During this state, no funds are held or moved.
2. Once the record is prepared for processing, Maya will transition it to the state of PAYMENT_PROCESSING, where validation checks are conducted.
3. If the authorization request successfully places a hold on the funds in the customer's Maya account, the authorization record will be tagged as AUTHORIZED.
4. On the other hand, if the authorization request fails to pass the validation checks, Maya will decline the request and mark the record as PAYMENT_FAILED.

Authorization hold period

A successful authorization is held until the transaction is not past its hold period. Authorizations past their corresponding hold period that do not have successful captures, or not canceled, will result to the authorization hold being dropped.

In case the AUTHORIZED record remains uncaptured or not canceled, and it surpasses its corresponding hold period, the authorization hold will be released, and the authorization record will transition to AUTHORIZATION_HOLD_EXPIRED.

POST https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/captures

Use this endpoint to capture an authorized payment transaction. Capturing an authorization will transition to CAPTURED state.

What happens during Capture Authorization:

During capture authorization, Maya will create a new captured payment record, which will be assigned with a unique identification number (id). Subsequently, this captured payment record will go through different transitions across various authorization states until it eventually reaches the PAYMENT_SUCCESS state.

1. Maya creates a new captured payment record, starting in the state of PENDING_PAYMENT.
2. Once the record is prepared for processing, Maya will transition it to the PAYMENT_PROCESSING state, during which validation checks are carried out.
3. If the capture request is successfully executed and funds are debited, the captured payment record will be marked as PAYMENT_SUCCESS.
4. On the other hand, if the capture request fails to meet the validation requirements, Maya will decline the request and update the captured payment record as PAYMENT_FAILED.

Simultaneously with the creation of the captured payment record, Maya will update the status of the corresponding authorization record once a successful capture authorization takes place.

1. Maya identifies the corresponding AUTHORIZED record using the authorization id.
2. Maya updates the authorization state to CAPTURED.
3. If the capture request is deemed final, the state of the authorization record will transition to DONE.

Manage the payment status updates by implementing webhooks.

Step 1: Identify the events you want to monitor and the event payloads to parse.

Step 2: Create a webhook endpoint as an HTTP endpoint (URL)

This endpoint is expected to receive a POST request with JSON payload from Maya for a given account link event. The endpoint is expected to return a 2xx response status codes.

const express = require('express');
const app = express();

app.post('/webhook', async (req, res) => {
  // TODO: You will have to implement the logic of this method.
  processMayaWebhookNotificationData(req.body);
  
  res.send({
    success: true
  })
});

app.listen(8080, () => console.log('Listening on port ${8080}!'));

Step 3: Test that your webhook endpoint is working properly.

You can execute your webhook endpoint via a simple curl command or through an API client application like Postman.

Sample Webhook Endpoint Test via curl

$ curl -s -D - -o /dev/null -X POST -H "Content-Type: application/json" \
-d '{
  "id": "0f324861-714c-441c-8829-eb1145908044",
  "isPaid": true,
  "status": "PAYMENT_SUCCESS",
  "amount": "100",
  "currency": "PHP",
  "canVoid": true,
  "canRefund": true,
  "canCapture": false,
  "createdAt": "2022-10-06T02:27:20.000Z",
  "updatedAt": "2022-10-06T02:28:01.000Z",
  "description": "Charge for [email protected]",
  "fundSource": {
    "type": "maya-credit",
    "id": "44d4d537-b3e3-4db8-830c-c9e969f43450",
    "description": "******9d77",
    "details": {
      "firstName": "Justin",
      "lastName": "Jones",
      "msisdn": "+639193890001",
      "profileId": "770993336277",
      "middleName": "******",
      "email": "******",
      "masked": "********4567"
    }
  },
  "metadata": {},
  "requestReferenceNumber": "20a26ca8-3ada-47d1-a8b6-46673d664eee",
  "paymentTokenId": "******",
  "receipt": {
    "transactionId": "******",
    "batchNo": "00000000",
    "receiptNo": "000000000000",
    "approval_code": "******",
    "approvalCode": "******"
  },
  "approvalCode": "******",
  "receiptNumber": "000000000000"
}' \
https://83ef-130-105-160-253.ngrok.io/webhook

When the output of the curl command shows a 200 response code that means that your webhook reachable and will return a status 200 OK.

HTTP/2 200
content-type: application/json; charset=utf-8
date: Mon, 14 Feb 2022 01:08:14 GMT
ngrok-agent-ips: 130.105.160.253
content-length: 18

Step 4: Save your Webhook via Create Webhook.

Register your webhook endpoints via the Create Webhook endpoint.

POST https://pg-staging.maya.ph/payments/v2/payments

This functionality will allow you to charge the final amount directly towards your customer’s linked Maya account. It can be used in scenarios wherein there is a mismatch between the authorized amount and the final amount to be charged.

What happens during Straight Payment:

During straight payment, Maya will create a new payment record, which will be assigned with a unique identification number (id). Subsequently, this payment record will go through different transitions across various payment states until it eventually reaches the PAYMENT_SUCCESS state. For this instance, no authorization and capture steps are needed.

1. Maya creates a new payment record, starting in the state of PENDING_PAYMENT, where no funds are debited.
2. Once the record is prepared for processing, Maya will transition it to the PAYMENT_PROCESSING state, during which validation checks are carried out.
3. If the payment request is successfully executed and funds are debited, the payment record will be marked as PAYMENT_SUCCESS.
4. On the other hand, if the payment request fails to meet the validation requirements, Maya will decline the request and update the payment record as PAYMENT_FAILED.

GET https://pg-staging.maya.ph/payments/v2/payments/{paymentId}

Use this endpoint to retrieve authorization or straight payment details you will be needing for validation. This endpoint requires paymentId which should be provided as request parameter.

GET https://pg-staging.maya.ph/payments/v2/payment-rrns/{rrn}

Use this endpoint to retrieve authorization or straight payment details you will be needing for validation. This endpoint requires rrn or the requestReferenceNumber which should be provided as request parameter.

GET https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/captures

Use this endpoint to retrieve transaction details of a captured authorization. This endpoint requires paymentId which should be provided as request parameter.

POST https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/voids

Use this endpoint to void an authorized payment. Upon successful void, Maya will release the hold placed on the customer’s funds.

What happens during Void Authorization:

During void authorization, Maya will create a new void record, which will be assigned with a unique identification number (id). Subsequently, this void record will transition to SUCCESS or FAIL state.

1. Maya creates a new void record, starting in the state of PENDING.
2. If the void is successfully executed, the void record will be marked as SUCCESS.
3. On the other hand, if the void fails to meet the validation requirements, Maya will decline the request and update the record as FAILED.

Simultaneously with the creation of the void record, Maya will update the status of the corresponding authorization record and transition it VOIDED state once a successful void takes place.

GET https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/voids

Call this endpoint to get all voids requested for a certain paymentId.

POST https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/refunds

Call this endpoint to request for a refund for the captured payments. Upon successful refund, Maya will void and refund the transaction.

What happens during Refund Captured Payments:

During refund, Maya will create a new refund record, which will be assigned with a unique identification number (id). Subsequently, this payment record will transition to SUCCESS or FAIL state.

1. Maya creates a new refund record, starting in the state of PENDING.
2. If the refund is successfully executed, the refund record will be marked as SUCCESS.
3. On the other hand, if the refund fails to meet the validation requirements, Maya will decline the request and update the record as FAILED.

Simultaneously with the creation of the refund record, Maya will update the status of the corresponding payment record and transition it REFUNDED state once a successful void takes place.

GET https://pg-staging.maya.ph/payments/v2/payments/{paymentId}/refunds

Call this endpoint to get all refunds requested for a certain paymentId.

POST https://pg-staging.maya.ph/payments/v2/payments/dry-run

Use the test payment endpoint to conduct a dry run to verify the eligibility of the linked account and availability of funds before making a transaction. Performing a Test Payment will NOT result in any deduction from the user's wallet balance.

Test Payment endpoint can ONLY do the following:

• Validate if state of the account link (linkId) is eligible to make a transaction
• Validate if wallet has sufficient balance to create a transaction

Call this endpoint by providing the linkId and the transaction amount you want to verify prior to the actual authorization or charge.

If account link is valid and has sufficient balance to make the transaction, this endpoint will return a HTTP 204 response. Otherwise, it will return an error response with the error details (see sample 🔴 400 response body of POST https://pg-staging.maya.ph/payments/v2/payments/dry-run ).