API Credentials

🚧

Before You Begin

You must have a BlueSnap account to generate API credentials. If you don't have an account, go to our New Signup page.

BlueSnap API credentials let you communicate with our developer APIs, such as the Payment API or the Reporting API. These APIs let you send and receive information to perform critical business actions, such as process transactions or retrieve reporting information from within your platform. For details about how to use your API credentials in an API request, see Authentication & Headers.

Types of API Credentials

A BlueSnap merchant account can have two types of API credentials:

• Primary — Main credentials associated with your merchant account. Each merchant ID (MID) can be associated with only one set of primary API credentials.
• Secondary — Restricted credentials to perform limited API actions. In some circumstances, you might want to provide a third party access to your BlueSnap account. You can generate restricted API credentials for these secondary users, and you can grant permissions to control access. A secondary user account can have permissions that are equal to or a subset of the primary account's permissions.

Inherited Attributes

Secondary API credentials inherit key attributes from the primary account that generates them.

Authorized IPs

Secondary API credentials have the same authorized IP addresses as the primary API credentials. Updates to the authorized IPs for the primary credentials are inherited by the secondary credentials.

Define the authorized IPs on Settings > API Settings.

Permission restrictions

Secondary API credentials have restricted permissions that are a subset of the permissions granted to the primary API credentials. This means that you cannot grant permissions to secondary API credentials that are not granted to the primary API credentials.

In addition, consider the following when granting permissions:

• When you remove a permission from the primary API credentials, that permission is removed from the secondary API credentials.
• When you add a permission to the primary API credentials, it is not added automatically inherited. You must manually add it to the secondary API credentials.

Lock Status

When the account associated with the primary API credentials is locked, all secondary API credentials are locked. After you unlock the primary account, you must manually unlock the secondary account. For assistance unlocking an account, contact BlueSnap Merchant Support.

Managing Credentials

You generate and manage both primary and secondary API credentials from Settings > API Settings in the Merchant Portal.

Generating Primary API Credentials

Complete the following to create your primary API credentials:

1. In the Merchant Portal, go to Settings > API Settings.
2. In API Credentials, create an API password and enter it in the Password field. Store your API password in a safe location for later use.
   The API password has the following requirements and restrictions:
   • Minimum 12 characters
   • Maximum 128 characters
   • ASCII characters only: a–z A–Z 0–9 _ ~ ! @ # & $ % ^ * ( ) | ' -
   • One uppercase letter
   • One lowercase letter
   • One special character
   • One digit
   • Cannot be the same as the user key
   • Cannot be formatted like an email address
3. In Authorized IPs, add IP addresses that you wan to authorize to call BlueSnap API servers with your credentials. You can add up to 15 IP addresses or a subnet.
   To enter a single IP address, enter values into the first four boxes and select Add. To enter a range of consecutive IP addresses, enter the starting IP address in the first four boxes. In the fifth box, enter the last octet of the final IP address in the range.
   After you add one IP address, you cannot remove all IP addresses from your account. You must always have one permitted IP address associated with your account.
4. (Optional) In Disable IP Checking, select the Disable IP Checking option if you do not want BlueSnap to verify your IP.

   🚧

   Warning

   IP checking adds an important security layer for your account. Do not disable IP checking unless you cannot provide a static IP address for your account.

5. Select Request API credentials.

Your credentials are generated and your API key is displayed in API User Key.

Generating Secondary API Credentials

After you generate your primary API credentials, you can generate secondary API credentials:

1. In the Merchant Portal, go to Settings > API Settings.
2. In API Credentials, select Add Credentials. A new page displays where you can define secondary API credentials.
   The API key is listed in API User Key.
3. In Password, enter a password for the secondary credentials. This password cannot be the same as the password for the primary account. It has the same restrictions as the primary account credentials.
4. Re-enter the password in Verify your password.
5. Select the permissions that you want to grant to these API credentails:
   • Reporting — Retrieve and view reports.
   • Retrieve Transactions — Retrieve and view transactions. This does not grant permission to create or update a transaction.
   • Issue Refunds — Issue refunds for transactions.
   • Shopper — Create, retrieve, update, or delete a shopper.
     To enable additional permisssions, speak with Merchant Support.

To view, edit, and delete secondary API credentials, select View Credentials in the API Credentials section.