Requests - for Payments v1 or AIS

Payments v2

These endpoints enable you to make v2 single immediate payments and future dated payments using the redirect, embedded and decoupled flows.

Operations

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.

Operations

Initiate a token request

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.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

requestOptionsobject(TokenRequestOptions)

Specifies optional request parameters.

requestPayloadPIS - Payments (object) or PIS - Standing Orders (object) or AIS (object)(TokenRequestPayload)required

One of:

Contains the details for obtaining the requested token.

requestPayload.transferBodyobject(TokenRequestPayloadTransferBody)required

Contains the financial details of the transfer.

requestPayload.transferBody.confirmFundsboolean(boolean)

If true, sufficient funds available for transfer are confirmed.

Default false

Example: false

requestPayload.transferBody.currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"

requestPayload.transferBody.executionDatestring

Specifies the execution date for the transfer (in ISO 8601 format).

Example: "2023-02-28"

requestPayload.transferBody.instructionsobject(TransferInstructions)required

Contains the transfer instructions for each payment.

requestPayload.transferBody.instructions.metadataobject(Metadata)

Information governing or otherwise related to the transfer instructions.

requestPayload.transferBody.instructions.sourceobject(TransferDebtorEndpoint)

Contains information about the payer account.

requestPayload.transferBody.instructions.transferDestinationsArray of sepa (object) or sepaInstant (object) or fasterPayments (object) or elixir (object) or euDomesticNonEuro (object) or euDomesticNonEuroInstant (object) or bankgiro (object) or plusgiro (object) or token (object) or virtualAccount (object)(TransferDestination)non-emptyrequired

The beneficiary account specifying the transfer destination, i.e., TPP/merchant/creditor bank account.

One of:

The beneficiary account specifying the transfer destination, i.e. TPP/merchant/creditor bank.

requestPayload.transferBody.instructions.transferDestinations[].sepaobject(sepa)required

requestPayload.transferBody.instructions.transferDestinations[].customerDataobject(CustomerDataCreditor)required

Specifies the legal identity information for the payee. This information is not required for settlement accounts.

requestPayload.transferBody.instructions.transferDestinations[].typestring(type)

Specifies the type of transfer destination.

Default "UNKNOWN"

Enum"UNKNOWN""BUSINESS""PERSONAL"

Example: "BUSINESS"

requestPayload.transferBody.lifetimeAmountstringrequired

The total amount, with up to four digits after the decimal point, transferred over the life of the token.

Example: "10000.00"

requestPayload.transferBody.remittanceReferencestring

The creditor's reference for matching an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts receivable system.

Example: "MFt6s64vn6aDyMiwBA3"

requestPayload.transferBody.returnRefundAccountboolean(boolean)

Requests that a refund account be returned in the response of GET transfers for any amounts refunded.

Default false

Example: false

requestPayload.transferBody.setTransferDestinationsUrlstring

destination.url.com

requestPayload.actingAsobject(ActingAs)

Specifies another party for whom the token was created 'on behalf of'.

requestPayload.callbackStatestring(callbackState)

The developer-specified string allowing the state to be persisted between the request and callback phases of the flow; used for the signature in a GET /token-requests/{tokenRequestId}/token-request-result call, in which the signing payload for the signature is a combination of state and tokenId, and validates the tokenId against the callbackstate originally sent in the request.
Note: The value of callbackState is added to the redirect URL and appended to the hash of the CSRF token.

Example: "6242e45e-3063-4c42-8376"

requestPayload.countriesArray of strings

Specifies the destination country or countries, using the two-letter country code in upper case (ISO 3166-1 alpha-2). This is used to limit the number of countries displayed in the Hosted Pages for user selection.

Example: ["DE","IT","RO"]

requestPayload.descriptionstring

Description of the payment with the following qualifiers:

must comply with the constraint imposed by the bank
length must be no greater than 255 characters
description in a subsequent call must match description in originating request
description omitted in originating request must also be omitted in subsequent calls
description omitted in subsequent call will be replaced with refId
the description field maps to description in the bank's consentRequest presented to the user

