Callback response for API-only integration

For the API-only integration callback, the bank calls back to Token.io and Token.io calls back to the TPP - as shown here:

AIS initiation starts from the POST /token-requests/{tokenRequestId}/authorization endpoint with bank authorization, using a given token request ID. If you've redirected the user to the redirect URL provided in the response for the POST /token-requests/{tokenRequestId}/authorization call, the bank will call back to Token.io. Token.io will process the callback and call back to you. The callback parameters normally include the token request-id, but if this is followed by an embedded or decoupled step, additional credential-fields will be returned.

In the callback response you may receive:

request-id AND request_id ONLY - these are mandatory fields; you'll then need to call GET /token-requests/{tokenRequestId}/result to get the authorization result.
request-id AND request_id AND credential-fields - you'll then follow the process for receiving additional credentials in the POST /token-requests/{tokenRequestId}/authorization response.
error response - this means an error occurred; check the gRPC code.

Callback for redirect authentication flow

The callback for redirect authentication flow contains the request-id and the request_id. You won't receive any additional credentials.

https://{% $THIRDPARTY %}.callback.url?request-id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq&request_id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq

or in JSON format:

Example callback for AIS v1 API-only redirect authentication flow


    "request-id": "rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq",

    "request_id": "rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq"

}

After this, you should call GET /token-requests/{tokenRequestId}/result to get the AIS authorization result.

If the callback is unsuccessful, a gRPC code is displayed:

https://{% $THIRDPARTY %}.callabck.url?request-id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq&request_id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq&trace-id=idm45Ag1X8D8Kvdw&error=14&message=Bank+is+unavailable

or in JSON format:

Example callback for AIS v1 API-only redirect authentication flow with error

{

    "request-id": "rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq",

    "request_id": "rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq"

    "trace-id": "idm45Ag1X8D8Kvdw",

    "error": 14,

    "message": "Bank is unavailable"

}

Callback for embedded authentication flow

If more credentials are required, for example if you're using an embedded authentication flow, additional credentials will be returned in the callback URL in the credential-fields query parameter:

https://{% $THIRDPARTY %}.callabck.url/?request-id=rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq&request_id=rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq&credential-fields=eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiT25lLXRpbWUgcGFzc2NvZGUiLCJpZCI6Im90cCJ9XX0

or in JSON format:

Example callback for AIS v1 API-only embedded authentication flow

{

    "request-id": "rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq",

    "request_id": "rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq",

    "credential-fields": "eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiT25lLXRpbWUgcGFzc2NvZGUiLCJpZCI6Im90cCJ9XX0"

}

In this example, once you base64-decode the value of credential-fields, you'll see:

base64-decoded credential-fields for AIS v1 embedded authentication flow

{

    "fields": [

        {

        "description": "One-time passcode",

        "id": "otp"

        }

    ]

}

The decoded credentials have the same structure as credentials returned in the initiation response.

Callback for decoupled authentication flow

If a decoupled authentication step is required after the callback, additional credentials will be returned in the callback URL in the credential-fields query parameter.

https://{% $THIRDPARTY %}.callabck.url/?request-id=rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq&request_id=rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq&credential-fields=eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiUGxlYXNlLCBhdXRob3JpemUgcGF5bWVudCB1c2luZyBtb2JpbGUgZGV2aWNlLiIsInR5cGUiOiJERUNPVVBMRUQifV19

or in JSON format:

Example callback for AIS v1 API-only decoupled authentication flow

{

    "request-id": "rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq",

    "request_id": "rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq",

    "credential-fields": "eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiUGxlYXNlLCBhdXRob3JpemUgcGF5bWVudCB1c2luZyBtb2JpbGUgZGV2aWNlLiIsInR5cGUiOiJERUNPVVBMRUQifV19"

}

In this example, once you base64-decode the value of credential-fields, you'll see:

base64-decoded credential-fields for AIS v1 decoupled authentication flow

{

    "fields": [

        {

        "description": "Please, authorize AIS request using mobile device.",

        "type": "DECOUPLED"

        }

    ]

}

If you have any feedback about the developer documentation, please contact devdocs@token.io