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 SoFi Tech Solutions 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. We calculate the response code, convert the request into the Auth API webhook, and pass it to you so that you can make the final decision—whether to accept or 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. SoFi Tech Solutions supports TLS 1.2.

SoFi Tech Solutions 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. SoFi Tech Solutions 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

SoFi Tech Solutions receives an authorization request, but we are not the system of record for your program. Although the transaction passes all validation checks, we cannot determine whether the account has sufficient funds, so we calculate response_code: 51 (Non-sufficient funds and not a force post).
We sends the Auth API webhook to you.
Because you maintain 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

SoFi Tech Solutions receives an authorization request and the cardholder has insufficient funds, so we calculate response_code: 51.
We send you the Auth API webhook.
You see that the account has insufficient funds, so you initiate a transfer by populating transfer_prn and transfer_amount. (This must be configured specially during product setup.)
After the transfer, the cardholder has sufficient funds, so we approve the request with response_code: 00.

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