# API Sequence

VIEW DIAGRAM

This solution uses **Bearer Token Authentication**. Your application must secure a valid `access_token` from Maya Connect to authenticate your requests. For more details, refer to **Bearer Authentication**

1. The customer provides remittance information to the API Consumer. 2. The API Consumer checks for a valid `access_token`. * If `access_token` is **expired** or no valid `access_token` exists: * The API Consumer requests a new `access_token` via **Maya Connect**

. * Maya Connect responds to the API Consumer with the `access_token`. * The API Consumer saves the `access_token`.
3. The API Consumer initiates the send transaction by calling the **Initiate Send** endpoint of the Maya Remittance API. 4. The Maya Remittance API checks if the transaction is a *retry*. 5. If it's a new send transaction, Maya Remittance API will proceed with the processing of the request, otherwise, Maya Remittance API will decline the request. 6. Maya Remittance API creates a remittance record with `INITIATED` status. 7. Maya Remittance API responds to the API Consumer with the generated `id`. 8. The API Consumer saves the `id`. 9. The API Consumer asks the customer for transaction confirmation. 10. The customer provides their confirmation. 11. The API Consumer checks for a valid `access_token`. * If `access_token` is **expired** or no valid `access_token` exists: * The API Consumer requests a new `access_token` via **Maya Connect**

. * Maya Connect responds to the API Consumer with the `access_token`. * The API Consumer saves the `access_token`.
12. The API Consumer sends a confirmation request to Maya Remittance API via the **Confirm Send** endpoint. 13. Maya Remittance API processes and updates the status of the send transaction to `PROCESSING`. 14. Maya Remittance API responds to the API Consumer with `PROCESSING` status. 15. Maya Remittance API debits funds from the source account. 16. Maya Remittance API credits funds to the receiver. 17. Maya Remittance API receives response from the receiver and triggers a callback: * If crediting succeeds: Maya Remittance API notifies the API Consumer of the `APPROVED` status. * If crediting fails: Maya Remittance API notifies the API Consumer of the `DECLINED` status. This will entail returning the funds back to the source account. 18. The API Consumer acknowledges the callback by responding with a 200 OK to the Maya Remittance API. 19. The API Consumer processes the callback. * If no callback is received: * The API Consumer checks for a valid `access_token` * If `access_token` is **expired** or no valid `access_token` exists: * The API Consumer requests a new `access_token` via **Maya Connect**

. * Maya Connect responds to the API Consumer with the `access_token`. * The API Consumer saves the `access_token`.
\- The API Consumer queries Maya Remittance API via the **Get Send** endpoint \- Maya Remittance API responds to the API Consumer with the send details. \- The API Consumer processes the updates. 20. The API Consumer updates the customer on the status of the remittance.

## Initiate the send

Prepare and create the remittance transaction.

### Step 1: Prepare the required details Sender and receiver details are crucial for screening and identifying the destination account. Below is a list of essential information needed when initiating a remittance: [block:parameters] { "data": { "h-0": "Information", "h-1": "Description", "0-0": "**Source Account Details**", "0-1": "Specifies the source account from which funds will be pulled for the remittance. \n \nThe required details to identify your source account include the account number, account name, and the financial institution where the account is held. \n \n

The `financial_institution_code` must be a valid **SWIFT code of Maya**, based on your account type:\n

`PAPHPHM1` for an **Operating Wallet in Maya PH**
`MYYAPHM2` for a **Business Deposit account in Maya Bank**

Reach out to your **Maya Relationship Manager** to know more about your source account.\n

", "1-0": "**Receiver Account Details**", "1-1": "Specifies the receiver’s or target account from which funds will credited. \n \nThe required details to identify your target account include the account number, account name, and the financial institution where the account is held. \n \n

The `financial_institution_code` must be a valid **SWIFT code of a bank in the Philippines**.\n

", "2-0": "**Sender Information**", "2-1": "Includes Sender KYC details", "3-0": "**Receiver Information**", "3-1": "Includes Receiver’s KYC details" }, "cols": 2, "rows": 4, "align": [ "left", "left" ] } [/block]
Ensure all necessary information is complete and accurate to facilitate a smooth transaction. Refer to the API specifications of **Initiate Send** for the full list of required fields. *** ### Step 2: Initiate a send request

