Callback 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:

Payment 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 are 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 payment 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 authorisation flow contains the request-id and the request_id. You won't receive any additional credentials.

Example callback for Payments v1 API-only redirect authentication flow

https://tpp.callback.url?request-id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq&request_id=rq:3SVzgJtzu2DvaZSgRGznpdknT3dq:5zKtXEAq

or in JSON format:

{

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

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

}

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

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

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

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:

{

   "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:

Example callback for Payments v1 API-only embedded authentication flow:

https://tpp.callabck.url/?request-id=rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq&request_id=rq:43hA2P34BC9a1jwYmyjmDYBrTETA:5zKtXEAq&credential-fields=eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiT25lLXRpbWUgcGFzc2NvZGUiLCJpZCI6Im90cCJ9XX0

or in JSON format:

{

   "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:

{

    "fields": [

        {

        "description": "One-time passcode",

        "id": "otp"

        }

    ]

}

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

Callback for decoupled authentication flow

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

Example callback for Payments v1 API-only decoupled authentication flow:

https://tpp.callabck.url/?request-id=rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq&request_id=rq:3smDYdTPr4gejc9g6MrHFnAAssg8:5zKtXEAq&credential-fields=eyJmaWVsZHMiOlt7ImRlc2NyaXB0aW9uIjoiUGxlYXNlLCBhdXRob3JpemUgcGF5bWVudCB1c2luZyBtb2JpbGUgZGV2aWNlLiIsInR5cGUiOiJERUNPVVBMRUQifV19

or in JSON format:

{

    "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:

{

    "fields": [

        {

        "description": "Please, authorize payment using mobile device.",

        "type": "DECOUPLED"

        }

    ]

}

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