Example: "A regular payment"

requestPayload.disableFutureDatedPaymentConversionboolean(boolean)

This field determines whether a payment can been converted from a single immediate payment to a future dated payment. If set to false, payments can be converted.

Default false

Example: false

requestPayload.redirectUrlstringrequired

This URL redirects the user after bank authentication.

Example: "http://psu-redirect.com"

requestPayload.refIdstring(refId)required

The TPP-generated reference identifier for the token. This is not to be confused with the requestId. The refId maps to the tppRefId in the bank's consentRequest. This is needed to match/verify the originating token request with the bank's consent request.
We recommend that the refId should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.

Example: "9htio4a1sp2akdr1aa"

requestPayload.toobject(TokenMember)required

Contains information identifying the Token.io member.

requestPayload.to.aliasobject(Alias)

Alternate or additional member identification information.

requestPayload.to.idstring(id)required

The Token.io-assigned memberId of the TPP.

Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

requestPayload.userRefIdstring(userRefId)

The Token.io-generated unique reference for the user.

Example: "3jdaWmcewrj3MX0CDS"

curl -i -X POST \
  https://api.token.io/token-requests \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "requestOptions": {
      "bankId": "ob-modelo",
      "from": {
        "alias": {
          "realmId": "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq",
          "type": "EMAIL",
          "value": "e-sales@token.io"
        },
        "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"
      },
      "psuId": "a:TASDo3124fcsmF0vsmdv4mf4mklsdwls3mcixz14fkasdv5",
      "receiptRequested": false,
      "tokenInternal": {
        "redirectUrl": "http://psu-redirect.com",
        "usingWebApp": false
      }
    },
    "requestPayload": {
      "actingAs": {
        "displayName": "The Great Baking Co.",
        "refId": "9htio4a1sp2akdr1aa",
        "secondaryName": "jane.doe@company.com"
      },
      "callbackState": "6242e45e-3063-4c42-8376",
      "countries": [
        "DE",
        "IT",
        "RO"
      ],
      "description": "A regular payment",
      "disableFutureDatedPaymentConversion": false,
      "redirectUrl": "http://psu-redirect.com",
      "refId": "9htio4a1sp2akdr1aa",
      "to": {
        "alias": {
          "realmId": "m:vHZUAMFt6s64vn6aDyMiwBYbPDN:5zKtXEAq",
          "type": "EMAIL",
          "value": "e-sales@token.io"
        },
        "id": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"
      },
      "userRefId": "3jdaWmcewrj3MX0CDS",
      "transferBody": {
        "confirmFunds": false,
        "currency": "EUR",
        "executionDate": "2023-02-28",
        "instructions": {
          "metadata": {
            "chargeBearer": "CRED",
            "providerTransferMetadata": {
              "cma9TransferMetadata": {
                "endToEndIdentification": "string",
                "instructionIdentification": "string",
                "risk": {
                  "deliveryAddress": {
                    "addressLine": [
                      "Flat 2, The Red Lodge, 1 High Street"
                    ],
                    "addressType": "BUSINESS",
                    "buildingNumber": "1",
                    "country": "GB",
                    "countrySubDivision": [
                      "North Yorkshire"
                    ],
                    "department": "1",
                    "postCode": "YO62 5JB",
                    "streetName": "High Street",
                    "subDepartment": "Flat 2",
                    "townName": "York"
                  },
                  "merchantCustomerIdentification": "0000789123",
                  "paymentContextCode": "PISP_PAYEE",
                  "paymentPurposeCode": "DVPM",
                  "beneficiaryAccountType": "BUSINESS",
                  "contractPresentIndicator": "true",
                  "beneficiaryPrepopulatedIndicator": "true"
                }
              }
            },
            "purposeCode": "DVPM",
            "ultimateCreditor": "ACME GmbH",
            "ultimateDebtor": "John Smith"
          },
          "source": {
            "accountIdentifier": {
              "bankgiro": {
                "bankgiroNumber": "56781234"
              }
            },
            "bankId": "ob-modelo",
            "bic": "BOFIIE2D",
            "customerData": {
              "address": {
                "city": "Berlin",
                "conscriptionNumber": "2831",
                "country": "DE",
                "district": "Friedrichshain",
                "flats": "21A - 21C",
                "full": "Fifth house on the left after the village oak, Smalltown, Smallcountry",
                "hamlet": "Botzowviertel",
                "houseName": "Grossen Blauen Haus",
                "houseNumber": "123",
                "place": "Arnswalder Platz",
                "postCode": "10243",
                "province": "BC",
                "state": "CA",
                "street": "Hans-Otto-Strasse",
                "subdistrict": "Friedrichshain Nord",
                "suburb": "Altona Meadows Suburb"
              },
              "legalNames": "Mr John Arthur Smith"
            }
          },
          "transferDestinations": [
            {
              "customerData": {
                "address": {
                  "city": "Berlin",
                  "conscriptionNumber": "2831",
                  "country": "DE",
                  "district": "Friedrichshain",
                  "flats": "21A - 21C",
                  "full": "Fifth house on the left after the village oak, Smalltown, Smallcountry",
                  "hamlet": "Botzowviertel",
                  "houseName": "Grossen Blauen Haus",
                  "houseNumber": "123",
                  "place": "Arnswalder Platz",
                  "postCode": "10243",
                  "province": "BC",
                  "state": "CA",
                  "street": "Hans-Otto-Strasse",
                  "subdistrict": "Friedrichshain Nord",
                  "suburb": "Altona Meadows Suburb"
                },
                "legalNames": "Mr John Arthur Smith"
              },
              "type": "BUSINESS",
              "sepa": {
                "iban": "GB29NWBK60161331926819",
                "bic": "BOFIIE2D"
              }
            }
          ]
        },
        "lifetimeAmount": "10000.00",
        "remittanceReference": "MFt6s64vn6aDyMiwBA3",
        "returnRefundAccount": false,
        "setTransferDestinationsUrl": "string"
      }
    }
  }'