No movement of funds will be done during this step.

After preparing the required information, send the request to the **Initiate Send** endpoint. Maya will validate the source and receiving accounts, including account status, limits, and restrictions. KYC information of both the sender and receiver will also be checked for sanctions. Maya will then respond with the initial validation results. Ensure the status is `INITIATED` and store the returned `id` before proceeding to the next steps.

Please note that the initiate send is valid for only **1 hour**. After this period, the transaction will be transitioned to `LAPSED` status. Any attempt to confirm a `LAPSED` transaction will result in the error **REMGTW0012** .

[block:tutorial-tile] { "backgroundColor": "#018FF4", "emoji": "📖", "id": "6a6196383c739db831fe2c6d", "link": "https://developers.maya.ph/v6.00/recipes/initiating-send-remittance", "slug": "initiating-send-remittance", "title": "Initiating Send Remittance" } [/block]

## Confirm the send

Confirm and process the remittance transaction.

Triggering the Confirm Send finalizes the request and authorizes the balance movement.

When the remittance request is confirmed, use the acquired remittance `id` and call the **Confirm Send** endpoint to proceed with the request. Validations will be conducted while securing the amount from your fund source.

You can only confirm an `INITIATED` send, otherwise, confirm send will return the current status of the send transaction whether it’s `APPROVED`, `DECLINED`, or `PROCESSING`. See also sample response payloads in **Confirm Send** .

Maya will acknowledge receipt of the request by responding with the initial remittance status update: `PROCESSING` while conducting validations and proceeding with the transfer. [block:tutorial-tile] { "backgroundColor": "#018FF4", "emoji": "📖", "id": "6a6196383c739db831fe2c6e", "link": "https://developers.maya.ph/v6.00/recipes/confirming-the-send-remittance", "slug": "confirming-the-send-remittance", "title": "Confirming the send remittance" } [/block]

## Monitor the send

Monitor and receive transaction status updates.

Balance transfers are processed **asynchronously** to handle potential timeouts and latency spikes that often cause ambiguous transaction states.

The resulting status after processing the transaction is **final**.

Maya uses callbacks to inform your application about specific events related to the remittance transaction. These notifications include the transaction status and response codes. Maya’s callback will trigger a maximum of **5 times**. * Immediately after the status event is triggered * Retry immediately after the initial callback failed * `5 mins` after the previous callback failed * `10 mins` after the previous callback failed * `15 mins` after the previous callback failed

If your application doesn't receive callbacks from Maya, you may use the **Get Send** endpoint instead.

### Step 1: Identify the events Identify the events you want to monitor and the event payloads to parse. [block:parameters] { "data": { "h-0": "State", "h-1": "Description", "0-0": "`APPROVED`", "0-1": "When the remittance is successfully credited to the receiving account. \nSample payload: Refer to :green_circle: **200 APPROVED** in **Get Send** ", "1-0": "`DECLINED`", "1-1": "When the transaction failed. \nSample payload: Refer to :green_circle: **200 DECLINED** in **Get Send** " }, "cols": 2, "rows": 2, "align": [ "left", "left" ] } [/block] *** ### Step 2: Create a callback endpoint Create a callback 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 code.

A callback should be SSL-secured (https) and publicly available. It is also recommended to use **port 443** for your SSL configuration. Your application may experience network issues when integrating with Maya using non-standard ports.

