How API Authentication Works in Maya Checkout

Overview

API authentication ensures that requests to Maya Checkout come from trusted sources. This prevents unauthorized access, protects sensitive data, and ensures only approved applications can interact with the payment system.

Maya Checkout uses Basic Authentication for the API requests. It is one of the simplest ways to authenticate an API request.

Before you begin with this guide, make sure you have completed the onboarding with Maya Checkout and have obtained your API Keys: Public Key (pk-...) and Secret Key (sk-...). To set up your credentials, refer to either of the following getting-started pages:

For direct-to-production commitment, refer to Getting Started in Maya Checkout (Maya Business Manager)
For sales-assisted, refer to Getting Started in Maya Checkout (Maya Manager 1.0)

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

Store and manage API keys securely
Use Basic Authentication in API requests
Handle expired API keys

What is an API Key in Maya Checkout?

An API Key is a unique identifier that authenticates your application when it communicates with Maya Checkout. You can think of it as a secure password that defines what your system is allowed to do.

Maya Checkout provides two types of API keys: the public key and the secret key, each with different permissions and use cases.

Choosing the Right Key

Which key to use depends on the specific endpoint you’re calling:

Refer to the Endpoints section in the Maya Checkout implementation guides. It lists all relevant endpoints along with the required API key for each.
Watch for callouts in the API specifications, which explicitly state whether a request requires a Public Key or a Secret Key.

Using the wrong key may cause authentication failures.

Storing Your API Keys

Keep keys in a secure vault or secrets manager.
If keys are compromised or lost:
- Revoke the old keys.
- Generate new keys in the same environment.

Misuse or mishandling of tokens or keys within the jurisdiction of the Partner, could entail risks and vulnerability of transactions.

Using the API Keys for 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=

Base64 is encoding, not encryption. Always send API requests over HTTPS to keep your credentials secure.

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=

Code Samples:

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

Expired API keys will prevent your requests from being authenticated in Maya Checkout.

Regenerate keys – When a key expires, create a new one directly from Maya Manager 1.0 or Maya Business Manager, depending on where your account is managed.
Update your application – Replace the expired key in your application or server configuration immediately to restore API access.

Handling of API Key-related Errors

Invalid or expired API keys will return specific error codes. Refer to the error guide to learn how to identify error codes and implement proper handling for Maya Checkout.

Next Steps

Now that you understand how to securely store and use your API keys, you’re ready to continue with your Maya Checkout integration.

Explore the implementation guides
Review the API specifications
- Confirm which type of key to use (Public vs Secret) for each endpoint
- Double-check all required fields to avoid integration errors