Authentication

Beam API authenticates your requests to ensure that they really come from you.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail with the relevant error being returned to you.

You need to provide one of three types of key, depending on who you are and what API you call.

Merchant API Key

Merchant API Key is used when you make a request from the server side.

Authentication to the API is performed via HTTP Basic Auth , using your Merchant ID as the username and your Merchant API Key as the password (more details below).

Your Merchant API Key can be self-managed through your account in Lighthouse  under the Developers section.

Here is an example of Merchant API key usage to create a charge:

POST /api/v1/charges
Authorization: Basic <credentials>

(create charge request body)
{
    ...
}

Partner API Key

If you are a partner that wants to make a request for a merchant under you, please use Partner API Key to make the request from your server.

Authentication to the API is performed via HTTP Basic Auth , using your Merchant ID as the username and your Partner API Key as the password (more details below).

You also need to provide your Beam Partner ID in the header X-Beam-Partner-ID.

Your Partner API Key can be self-managed through your account in Bridge  under the Merchants > API Keys section.

Here is an example of Partner API key usage to create a charge:

POST /api/v1/charges
X-Beam-Partner-ID: <partnerId>
Authorization: Basic <credentials>

(create charge request body)
{
    ...
}

Publishable Key

Publishable Key is used when you make a request from client side to API endpoints with /client prefix, for example Card Tokenization API.

Authentication to the API is performed via HTTP Basic Auth , using your Merchant ID as the username and your Publishable Key as the password (more details below).

Here is an example of publishable key usage to create a card token:

POST /client/v1/card-tokens
Authorization: Basic <credentials>

{
    "pan": "<...>",
    "cardHolderName": "<...>",
    "expiryYear": ...,
    "expiryMonth": ...
}

Basic Auth

In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where is the Base64 encoding of ID and password joined by a single colon :.

This is how to perform HTTP Basic Auth with aforementioned username and password.

1. Concatenate the username and password with a single colon :.
2. Encode the resulting string using Base64 with padding.

For example, if the username is beam and the password is UJhQ0mTwkn1g05E7rGGI7jwRmfaaOEiDkY2W+p56YX8=, the resulting credentials will be YmVhbTpVSmhRMG1Ud2tuMWcwNUU3ckdHSTdqd1JtZmFhT0VpRGtZMlcrcDU2WVg4PQ==. Therefore, the authorization header will be:

Authorization: Basic YmVhbTpVSmhRMG1Ud2tuMWcwNUU3ckdHSTdqd1JtZmFhT0VpRGtZMlcrcDU2WVg4PQ==