About Auth API

The Authorization Controller API (Auth API) is a webhook that allows you to participate in the authorization decision-making process in real time.

When Galileo receives an ISO 8583 authorization request from the network, it performs initial checks such as validating the PIN, verifying account status, and checking account balance. Galileo calculates the response code, converts the request into the Auth API webhook, and passes it to you so that you can make the final decision—whether to accept Galileo's verdict or override.

For more information see the Authorization Controller API guide.

Versions

There are currently two supported versions of the Auth API: 2.0 and 3.0. Version 3 is a breaking change from version 2. See Differences between version 2 and version 3 in the Authorization Controller API guide.

Security

Use HTTPS for the Auth API webhook to ensure fundamental security is in place. Galileo supports TLS 1.2.

Galileo uses JSON web tokens (JWTs) to authenticate the webhook. A shared secret encodes and decodes the token.

The payload will have the following arguments:

• iat — Issued-at time
• exp — Expiration time
• iss — galileo

The times are expressed as Unix epoch time.

The token is created using this Python code:

import jwt
from datetime import datetime, timedelta
payload = {
    'exp': datetime.utcnow() + timedelta(seconds=5),
    'iat': datetime.utcnow(),
    'iss': 'galileo'
}
token = jwt.encode(payload, secret, algorithm='HS256')

where secret is the shared secret.

The token is placed in the Authorization header field.

Security Example

This is the header value for exp = 1534274886 and iat = 1534274881:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnYWxpbGVvIiwiaWF0IjoxNTM0Mjc0ODgxLCJleHAiOjE1MzQyNzQ4ODZ9.1xUk4iNFGWLo01MyJUHXRlyrNlzwPvDMSXpN38TrblU

Paths

You provide a base URL, hosted by a server in your system. Galileo invokes your webhook at the /Authorization endpoint.

Examples

These are some examples of how you use the Auth API. See Overrides in the Authorization Controller API guide for details.

Overriding the response code

1. Galileo receives an authorization request and plans to approve it (response_code: 00) because all validation checks passed and the account has sufficient funds.
2. Galileo sends the Auth API webhook to you.
3. You determine that the transaction amount is above a limit, so you return response_code: 61 (Exceeds amount limit), and the transaction is declined.

When you maintain the balance:

For your program, you may be the system of record for client accounts instead of Galileo.

1. Galileo gets a balance inquiry, but because Galileo does not have the latest balance, Galileo invokes your Auth API webhook.
2. You return the balance available in the available_balance field and Galileo relays that balance to the network.

Client initiates transfer

1. Galileo receives an authorization request and the cardholder has insufficient funds, so Galileo calculates response_code: 51.
2. Galileo sends you the Auth API webhook.
3. You see that the account has insufficient funds, so you initiate a transfer by populating the transfer_prn and transfer_amount. (This must be set up specially at Galileo before using.)
4. After the transfer, the cardholder has sufficient funds, and Galileo approves the request.

For examples of webhook code, see the Auth API v3 webhook examples in the Authorization Controller API guide.