```javascript const express = require('express'); const app = express(); app.post('/remittance/send/direct/callback', async (req, res) => { // TODO: You will have to implement the logic of this method. processMayaCallbackData(req.body); res.send({ success: true }) }); app.listen(8080, () => console.log('Listening on port ${8080}!')); ``` *** ### Step 3: Test your callback Test that your callback endpoint is working properly. You can execute your callback endpoint via a simple `curl` command or through an API client application like Postman. **Sample Callback Endpoint Test via curl** ```curl $ curl -s -D - -o /dev/null -X POST -H "Content-Type: application/json" \ -d '{ "id": "c36d9958-9c55-49e3-b70e-702b082046c0", "status": "APPROVED", "created_timestamp": "2024-06-05T04:12:43.451977Z", "updated_timestamp": "2024-06-05T04:17:12.865432Z", "confirmation_deadline": "2024-06-05T04:22:43.451995Z", "request": { "source_account": { "financial_institution_code": "PAPHPHM1XXX", "account_number": "331234567898" }, "receiver_account": { "financial_institution_code": "PAPHPHM1XXX", "account_number": "+639498187453", "account_name": "Maria Reyes" }, "sender": { "contact_information": { "type": "msisdn", "value": "+639336143939" }, "name": { "first_name": "John Mark", "middle_name": "De Guzman", "last_name": "Dela Cruz" }, "nationality": "PH", "gender": "M", "birth_date": "1995-12-31", "birth_place": { "city": "Paris", "country": "FR" }, "present_address": { "line1": "3701 Summerfield Blvd", "line2": "Suite 204", "locality": "Bastille", "state": "Paris", "zip_code": "11200", "city": "L Haÿ-les-Roses", "country": "FR" }, "permanent_address": { "line1": "3701 Summerfield Blvd", "line2": "Suite 204", "locality": "Bastille", "state": "Paris", "zip_code": "11200", "city": "Paris", "country": "FR" }, "income_source": "Salary", "additional_income_source": "Inheritance", "identification": { "type": "Passport", "number": "110-230-987-000", "issue_country": "FR", "issue_date": "2000-01-01", "expiry_date": "2050-01-01" }, "employment": { "work_nature": "IT Companies", "additional_work_nature": "Government Service (LGUs, etc.)", "position_level": "Owner", "employer_name": "Maya Bank Inc." }, "additional_information": { "hair_color": "black", "eye_color": "brown" } }, "receiver": { "contact_information": { "type": "msisdn", "value": "+639498187453" }, "name": { "first_name": "Maria", "middle_name": "Reyes", "last_name": "Reyes" }, "nationality": "PH", "gender": "F", "birth_date": "2000-01-01", "birth_place": { "city": "Parañaque City", "country": "PH" }, "present_address": { "line1": "Blk 7 Lot 24 Maligaya St.", "line2": "6F Launchpad Bldg.", "locality": "Bgry. Nagkaisang Nayon", "state": "Metro Manila", "zip_code": "1240", "city": "Parañaque City", "country": "PH" }, "permanent_address": { "line1": "Blk 7 Lot 24 Maligaya St.", "line2": "6F Launchpad Bldg.", "locality": "Bgry. Nagkaisang Nayon", "state": "Metro Manila", "zip_code": "1240", "city": "Parañaque City", "country": "PH" }, "income_source": "Salary", "additional_income_source": "Inheritance", "identification": { "type": "Government Office and GOCC IDs (AFP, NBI, etc.)", "number": "PM2512345", "issue_country": "PH", "issue_date": "2000-01-01", "expiry_date": "2050-01-01" }, "employment": { "work_nature": "IT Companies", "additional_work_nature": "E-commerce/Online Business", "position_level": "Senior Level/Executive", "employer_name": "Maya Philippines Inc." }, "additional_information": { "hair_color": "black", "eye_color": "brown" } }, "amount": { "currency": "PHP", "value": 1249.26 }, "origin_country": "PH", "transaction_purpose": "Family Support/Allowance", "relationship_to_receiver": "Father", "additional_information": { "eye_color": "brown" } }, "transfer_details": { "source": { "ending_balance": { "current_balance": { "currency": "PH", "value": 10734124.63 }, "available_balance": { "currency": "PH", "value": 10734124.63 } } }, "gross_amount": { "currency": "PHP", "value": 1018.5 }, "principal_amount": { "currency": "PHP", "value": 1000 }, "commission": { "currency": "PHP", "value": 11.5 }, "fee": { "currency": "PHP", "value": 7 } } }' \ https://83ef-130-105-160-253.ngrok.io/remittance/send/direct/callback ``` When the output of the curl command shows a `200` response code that means that your callback is reachable and will return a status `200 OK`. ```curl 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: Deploy and endorse your callback URL Deploy your callback and endorse the URL for enrollment to your **Maya Relationship Manager**.

