Requests - for Payments v1 or AIS

These endpoints allow you to initiate a Payments v1 request or an AIS request, and retrieve the status of the request.

Initiate a token request

The POST /token-requests endpoint persists the required information used by AIS requests and PIS requests using the API and the Token.io Hosted Pages.

SecurityBearer or BasicAuth
Request
Request Body schema: application/json
required
object (TokenRequestOptions)

Specifies optional request parameters.

required
object (TokenRequestPayload)

Contains the details for obtaining the requested token.

Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a payment, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

post/token-requests
Request samples
application/json
{
  • "requestOptions": {
    },
  • "requestPayload": {
    }
}
Response samples
application/json
{
  • "tokenRequest": {
    }
}

Get a token request

The GET /token-requests/{requestId} endpoint retrieves a specific token request by its id.

SecurityBearer or BasicAuth
Request
path Parameters
requestId
required
string

The request id received in response to the original token request.

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a token request, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

get/token-requests/{requestId}
Request samples
Response samples
application/json
{
  • "tokenRequest": {
    }
}

Get a token request result

The GET /token-requests/{tokenRequestId}/result endpoint checks whether a token request result is available. This endpoint will return a PENDING status while the result is not available. The status will become PROCESSED once the result is available. If the request is rejected by the bank, the status will become REJECTED. The status will become EXPIRED if the request is not processed or rejected before the token request expiration.

SecurityBearer or BasicAuth
Request
path Parameters
tokenRequestId
required
string

The token request id received in response to the original token request.

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a token request, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

get/token-requests/{tokenRequestId}/result
Request samples
Response samples
application/json
{
  • "transferId": "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
  • "tokenId": "tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1",
  • "signature": {
    },
  • "status": "PROCESSED",
  • "statusReasonInformation": "The token request is processing.",
  • "bankId": "ob-modelo"
}

Initiate bank authorization

The POST /token-requests/{tokenRequestId}/authorization endpoint initiates the bank authorization process with a given bank id and token request id.

SecurityBearer or BasicAuth
Request
path Parameters
tokenRequestId
required
string

The token request id received in response to the original token request.

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq
Request Body schema: application/json
required
consentAccepted
boolean <boolean>
Default: false

This flag indicates whether the user has grated consent for the payment in the TPP's user interface.

Example: false
object (InitiateBankAuthorizationRequestCredentialsEntry)

Maps a bank-defined credential id string to a value.

useCredentialFlow
boolean <boolean>
Default: false

If true, this triggers the credential flow. The credentials map must be populated if required by the bank (see credentialFields in the response to GET /banks). Otherwise, empty credentials are used.

Example: false
useWebappCredentialsFlow
boolean <boolean>
Default: false

When useWebAppCredentialsFlow is set to true and bank's flow includes embedded steps, these steps are handled by Token.io's Hosted Pages, rather than by the customer's own pages.

Example: false
Responses
200

Successful response

400

The client specified an invalid argument

401

The authorization information is missing or invalid

403

Permission to access this endpoint is denied

404

The requested entity, such as a payment, was not found

429

Too many requests

500

An unexpected or internal server error

501

The operation was not implemented

503

Service is unavailable

504

Gateway has timed out

post/token-requests/{tokenRequestId}/authorization
Request samples
application/json
{
  • "consentAccepted": false,
  • "credentials": {
    },
  • "useCredentialFlow": false,
  • "useWebappCredentialsFlow": false
}
Response samples
application/json
{
  • "fields": {
    },
  • "oauthState": "71b624cf-af3a-4f78-9420-d6e4248a9efe"
}