JWT Tokens

Summary

Each request to the payment API will need a JWT token as part of the header of the request. JWT is a standard for encoding data so that is can be verified on the receiving side as coming from you. In order to start creating JWT tokens, you'll need your API key and company ID from us. We'll supply these details after we are able to get you signed up and setup in our system.

JWT token generation

You can find more information about JWT here: https://jwt.io
They have links to libraries for various languages. Below are some examples for a few languages. You will need to generate this token on your side and using your language of choice. The expiration date can be short or long depending on how long you want to keep your token alive, but we don't recommend setting an expiration date longer than 12 hours and less is recommended. Keep in mind that you can also generate a new token with every request.

The token must include a key/value payload with the key being "company_id" and value being your company id. You can see this in the examples below.

# https://github.com/firebase/php-jwt

function generateJwtToken($dataToEncode) {
    $issuedAt = time();
    $token = [];
    $token['iat'] = $issuedAt;
    $token['jti'] = bin2hex(openssl_random_pseudo_bytes(32));
    $token['nbf'] = $issuedAt;
    $token['exp'] = $issuedAt + (60 * 60 * 12); // Expiration in seconds
    $token['data'] = $dataToEncode;
    return \Firebase\JWT\JWT::encode($token, 'your-private-token-here');
}
$tokenToSendInHeader = generateJwtToken(['company_id' => 1]);

// https://github.com/auth0/java-jwt

public static String generateJwtToken()
{
    Algorithm algorithm = Algorithm.HMAC256("your-private-token-here");
    Map<String, Object> data = new HashMap<>();
        data.put("company_id", "your-company-id-here");
    String token = JWT.create()
        .withExpiresAt(new Date(System.currentTimeMillis() + (15 * 60 * 1000))) // 15 minutes)
        .withClaim("data", data)
        .sign(algorithm);
    return token;
}

# https://github.com/jpadilla/pyjwt

payload = {
  "data": {"company_id": "1"}, 
  "exp": datetime.datetime.now(tz=timezone.utc) + datetime.timedelta(seconds=60 * 60 * 12)
}
token = jwt.encode(payload, "your-private-token-here", algorithm="HS256")

# https://github.com/jwt/ruby-jwt

require 'jwt'

payload = { data: [company_id: 1], exp: Time.now.to_i + 60 * 60 * 12 }
token = JWT.encode payload, 'your-private-token-here', 'HS256'

HTTP Header

The JWT token generated by your code needs to be included in the header of each request to our system. The header will look something like below but have your generated token instead.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9eyJpYXQiOjE2NDcwMTgzNDYsImp0aS