API Key Requirements

The Global Payments API uses asymmetric key authentication:

1. You generate an RSA key pair (private and public key).
2. Provide Orbital with the public key.
3. Orbital will provide an API key to you, that is linked to your public key.
4. You will need to authorise requests using your API key, and sign your requests using your private key.
5. Orbital will check authorisation using the API key you provide, and verify the signature using your public key.

Generate a Key Pair

To securely sign your requests, you need to generate an RSA key pair. You can generate an RSA key pair using OpenSSL or another tool of your choice.

In future iterations, we will add self-service support so you can do this via the Client Portal.

Requirements:

• Key size: 2048 bits
• Format: PEM format

Sample script to generate key pair:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in private_key.pem -out public_key.pem

Register Your Public Key with Orbital

When sending your public key to Orbital, be sure to specify the permissions that you require:

• Read permissions: Grants read-only access to view transactions, accounts, and beneficiaries.
• Write permissions: Grants access to create payments and beneficiaries.

After generating your key pair, register your public key with us so we can verify your signed requests.

1. Send your public key and permissions requirements:
   1. Determine the most secure way with your Implementation Manager. Ideally, passcode encrypted such as an encrypted zip file. Contact our support team at [email protected] or your assigned Implementation Manager.
   2. Along with your public key, let us know which permissions are to be applied to your API key. Multiple API keys are supported, with permission configurations to suit your requirements. This entire process will need to be repeated for each API key, including an RSA key pair for each. You will need to manage your API keys and use the correct one during singing.
   3. We recommend that you have an endpoint configured that can receive and handle our webhook notifications. Please provide the production URL that will be used to receive these.
2. Key association: We will associate your public key with your API key, enabling us to verify signed requests made from your system. The permissions you specified will be applied the API key.
3. Wait for confirmation: You will receive confirmation within one business day.

❗️

Important

Please share only your public key as sharing your private key renders the key pair invalid.

Signing Your Requests

To ensure the integrity and authenticity of your requests, you must sign them using your private key.

1. Create the signature:

   • Concatenate the HTTP method, full resource (with any query or path parameters), and the JSON payload (if any) in this exact order.
   • Generate a SHA-256 hash of this content.
   • Sign this hash with your private key

2. Include the following headers in your API request:

   • x-api-key: Your API key.
   • x-signature: The Base64-encoded signature from step 1.

3. Request verification:
   The Global Payments API server will use your registered public key to verify the signature and ensure the request is authentic and has not been altered.

4. Code samples

• Resource with Path Parameter Node.js:

import * as crypto from 'crypto';

const privateKey = `-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----`;

// Example with Path Parameter
const pathPayload = 'GET/counterparty/f9c1bcab-5268-44c8-a6d5-65054bdfa46a';
const pathSignature = crypto.createSign('RSA-SHA256');
pathSignature.update(pathPayload);
const pathSignatureResult = pathSignature.sign(privateKey, 'base64');

• Resource with Query Parameters Node.js:

import * as crypto from 'crypto';

const privateKey = `-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----`;

// Example with Query Parameters
const queryPayload = 'GET/transactions?fromDate=2024-06-26T00:52:28.795Z&toDate=2024-07-27T00:52:28.795Z&status=new';
const querySignature = crypto.createSign('RSA-SHA256');
querySignature.update(queryPayload);
const querySignatureResult = querySignature.sign(privateKey, 'base64');

• Resource with Path Parameter Python:

import base64
import hashlib
from Crypto.Signature import pkcs1_15
from Crypto.PublicKey import RSA

private_key = """-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----"""

key = RSA.import_key(private_key)

# Example with Path Parameter
path_payload = 'GET/counterparty/f9c1bcab-5268-44c8-a6d5-65054bdfa46a'
path_hash = hashlib.sha256(path_payload.encode('utf-8')).digest()
path_signature = pkcs1_15.new(key).sign(path_hash)
path_signature_base64 = base64.b64encode(path_signature).decode('utf-8')

• Resource with Query Parameters Python:

import base64
import hashlib
from Crypto.Signature import pkcs1_15
from Crypto.PublicKey import RSA

private_key = """-----BEGIN PRIVATE KEY-----
[Your-Private-Key-Here]
-----END PRIVATE KEY-----"""

key = RSA.import_key(private_key)

# Example with Query Parameters
query_payload = 'GET/transactions?fromDate=2024-06-26T00:52:28.795Z&toDate=2024-07-27T00:52:28.795Z&status=new'
query_hash = hashlib.sha256(query_payload.encode('utf-8')).digest()
query_signature = pkcs1_15.new(key).sign(query_hash)
query_signature_base64 = base64.b64encode(query_signature).decode('utf-8')