Responses

Successful response

Bodyapplication/json

tokenRequestobject(TokenRequest)

Contains the response to the submitted request.

Response

application/json

{
  "tokenRequest": {
    "id": "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq",
    "requestOptions": { … },
    "requestPayload": { … }
  }
}

Get a token request

Request

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

Security

Bearer or BasicAuth

Path

requestIdstringrequired

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

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

curl -i -X GET \
  https://api.token.io/token-requests/rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

tokenRequestobject(TokenRequest)

Contains the response to the submitted request.

Response

application/json

{
  "tokenRequest": {
    "id": "rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq",
    "requestOptions": { … },
    "requestPayload": { … }
  }
}

Get a token request result

Request

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.

Security

Bearer or BasicAuth

Path

tokenRequestIdstringrequired

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

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

curl -i -X GET \
  https://api.token.io/token-requests/rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq/result \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

One of:

Contains the details of the transfer response.

transferIdstring

The id of the transfer sent in the POST /transfers response and/or included in a respective GET /transfers response. This is populated for transfer token requests only, it is present if a transfer resource is created.

Example: "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"

tokenIdstring(tokenId)

Identifies a unique authorization token for a transfer, standing order or account information access.

Example: "tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1"

signatureobject(Signature)

Contains information about the signing party. This is only present if a tokenId is present. It can be used to validate that the provided tokenId corresponds to the token request (this is needed for the Hosted Pages flows only).

statusstring(TokenRequestResultStatus)required

The current result of the token request. This field is always populated.

PENDING - consent is not authorized by the user.
PROCESSED - consent was successfully authorized by the user.
REJECTED - consent has been rejected (the reason usually can be found in the statusReasonInformation field).
EXPIRED - the token request has expired and cannot be used anymore (consent can be in any state - authorized/not authorized yet/rejected - at this point).

