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.

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:

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

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.

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.

Maya will acknowledge receipt of the request by responding with the initial remittance status update: PROCESSING while conducting validations and proceeding with the transfer.

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

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

Step 1: Identify the events

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

State	Description
APPROVED	When the remittance is successfully credited to the receiving account. Sample payload: Refer to 🟢 200 APPROVED in Get Send
DECLINED	When the transaction failed. Sample payload: Refer to 🟢 200 DECLINED in Get Send

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.

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 -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.

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.

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.

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.

Here is a transition state diagram representing the statuses of the transaction process:

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