## Enum values List of valid values for certain fields of Maya’s Remittance API.

## Retry vs Create New Transaction

Maya’s Remittance APIs enforce strict idempotency rules for each API consumer using the `x-idempotency-key` in their API requests.

Maya implemented the idempotency checks to the **Initiate Send** endpoint. ### Retry A transaction will be considered a retry when the Remittance API receives a request with the same `x-idempotency-key`.

Note that retries will **never** be processed even if the original attempt failed. Maya will reject the request with the error code **REMGTW0011** or **REMGTW0014** .

### Create New Transaction Each request with a unique and unused `x-idempotency-key` will be treated as a new transaction, even if the request body is identical to a previous attempt.

Processing a new transaction may **vary** depending on the validation and business rules of the processor and the receiving financial entity.

## Transaction Statuses

In the Maya Remittance API, the transaction `status` indicates the current state of the transaction.

Here is a transition state diagram representing the statuses of the transaction process: [block:image] { "images": [ { "image": [ "https://files.readme.io/3a17f62-maya-remittance-transition-state.png", "", "" ], "align": "center", "sizing": "50% " } ] } [/block] [block:parameters] { "data": { "h-0": "Status", "h-1": "Description", "h-2": "Results from", "0-0": "`INITIATED`", "0-1": "The transaction is initiated by the requestor and successfully validated by the service", "0-2": "Initiate Send", "1-0": "`PROCESSING`", "1-1": "The transaction has been confirmed and the balance transfer is still in progress", "1-2": "Confirm Send", "2-0": "`APPROVED`", "2-1": "The transaction is successful", "2-2": "Confirm Send", "3-0": "`DECLINED`", "3-1": "The transaction is declined during initiation or fails during processing", "3-2": "Initiate Send, \nConfirm Send", "4-0": "`LAPSED`", "4-1": "The initiated transaction is no longer valid because the confirmation deadline has been exceeded", "4-2": "Confirm Send" }, "cols": 3, "rows": 5, "align": [ "left", "left", "left" ] } [/block]

## Sandbox Test Data

Provided here are the test data you could use in the sandbox.

[block:parameters] { "data": { "h-0": "Fields", "h-1": "Description", "h-2": "Test Data", "0-0": "Source Account Details", "0-1": "Values to be used in `source_account` when using **Initiate Send** endpoint", "0-2": "To be provided after partner onboarding", "1-0": "Receiver Account Details", "1-1": "Values to be used in `receiver_account` when using **Initiate Send** endpoint", "1-2": "**Maya Wallet** \n`receiver_account.financial_institution_code` = **PAPHPHM1XXX** \n`receiver_account.account_number` = **639101000112** \n \n**Instapay - participating Bank** \n`receiver_account.financial_institution_code` = **MBTCPHMMXXX** \n`receiver_account.account_number` = **111222333**" }, "cols": 3, "rows": 2, "align": [ "left", "left", "left" ] } [/block]

## Handling Errors

When integrating with our remittance APIs, you may encounter two types of errors: **ambiguous** and **unambiguous**.

### Ambiguous errors Ambiguous errors are those whose response body does not follow any specified error response structures. They are not definitive and do not represent the actual processing result from Maya. Examples include: * Connectivity timeouts and network interruptions, often appear as *socket timeout* or *socket closed* * Interface downtimes; occur if the API gateway mediating our communication goes down. They typically show as **HTTP 503** with no response body or a response body that doesn't match any documented structure Maya recommends handling ambiguous errors by performing **Get Send** to validate the latest stats of the transaction. If an inquiry is not possible due to lack of reference, performing a retry is an alternative. ### Unambiguous errors If a transaction processing encounters an error, the response from Maya will include the error object within the response body. The error code signifies the specific issue faced during the creation and processing of the transaction. You can find the list of error codes on this page. If you want to re-attempt a transaction that encountered an error, consider creating a new transaction.
See also list of **Send Remittance Errors**

- Updated API Specifications to reclassify the following fields, now treated as **optional** in **Initiate Send** :

- Updated Code Recipe to include `x-originator-transaction-id` in the sample Initiate Send