Enum"PENDING""PROCESSED""REJECTED""EXPIRED"

Example: "PROCESSED"

statusReasonInformationstring(statusReasonInformation)

A human-readable description of the reason for the reported status, which may include a message from the bank, This value should not exceed 256 characters in length.

Example: "The token request is processing."

bankIdstring

The bank identifier, identical to the id in the repsonse to GET /banks.

Example: "ob-modelo"

Response

application/json

{
  "transferId": "t:2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
  "tokenId": "tt:8zK1dic95omjWb72gvc3z3ELKbTNfnGd89MbDnM73er4:ZhBVAJSH8DeU1",
  "signature": {
    "keyId": "CqSTHPvWY_dgVh-f",
    "memberId": "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq",
    "signature": "ODRWmM0xMRM7CKmK3bNl4e2Kb2btavTbZssCsrHsu8yopoKxBzouBrD9q5-E63tgdV1DpB7i31vwNDKywA0CAE"
  },
  "status": "PROCESSED",
  "statusReasonInformation": "The token request is processing.",
  "bankId": "ob-modelo"
}

Initiate bank authorization

Request

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

Security

Bearer or BasicAuth

Path

tokenRequestIdstringrequired

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

Example: rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq

Bodyapplication/jsonrequired

consentAcceptedboolean(boolean)

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

Default false

Example: false

credentialsobject(InitiateBankAuthorizationRequestCredentialsEntry)

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

useCredentialFlowboolean(boolean)

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.

Default false

Example: false

useWebappCredentialsFlowboolean(boolean)

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.

Default false

Example: false

curl -i -X POST \
  https://api.token.io/token-requests/rq:ej5ACWNwi1EcqBeuDPc4Z8C4Bgc:5zKtXEAq/authorization \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "consentAccepted": false,
    "credentials": {
      "property1": "string",
      "property2": "string"
    },
    "useCredentialFlow": false,
    "useWebappCredentialsFlow": false
  }'

Responses

Successful response

Bodyapplication/json

One of:

fieldsobject(CredentialFields)

oauthStatestring

The authorization state parameter generated within Token.io in the response. It is an optional field.

Example: "71b624cf-af3a-4f78-9420-d6e4248a9efe"

Response

application/json

{
  "fields": {
    "fields": [ … ]
  },
  "oauthState": "71b624cf-af3a-4f78-9420-d6e4248a9efe"
}

Transfers - for Payments v1

These endpoints relate to transfers, which are requests to move money between accounts.

Operations

Variable Recurring Payments

These endpoints enable you to initiate Variable Recurring Payments (VRP).

Operations

Refunds

These endpoints allow you to handle registration, posting, and retrieval of refunds associated with original transaction account information.

Operations

Payouts

These endpoints allow you to make payouts.

Operations

Settlement Accounts

These endpoints provide authorized access to an authenticated user's settlement account information, enabling you to create settlement accounts, retrieve settlement account details, transactions and payouts, and manage settlement rules.

Operations

Accounts

These endpoints provide authorized access to an authenticated user's account information.

Operations

Tokens

These endpoints retrieve all tokens, a filtered list of tokens, or a specific token, as well as allowing you to cancel an existing token.

Operations

Banks v1

These endpoints filter and fetch the list of connected banks, get information on specific banks, and initiate authorization with user-selected banks using Payments v1.

Operations

Banks v2

This endpoint filters and fetches the list of connected banks, gets information on specific banks, and initiates authorization with user-selected banks using Payments v2.

Operations

Sub-TPPs

These endpoints are for resellers using Token.io's licence to create, retrieve and delete sub-TPPs.

Operations

Authentication keys

These endpoints are for managing the public keys that are used for JWT authentication.

Operations

Reports

These endpoints retrieve the current AIS and PIS status of connected banks.

Operations

Webhooks

These endpoints configure, retrieve and remove webhooks. See Webhooks for more details.

Operations

Token.io's Open Banking API for TPPs

Payments v2