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 for details.

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, but Galileo is not the system of record for your program. Although the transaction passes all validation checks, Galileo cannot determine whether the account has sufficient funds, so Galleo calculates response_code: 51 (Non-sufficient funds and not a force post).
2. Galileo sends the Auth API webhook to you.
3. Because you maintain the your own ledgers, you see that the account has sufficient funds, so you return response_code: 00 (Success), and the transaction is authorized.

Transfer with override

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 transfer_prn and transfer_amount. (This must be set up specially at Galileo before using.)
4. After the transfer, the cardholder has sufficient funds, so Galileo approves the request with response_code: 00.

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