In Maya, Basic Authentication is used in the following products/solutions:

Maya Online Payments (Maya Checkout, Maya Vault, Pay with Maya)

Payments Processing Platform

Cash-in to Maya Wallet (Cash-in via Maya Login, Cash-in via Code, Cash-in via Mini App)

Remittance to Maya Wallet

Overview

Basic Authentication is one of the simplest ways to authenticate an API request. It works by sending an encoded Base64 value of the username and password in the request header. In Maya, these credentials are the API keys provided to you after onboarding.

An API Key is a unique identifier used to authenticate a client or application when making API requests. Think of it as a password that grants access to an API.

Maya provides two types of API Keys: the public key and the secret key. You may acquire these keys in different ways, depending on the Maya solution you are trying to integrate with:

Maya Manager 1.0: An all-in-one dashboard that gives partners total control over their business. Refer to the Quick Start Guide with Maya Manager 1.0 and get started.
Maya Business Manager: The latest dashboard that also gives partners total control over their business. Refer to the Quick Start Guide with Maya Business Manager and get started.

For other solutions not available in Maya Manager 1.0 or Maya Business Manager, your Maya Relationship Manager, a representative of Maya will assist you on your journey. They are your point of contact within Maya.

Acquiring Your API Keys

There are different ways of acquiring your API keys, depending on the solution you are trying to integrate with.

Keep in Mind

Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. See the API Environment to familiarize the API environments of Maya.

API credentials are specific to the Maya solution you will be using

A. Generate via Maya Manager 1.0

Applicable to Maya Online Payments.

Here are the steps to generate your API keys via the Maya Manager 1.0:

Login into Maya Manager Sandbox (https://manager-sandbox.paymaya.com/).
Go to the menu on the left side of the screen and look for API Keys.
On the main navigation, select the Merchant name you registered earlier, then generate the API key by clicking Generate API Key.
After being redirected to another screen, create keys for both Public and Secret policies.
Click Create, then your unencrypted API keys will be shown on the screen. This is the only time you can visibly see this; only the masked values will be reflected once you exit.
Copy and store the generated public and secret API keys in a secure and encrypted location. Do not store your keys anywhere that unauthorized personnel can access.

B. Generate via Maya Business Manager

Can support Maya Checkout only.

Here are the steps to generate your API keys via the Maya Business Manager:

Login into Maya Business Manager (https://pbm.paymaya.com/).
On the sidebar, navigate through “Solutions” and choose an activated online payment solution; for example, “Maya Checkout”.
Click “Set up Online Payments”.
On the Set up Online Payments form, fill out the website name field, choose where you will be using the Maya Checkout, and select the platform you are using. Click Submit.
Unencrypted API keys will be shown on the screen. This is the only time you can visibly see this; once you exit, only the masked values will be reflected.
Copy and store the generated public and secret API keys in a secure and encrypted location. Do not store your keys anywhere that unauthorized personnel can access.

C. Acquire from Your Maya Relationship Manager

Your assigned Maya Relationship Manager will assist you in acquiring your API keys for other solutions not available in Maya Manager 1.0 or Maya Business Manager (e.g., Payments Processing Platform, Cash-in to Maya Wallet).

During onboarding, the Maya Relationship Manager will ask you to nominate a key recipient and provide their public GPG key and email address. If you are unfamiliar with GPG, see the GNUPG document and start importing a public GPG key.

This public GPG key will only be used for encrypting files or details such as your API keys, before sending it to your nominated email. It will not be used during integration or when sending an API request to Maya.

Once onboarded, the API keys or credentials will be sent to your nominated key recipient. These credentials will be stored in an encrypted file using the submitted public GPG key. Refer to the GNUPG document to start decrypting your file.

Storing Your API Keys

API keys will be used to authenticate your application, so save them in a secure location. Misuse or mishandling of tokens or keys within the jurisdiction of the Partner could entail risks and vulnerability of transactions.

If your API keys are lost or breached, delete the old API keys and generate new ones in the same environment.

Using the API Keys for Basic Authentication

Now that you have acquired your API keys, you may now start using them to verify your identity as an authorized entity accessing the Maya endpoints. API Authentication is performed during the transaction requests.

Be sure to review the endpoint and API specifications document. Look out for reminders or callouts within the documentation to help identify which type of API key is required for authentication, whether it is a public key (pk-....) or a secret (sk-....) key.

Sample callouts:

For Basic Authentication, use PUBLIC KEY. Learn more →

For Basic Authentication, use SECRET KEY. Learn more →

How to use Basic Authentication:

Format the credentials. Use the required key as the username, then put a colon (':') after it. Leave the password blank (do not type anything after the colon). For example, if your API key is pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah, the resulting string is:

pk-Z0OSzLvIcOI2UIvDhdTGVVfRSSeiGStnceqwUE7n0Ah:

Convert to Base64. The next step is to encode the formatted string from Step 1 using Base64. You can use an online Base64 encoder or do it in code (e.g., in Python: base64.b64encode(b"your_api_key:").decode()). If we encode the example API key, it becomes:

cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=

Add the Authorization header. In your API request, include an Authorization header. The value should be "Basic " followed by the Base64-encoded string from Step 2. Given the previous examples, the Authorization header will look like:

Authorization: Basic cGstWjBPU3pMdkljT0kyVUl2RGhkVEdWVmZSU1NlaUdTdG5jZXF3VUU3bjBBaDo=

Sample Codes

import base64

username = "client_id"
password = "client_secret"
credentials = f"{username}:{password}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()

print("Basic " + encoded_credentials)

const username = "client_id";
const password = "client_secret";
const credentials = `${username}:${password}`;
const encodedCredentials = btoa(credentials);

console.log("Basic " + encodedCredentials);

Handling the Expired API Keys

The validity of the API keys varies on each Maya solution.

For API keys generated via Maya Manager 1.0 and Maya Business Manager, you can verify the expiry of the keys on the Manager where the keys were generated. You can then renew the keys by generating new ones.
For API keys provided via email, Maya will reach out to your point of contact to remind you when the API keys are about to expire. You can also reach out to your Maya Relationship Manager whenever you want to request renewal or regenerate your API keys.

Handling of API Key related Errors

There is a specific list of errors per Maya Solution:

Next Steps

Aside from the Authorization header, there are required fields that you must include in the API request. Be sure to review the API documentation of the solution you are integrating with for the correct specifications.

Basic Authentication