Verify if funds are available or not

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

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

Create a VRP consent

Request

The POST /vrp-consents endpoint creates a new VRP consent.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

initiationobject(VrpConsentInitiation)required

The initiation payload for the VRP consent.

initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

initiation.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"

initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

initiation.startDateTimestring

The date and time from which payments can be made (in ISO 8601 format). Payments initiated before this time will be rejected. If not provided, the time of consent creation is used as a default. The date and time cannot be earlier than the current time.

Example: "2017-04-05T10:43:07.123+01:00"

initiation.endDateTimestring

The date and time before which payments can be made (in ISO 8601 format). Payments initiated after this time will be rejected.

Example: "2017-04-05T10:43:07.132+01:00"

initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

initiation.vrpTypestringrequired

The types of payments that can be made under this VRP consent.

Enum"SWEEPING""OTHER"

Example: "SWEEPING"

initiation.localInstrumentstringrequired

The bank's payment service used for making a payment. Presently only Faster Payments are supported.

Value"FASTER_PAYMENTS"

Example: "FASTER_PAYMENTS"

initiation.debtorFasterPaymentsAccount (object)(VRPDebtorInformation)

FasterPaymentsAccount (object)(VRPDebtorInformation)

initiation.creditorFasterPaymentsAccount (object)(VRPCreditorInformation)required

FasterPaymentsAccount (object)(VRPCreditorInformation)

initiation.currencystringrequired

The ISO 4217 three letter currency code for this VRP consent. All amounts specified in this consent are in this currency. All payments created under this consent should use this currency.

Example: "EUR"

initiation.minimumIndividualAmountstring

The minimum amount for individual payments made under this consent, with up to four digits after the decimal point It should not exceed the maximumIndividualAmount or any of the periodic limits maximumAmount.

Example: "5.0"

initiation.maximumIndividualAmountstringrequired

The maximum amount for individual payments made under this consent, with up to four digits after the decimal point.

Example: "10000.0"

initiation.periodicLimitsArray of objects(PeriodicLimit)required

A list of periodic limits that are applied together as an intersection. At least one should be specified.

initiation.periodicLimits[].maximumAmountstringrequired

The transaction amount with up to four digits after the decimal point.

Example: "100.00"

initiation.periodicLimits[].periodTypestringrequired

Enum"DAY""WEEK""MONTH""YEAR"

Example: "DAY"

initiation.periodicLimits[].periodAlignmentstring

This field specifies whether the period starts on the consent start date or lines up with a calendar. If not specified, the CONSENT alignment is used.
The consent start date is defined by the startDateTime field of the consent (the time element is disregarded) or the date when consent is created if the startDateTime is not specified.

Enum"CONSENT""CALENDAR"

Example: "CALENDAR"

initiation.maximumOccurrencesinteger

The total number of payments that can be initiated under this consent. Any new payments will be rejected if the number is over this limit. This cannot be negative, 0 value is considered as not set.

Example: 3

initiation.callbackUrlstring(callbackUrl)required

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.

Example: "https://tpp.com/callback"

initiation.callbackStatestring(callbackStatev2)required

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

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

initiation.returnRefundAccountboolean

This field indicates whether the RefundAccount object should be included in the VRP created under this consent.

Default false

Example: true

initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

pispConsentAcceptedboolean(pispConsentAccepted)

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

Default false

Example: false

curl -i -X POST \
  https://api.token.io/vrp-consents \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "bankId": "ob-modelo",
      "refId": "9htio4a1sp2akdr1aa",
      "remittanceInformationPrimary": "Sweepco",
      "remittanceInformationSecondary": "Secondary remittance information.",
      "startDateTime": "2017-04-05T10:43:07.123+01:00",
      "endDateTime": "2017-04-05T10:43:07.132+01:00",
      "onBehalfOfId": "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s",
      "vrpType": "SWEEPING",
      "localInstrument": "FASTER_PAYMENTS",
      "debtor": {
        "accountNumber": "12345678",
        "sortCode": "123456",
        "name": "John Smith",
        "ultimateDebtorName": "John Smith",
        "address": {
          "addressLine": [
            "The Coach House"
          ],
          "streetName": "221B",
          "buildingNumber": "2C",
          "postCode": "TR26 1EZ",
          "townName": "Saint Ives",
          "state": "Cornwall",
          "district": "string",
          "country": "GB"
        }
      },
      "creditor": {
        "accountNumber": "12345678",
        "sortCode": "123456",
        "name": "Customer Inc.",
        "ultimateCreditorName": "Customer Inc.",
        "address": {
          "addressLine": [
            "The Coach House"
          ],
          "streetName": "221B",
          "buildingNumber": "2C",
          "postCode": "TR26 1EZ",
          "townName": "Saint Ives",
          "state": "Cornwall",
          "district": "string",
          "country": "GB"
        },
        "bankName": "string"
      },
      "currency": "EUR",
      "minimumIndividualAmount": "5.0",
      "maximumIndividualAmount": "10000.0",
      "periodicLimits": [
        {
          "maximumAmount": "100.00",
          "periodType": "DAY",
          "periodAlignment": "CALENDAR"
        }
      ],
      "maximumOccurrences": 3,
      "callbackUrl": "https://tpp.com/callback",
      "callbackState": "6242e45e-3063-4c42-8376",
      "returnRefundAccount": true,
      "risk": {
        "psuId": "0000789123",
        "paymentContextCode": "PISP_PAYEE",
        "paymentPurposeCode": "DVPM",
        "merchantCategoryCode": "4812",
        "beneficiaryAccountType": "BUSINESS",
        "contractPresentIndicator": true,
        "beneficiaryPrepopulatedIndicator": true,
        "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"
        }
      }
    },
    "pispConsentAccepted": false
  }'

Responses

Successful response

Bodyapplication/json

vrpConsentobject(VrpConsent)required

The VRP consent object.

vrpConsent.idstringrequired

The Token.io generated VRP consent id.

Example: "vc:12345abcd:abcde"

vrpConsent.memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrpConsent.initiationobject(VrpConsentInitiation)required

The initiation payload for the VRP consent.

vrpConsent.initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

vrpConsent.initiation.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"

vrpConsent.initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrpConsent.initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrpConsent.initiation.startDateTimestring

The date and time from which payments can be made (in ISO 8601 format). Payments initiated before this time will be rejected. If not provided, the time of consent creation is used as a default. The date and time cannot be earlier than the current time.

Example: "2017-04-05T10:43:07.123+01:00"

vrpConsent.initiation.endDateTimestring

The date and time before which payments can be made (in ISO 8601 format). Payments initiated after this time will be rejected.

Example: "2017-04-05T10:43:07.132+01:00"

vrpConsent.initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

vrpConsent.initiation.vrpTypestringrequired

The types of payments that can be made under this VRP consent.

Enum"SWEEPING""OTHER"

Example: "SWEEPING"

vrpConsent.initiation.localInstrumentstringrequired

The bank's payment service used for making a payment. Presently only Faster Payments are supported.

Value"FASTER_PAYMENTS"

Example: "FASTER_PAYMENTS"

vrpConsent.initiation.debtorFasterPaymentsAccount (object)(VRPDebtorInformation)

FasterPaymentsAccount (object)(VRPDebtorInformation)

vrpConsent.initiation.creditorFasterPaymentsAccount (object)(VRPCreditorInformation)required

FasterPaymentsAccount (object)(VRPCreditorInformation)

vrpConsent.initiation.currencystringrequired

The ISO 4217 three letter currency code for this VRP consent. All amounts specified in this consent are in this currency. All payments created under this consent should use this currency.

Example: "EUR"

vrpConsent.initiation.minimumIndividualAmountstring

The minimum amount for individual payments made under this consent, with up to four digits after the decimal point It should not exceed the maximumIndividualAmount or any of the periodic limits maximumAmount.

Example: "5.0"

vrpConsent.initiation.maximumIndividualAmountstringrequired

The maximum amount for individual payments made under this consent, with up to four digits after the decimal point.

Example: "10000.0"

vrpConsent.initiation.periodicLimitsArray of objects(PeriodicLimit)required

A list of periodic limits that are applied together as an intersection. At least one should be specified.

vrpConsent.initiation.periodicLimits[].maximumAmountstringrequired

The transaction amount with up to four digits after the decimal point.

Example: "100.00"

vrpConsent.initiation.periodicLimits[].periodTypestringrequired

Enum"DAY""WEEK""MONTH""YEAR"

Example: "DAY"

vrpConsent.initiation.periodicLimits[].periodAlignmentstring

This field specifies whether the period starts on the consent start date or lines up with a calendar. If not specified, the CONSENT alignment is used.
The consent start date is defined by the startDateTime field of the consent (the time element is disregarded) or the date when consent is created if the startDateTime is not specified.

Enum"CONSENT""CALENDAR"

Example: "CALENDAR"

vrpConsent.initiation.maximumOccurrencesinteger

The total number of payments that can be initiated under this consent. Any new payments will be rejected if the number is over this limit. This cannot be negative, 0 value is considered as not set.

Example: 3

vrpConsent.initiation.callbackUrlstring(callbackUrl)required

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.

Example: "https://tpp.com/callback"

vrpConsent.initiation.callbackStatestring(callbackStatev2)required

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

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

vrpConsent.initiation.returnRefundAccountboolean

This field indicates whether the RefundAccount object should be included in the VRP created under this consent.

Default false

Example: true

vrpConsent.initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrpConsent.createdDateTimestringrequired

The time this VRP consent object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrpConsent.updatedDateTimestringrequired

The last time this VRP consent object was updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrpConsent.statusstring(VrpConsentStatus)required

The Token.io VRP consent status.

PENDING - Token.io has received the request to create a VRP consent and the request has passed Token.io's validation.
PENDING_MORE_INFO - The initiaion lacks mandatory fields (e.g., bankId) that must be collected before connecting to the bank.
PENDING_REDIRECT_AUTH - The consent request has been acknowledged by the bank and Token.io is awaiting user confirmation at the bank's page.
PENDING_REDIRECT_AUTH_VERIFICATION - Token.io has received the callback information from the bank and is currently verifying it with the bank.
AUTHORIZED - the VRP consent has been successfully authorized.
REJECTED - The VRP consent has been rejected. More details are shared in the corresponding statusReasonInformation field.
REVOKED - The VRP consent has been revoked by the user.
FAILED - Token.io failed to proceed with the consent as a result of problems with the bank, or because the user has abandoned the request. All PENDING statuses convert to FAILED 30 minutes after consent creation.

Default "PENDING"

Enum"PENDING""PENDING_MORE_INFO""PENDING_REDIRECT_AUTH""PENDING_REDIRECT_AUTH_VERIFICATION""AUTHORIZED""REJECTED""REVOKED""FAILED"

Example: "AUTHORIZED"

vrpConsent.bankVrpConsentIdstring

The VRP consent id from the bank. This field can be empty if the consent id isn't available on the bank side.

Example: "4jq34dwjgi9MCK2MXB9f7v"

vrpConsent.bankVrpConsentStatusstring

The raw bank status. This field can be empty if the consent status isn't available on the bank side.

Example: "AwaitingAuthorization"

vrpConsent.statusReasonInformationstring

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 consent resource is awaiting user authorization."

vrpConsent.authenticationobject(Authentication)

The authentication operation required to proceed with consent creation. This is present when the consent initiation request has been created at the bank, but the consent hasn't been authorized or rejected yet.

Response

application/json

{
  "vrpConsent": {
    "id": "vc:12345abcd:abcde",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "createdDateTime": "2017-04-05T10:43:07.123Z",
    "updatedDateTime": "2017-04-05T10:45:07.123Z",
    "status": "AUTHORIZED",
    "bankVrpConsentId": "4jq34dwjgi9MCK2MXB9f7v",
    "bankVrpConsentStatus": "AwaitingAuthorization",
    "statusReasonInformation": "The consent resource is awaiting user authorization.",
    "authentication": { … }
  }
}

Get VRP consents

Request

The GET /vrp-consents endpoint retrieves all VRP consents created by the calling member.

Security

Bearer or BasicAuth

Query

limitinteger(int32)[ 1 .. 200 ]required

The maximum number of records to return.

Example: limit=10

offsetstring

The offset from the previous page.

Example: offset=LerV6Jmex

curl -i -X GET \
  'https://api.token.io/vrp-consents?limit=10&offset=LerV6Jmex' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpConsentsArray of objects(VrpConsent)required

vrpConsents[].idstringrequired

The Token.io generated VRP consent id.

Example: "vc:12345abcd:abcde"

vrpConsents[].memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrpConsents[].initiationobject(VrpConsentInitiation)required

The initiation payload for the VRP consent.

vrpConsents[].initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

vrpConsents[].initiation.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"

vrpConsents[].initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrpConsents[].initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrpConsents[].initiation.startDateTimestring

The date and time from which payments can be made (in ISO 8601 format). Payments initiated before this time will be rejected. If not provided, the time of consent creation is used as a default. The date and time cannot be earlier than the current time.

Example: "2017-04-05T10:43:07.123+01:00"

vrpConsents[].initiation.endDateTimestring

The date and time before which payments can be made (in ISO 8601 format). Payments initiated after this time will be rejected.

Example: "2017-04-05T10:43:07.132+01:00"

vrpConsents[].initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

vrpConsents[].initiation.vrpTypestringrequired

The types of payments that can be made under this VRP consent.

Enum"SWEEPING""OTHER"

Example: "SWEEPING"

vrpConsents[].initiation.localInstrumentstringrequired

The bank's payment service used for making a payment. Presently only Faster Payments are supported.

Value"FASTER_PAYMENTS"

Example: "FASTER_PAYMENTS"

vrpConsents[].initiation.debtorFasterPaymentsAccount (object)(VRPDebtorInformation)

FasterPaymentsAccount (object)(VRPDebtorInformation)

vrpConsents[].initiation.creditorFasterPaymentsAccount (object)(VRPCreditorInformation)required

FasterPaymentsAccount (object)(VRPCreditorInformation)

vrpConsents[].initiation.currencystringrequired

The ISO 4217 three letter currency code for this VRP consent. All amounts specified in this consent are in this currency. All payments created under this consent should use this currency.

Example: "EUR"

vrpConsents[].initiation.minimumIndividualAmountstring

The minimum amount for individual payments made under this consent, with up to four digits after the decimal point It should not exceed the maximumIndividualAmount or any of the periodic limits maximumAmount.

Example: "5.0"

vrpConsents[].initiation.maximumIndividualAmountstringrequired

The maximum amount for individual payments made under this consent, with up to four digits after the decimal point.

Example: "10000.0"

vrpConsents[].initiation.periodicLimitsArray of objects(PeriodicLimit)required

A list of periodic limits that are applied together as an intersection. At least one should be specified.

vrpConsents[].initiation.periodicLimits[].maximumAmountstringrequired

The transaction amount with up to four digits after the decimal point.

Example: "100.00"

vrpConsents[].initiation.periodicLimits[].periodTypestringrequired

Enum"DAY""WEEK""MONTH""YEAR"

Example: "DAY"

vrpConsents[].initiation.periodicLimits[].periodAlignmentstring

This field specifies whether the period starts on the consent start date or lines up with a calendar. If not specified, the CONSENT alignment is used.
The consent start date is defined by the startDateTime field of the consent (the time element is disregarded) or the date when consent is created if the startDateTime is not specified.

Enum"CONSENT""CALENDAR"

Example: "CALENDAR"

vrpConsents[].initiation.maximumOccurrencesinteger

The total number of payments that can be initiated under this consent. Any new payments will be rejected if the number is over this limit. This cannot be negative, 0 value is considered as not set.

Example: 3

vrpConsents[].initiation.callbackUrlstring(callbackUrl)required

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.

Example: "https://tpp.com/callback"

vrpConsents[].initiation.callbackStatestring(callbackStatev2)required

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

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

vrpConsents[].initiation.returnRefundAccountboolean

This field indicates whether the RefundAccount object should be included in the VRP created under this consent.

Default false

Example: true

vrpConsents[].initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrpConsents[].createdDateTimestringrequired

The time this VRP consent object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrpConsents[].updatedDateTimestringrequired

The last time this VRP consent object was updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrpConsents[].statusstring(VrpConsentStatus)required

The Token.io VRP consent status.

PENDING - Token.io has received the request to create a VRP consent and the request has passed Token.io's validation.
PENDING_MORE_INFO - The initiaion lacks mandatory fields (e.g., bankId) that must be collected before connecting to the bank.
PENDING_REDIRECT_AUTH - The consent request has been acknowledged by the bank and Token.io is awaiting user confirmation at the bank's page.
PENDING_REDIRECT_AUTH_VERIFICATION - Token.io has received the callback information from the bank and is currently verifying it with the bank.
AUTHORIZED - the VRP consent has been successfully authorized.
REJECTED - The VRP consent has been rejected. More details are shared in the corresponding statusReasonInformation field.
REVOKED - The VRP consent has been revoked by the user.
FAILED - Token.io failed to proceed with the consent as a result of problems with the bank, or because the user has abandoned the request. All PENDING statuses convert to FAILED 30 minutes after consent creation.

Default "PENDING"

Enum"PENDING""PENDING_MORE_INFO""PENDING_REDIRECT_AUTH""PENDING_REDIRECT_AUTH_VERIFICATION""AUTHORIZED""REJECTED""REVOKED""FAILED"

Example: "AUTHORIZED"

vrpConsents[].bankVrpConsentIdstring

The VRP consent id from the bank. This field can be empty if the consent id isn't available on the bank side.

Example: "4jq34dwjgi9MCK2MXB9f7v"

vrpConsents[].bankVrpConsentStatusstring

The raw bank status. This field can be empty if the consent status isn't available on the bank side.

Example: "AwaitingAuthorization"

vrpConsents[].statusReasonInformationstring

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 consent resource is awaiting user authorization."

vrpConsents[].authenticationobject(Authentication)

The authentication operation required to proceed with consent creation. This is present when the consent initiation request has been created at the bank, but the consent hasn't been authorized or rejected yet.

pageInfoobject(PageInfo)required

The information about the current page, which also indicates whether the next page exists.

pageInfo.limitinteger(int32)[ 1 .. 200 ]required

The limit (maximum number of objects to return) applied to this page.
The default and maximum allowed limit is 200. If this limit is exceeded, was not set or was set to 0, it will be set to 200.

Default 200

Example: 20

pageInfo.offsetstring

The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset is provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to the dynamic nature of the data.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "LerV6Jmex"

pageInfo.nextOffsetstring

The offset for the next page. If the page is empty, it is equal to this page offset. If the page is not empty, but there are no more objects to load (haveMore = false), it will be empty.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "KgwG8Qkat"

pageInfo.haveMoreboolean

This field indicates whether there are more objects to load, i.e. whether the next page exists.

Default false

Example: false

Response

application/json

{
  "vrpConsents": [
    { … }
  ],
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  }
}

Get a VRP consent

Request

The GET /vrp-consents/{id} endpoint retrieves the details for an individual VRP consent.

Security

Bearer or BasicAuth

Path

idstringrequired

VRP consent id

Example: vc:12345abcd:abcde

curl -i -X GET \
  https://api.token.io/vrp-consents/vc:12345abcd:abcde \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpConsentobject(VrpConsent)required

The VRP consent object.

vrpConsent.idstringrequired

The Token.io generated VRP consent id.

Example: "vc:12345abcd:abcde"

vrpConsent.memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrpConsent.initiationobject(VrpConsentInitiation)required

The initiation payload for the VRP consent.

vrpConsent.initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

vrpConsent.initiation.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"

vrpConsent.initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrpConsent.initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrpConsent.initiation.startDateTimestring

The date and time from which payments can be made (in ISO 8601 format). Payments initiated before this time will be rejected. If not provided, the time of consent creation is used as a default. The date and time cannot be earlier than the current time.

Example: "2017-04-05T10:43:07.123+01:00"

vrpConsent.initiation.endDateTimestring

The date and time before which payments can be made (in ISO 8601 format). Payments initiated after this time will be rejected.

Example: "2017-04-05T10:43:07.132+01:00"

vrpConsent.initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

vrpConsent.initiation.vrpTypestringrequired

The types of payments that can be made under this VRP consent.

Enum"SWEEPING""OTHER"

Example: "SWEEPING"

vrpConsent.initiation.localInstrumentstringrequired

The bank's payment service used for making a payment. Presently only Faster Payments are supported.

Value"FASTER_PAYMENTS"

Example: "FASTER_PAYMENTS"

vrpConsent.initiation.debtorFasterPaymentsAccount (object)(VRPDebtorInformation)

FasterPaymentsAccount (object)(VRPDebtorInformation)

vrpConsent.initiation.creditorFasterPaymentsAccount (object)(VRPCreditorInformation)required

FasterPaymentsAccount (object)(VRPCreditorInformation)

vrpConsent.initiation.currencystringrequired

The ISO 4217 three letter currency code for this VRP consent. All amounts specified in this consent are in this currency. All payments created under this consent should use this currency.

Example: "EUR"

vrpConsent.initiation.minimumIndividualAmountstring

The minimum amount for individual payments made under this consent, with up to four digits after the decimal point It should not exceed the maximumIndividualAmount or any of the periodic limits maximumAmount.

Example: "5.0"

vrpConsent.initiation.maximumIndividualAmountstringrequired

The maximum amount for individual payments made under this consent, with up to four digits after the decimal point.

Example: "10000.0"

vrpConsent.initiation.periodicLimitsArray of objects(PeriodicLimit)required

A list of periodic limits that are applied together as an intersection. At least one should be specified.

vrpConsent.initiation.periodicLimits[].maximumAmountstringrequired

The transaction amount with up to four digits after the decimal point.

Example: "100.00"

vrpConsent.initiation.periodicLimits[].periodTypestringrequired

Enum"DAY""WEEK""MONTH""YEAR"

Example: "DAY"

vrpConsent.initiation.periodicLimits[].periodAlignmentstring

This field specifies whether the period starts on the consent start date or lines up with a calendar. If not specified, the CONSENT alignment is used.
The consent start date is defined by the startDateTime field of the consent (the time element is disregarded) or the date when consent is created if the startDateTime is not specified.

Enum"CONSENT""CALENDAR"

Example: "CALENDAR"

vrpConsent.initiation.maximumOccurrencesinteger

The total number of payments that can be initiated under this consent. Any new payments will be rejected if the number is over this limit. This cannot be negative, 0 value is considered as not set.

Example: 3

vrpConsent.initiation.callbackUrlstring(callbackUrl)required

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.

Example: "https://tpp.com/callback"

vrpConsent.initiation.callbackStatestring(callbackStatev2)required

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

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

vrpConsent.initiation.returnRefundAccountboolean

This field indicates whether the RefundAccount object should be included in the VRP created under this consent.

Default false

Example: true

vrpConsent.initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrpConsent.createdDateTimestringrequired

The time this VRP consent object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrpConsent.updatedDateTimestringrequired

The last time this VRP consent object was updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrpConsent.statusstring(VrpConsentStatus)required

The Token.io VRP consent status.

PENDING - Token.io has received the request to create a VRP consent and the request has passed Token.io's validation.
PENDING_MORE_INFO - The initiaion lacks mandatory fields (e.g., bankId) that must be collected before connecting to the bank.
PENDING_REDIRECT_AUTH - The consent request has been acknowledged by the bank and Token.io is awaiting user confirmation at the bank's page.
PENDING_REDIRECT_AUTH_VERIFICATION - Token.io has received the callback information from the bank and is currently verifying it with the bank.
AUTHORIZED - the VRP consent has been successfully authorized.
REJECTED - The VRP consent has been rejected. More details are shared in the corresponding statusReasonInformation field.
REVOKED - The VRP consent has been revoked by the user.
FAILED - Token.io failed to proceed with the consent as a result of problems with the bank, or because the user has abandoned the request. All PENDING statuses convert to FAILED 30 minutes after consent creation.

Default "PENDING"

Enum"PENDING""PENDING_MORE_INFO""PENDING_REDIRECT_AUTH""PENDING_REDIRECT_AUTH_VERIFICATION""AUTHORIZED""REJECTED""REVOKED""FAILED"

Example: "AUTHORIZED"

vrpConsent.bankVrpConsentIdstring

The VRP consent id from the bank. This field can be empty if the consent id isn't available on the bank side.

Example: "4jq34dwjgi9MCK2MXB9f7v"

vrpConsent.bankVrpConsentStatusstring

The raw bank status. This field can be empty if the consent status isn't available on the bank side.

Example: "AwaitingAuthorization"

vrpConsent.statusReasonInformationstring

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 consent resource is awaiting user authorization."

vrpConsent.authenticationobject(Authentication)

The authentication operation required to proceed with consent creation. This is present when the consent initiation request has been created at the bank, but the consent hasn't been authorized or rejected yet.

Response

application/json

{
  "vrpConsent": {
    "id": "vc:12345abcd:abcde",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "createdDateTime": "2017-04-05T10:43:07.123Z",
    "updatedDateTime": "2017-04-05T10:45:07.123Z",
    "status": "AUTHORIZED",
    "bankVrpConsentId": "4jq34dwjgi9MCK2MXB9f7v",
    "bankVrpConsentStatus": "AwaitingAuthorization",
    "statusReasonInformation": "The consent resource is awaiting user authorization.",
    "authentication": { … }
  }
}

Revoke a VRP consent

Request

The DELETE /vrp-consents/{id} endpoint revokes an individual VRP consent.

Security

Bearer or BasicAuth

Path

idstringrequired

VRP consent id

Example: vc:12345abcd:abcde

curl -i -X DELETE \
  https://api.token.io/vrp-consents/vc:12345abcd:abcde \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpConsentobject(VrpConsent)required

The VRP consent object.

vrpConsent.idstringrequired

The Token.io generated VRP consent id.

Example: "vc:12345abcd:abcde"

vrpConsent.memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrpConsent.initiationobject(VrpConsentInitiation)required

The initiation payload for the VRP consent.

vrpConsent.initiation.bankIdstring(bankId)

The Token.io id of the bank where the consent is created. This field is required if the customer is not using Token.io's Hosted Pages for bank selection, i.e., API-only integration when EMBEDDED_HOSTED_PAGES is selected in flowType, or Hosted Pages embedded (modal) integration.

Example: "ob-modelo"

vrpConsent.initiation.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"

vrpConsent.initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrpConsent.initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrpConsent.initiation.startDateTimestring

The date and time from which payments can be made (in ISO 8601 format). Payments initiated before this time will be rejected. If not provided, the time of consent creation is used as a default. The date and time cannot be earlier than the current time.

Example: "2017-04-05T10:43:07.123+01:00"

vrpConsent.initiation.endDateTimestring

The date and time before which payments can be made (in ISO 8601 format). Payments initiated after this time will be rejected.

Example: "2017-04-05T10:43:07.132+01:00"

vrpConsent.initiation.onBehalfOfIdstring

The id of the ultimate client on whose behalf the consent is created. If the consent is created on behalf of a sub-TPP, this field should contain the sub-TPP referenceId. This field is mandatory for unregulated TPPs.

Example: "6f34h397-b29h-23b0-s30g-hkd0d2dk4k1s"

vrpConsent.initiation.vrpTypestringrequired

The types of payments that can be made under this VRP consent.

Enum"SWEEPING""OTHER"

Example: "SWEEPING"

vrpConsent.initiation.localInstrumentstringrequired

The bank's payment service used for making a payment. Presently only Faster Payments are supported.

Value"FASTER_PAYMENTS"

Example: "FASTER_PAYMENTS"

vrpConsent.initiation.debtorFasterPaymentsAccount (object)(VRPDebtorInformation)

FasterPaymentsAccount (object)(VRPDebtorInformation)

vrpConsent.initiation.creditorFasterPaymentsAccount (object)(VRPCreditorInformation)required

FasterPaymentsAccount (object)(VRPCreditorInformation)

vrpConsent.initiation.currencystringrequired

The ISO 4217 three letter currency code for this VRP consent. All amounts specified in this consent are in this currency. All payments created under this consent should use this currency.

Example: "EUR"

vrpConsent.initiation.minimumIndividualAmountstring

The minimum amount for individual payments made under this consent, with up to four digits after the decimal point It should not exceed the maximumIndividualAmount or any of the periodic limits maximumAmount.

Example: "5.0"

vrpConsent.initiation.maximumIndividualAmountstringrequired

The maximum amount for individual payments made under this consent, with up to four digits after the decimal point.

Example: "10000.0"

vrpConsent.initiation.periodicLimitsArray of objects(PeriodicLimit)required

A list of periodic limits that are applied together as an intersection. At least one should be specified.

vrpConsent.initiation.periodicLimits[].maximumAmountstringrequired

The transaction amount with up to four digits after the decimal point.

Example: "100.00"

vrpConsent.initiation.periodicLimits[].periodTypestringrequired

Enum"DAY""WEEK""MONTH""YEAR"

Example: "DAY"

vrpConsent.initiation.periodicLimits[].periodAlignmentstring

This field specifies whether the period starts on the consent start date or lines up with a calendar. If not specified, the CONSENT alignment is used.
The consent start date is defined by the startDateTime field of the consent (the time element is disregarded) or the date when consent is created if the startDateTime is not specified.

Enum"CONSENT""CALENDAR"

Example: "CALENDAR"

vrpConsent.initiation.maximumOccurrencesinteger

The total number of payments that can be initiated under this consent. Any new payments will be rejected if the number is over this limit. This cannot be negative, 0 value is considered as not set.

Example: 3

vrpConsent.initiation.callbackUrlstring(callbackUrl)required

The TPP's url that Token.io calls back to. This url should not be under the token.io domain and must be https/SSL secure.

Example: "https://tpp.com/callback"

vrpConsent.initiation.callbackStatestring(callbackStatev2)required

The uniquely-generated string included as part of the URL when communicating with the bank. It is sent to the bank during payment initiation and is also returned in the callback from the bank. You can use it to identify which payment the callback refers to, ensuring that the callback can be reliably matched to the original payment request.

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

vrpConsent.initiation.returnRefundAccountboolean

This field indicates whether the RefundAccount object should be included in the VRP created under this consent.

Default false

Example: true

vrpConsent.initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrpConsent.createdDateTimestringrequired

The time this VRP consent object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrpConsent.updatedDateTimestringrequired

The last time this VRP consent object was updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrpConsent.statusstring(VrpConsentStatus)required

The Token.io VRP consent status.

PENDING - Token.io has received the request to create a VRP consent and the request has passed Token.io's validation.
PENDING_MORE_INFO - The initiaion lacks mandatory fields (e.g., bankId) that must be collected before connecting to the bank.
PENDING_REDIRECT_AUTH - The consent request has been acknowledged by the bank and Token.io is awaiting user confirmation at the bank's page.
PENDING_REDIRECT_AUTH_VERIFICATION - Token.io has received the callback information from the bank and is currently verifying it with the bank.
AUTHORIZED - the VRP consent has been successfully authorized.
REJECTED - The VRP consent has been rejected. More details are shared in the corresponding statusReasonInformation field.
REVOKED - The VRP consent has been revoked by the user.
FAILED - Token.io failed to proceed with the consent as a result of problems with the bank, or because the user has abandoned the request. All PENDING statuses convert to FAILED 30 minutes after consent creation.

Default "PENDING"

Enum"PENDING""PENDING_MORE_INFO""PENDING_REDIRECT_AUTH""PENDING_REDIRECT_AUTH_VERIFICATION""AUTHORIZED""REJECTED""REVOKED""FAILED"

Example: "AUTHORIZED"

vrpConsent.bankVrpConsentIdstring

The VRP consent id from the bank. This field can be empty if the consent id isn't available on the bank side.

Example: "4jq34dwjgi9MCK2MXB9f7v"

vrpConsent.bankVrpConsentStatusstring

The raw bank status. This field can be empty if the consent status isn't available on the bank side.

Example: "AwaitingAuthorization"

vrpConsent.statusReasonInformationstring

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 consent resource is awaiting user authorization."

vrpConsent.authenticationobject(Authentication)

The authentication operation required to proceed with consent creation. This is present when the consent initiation request has been created at the bank, but the consent hasn't been authorized or rejected yet.

Response

application/json

{
  "vrpConsent": {
    "id": "vc:12345abcd:abcde",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "createdDateTime": "2017-04-05T10:43:07.123Z",
    "updatedDateTime": "2017-04-05T10:45:07.123Z",
    "status": "AUTHORIZED",
    "bankVrpConsentId": "4jq34dwjgi9MCK2MXB9f7v",
    "bankVrpConsentStatus": "AwaitingAuthorization",
    "statusReasonInformation": "The consent resource is awaiting user authorization.",
    "authentication": { … }
  }
}

Get payments under a VRP consent

Request

The GET /vrp-consents/{id}/payments endpoint retrieves the payments under a given VRP consent.

Security

Bearer or BasicAuth

Path

idstringrequired

VRP consent id

Example: vc:12345abcd:abcde

Query

limitinteger(int32)[ 1 .. 200 ]required

The maximum number of records to return.

Example: limit=10

offsetstring

The offset from the previous page.

Example: offset=LerV6Jmex

curl -i -X GET \
  'https://api.token.io/vrp-consents/vc:12345abcd:abcde/payments?limit=10&offset=LerV6Jmex' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpsArray of objects(Vrp)required

vrps[].idstringrequired

The Token.io generated VRP id.

Example: "vrp:12345abcd:abcd"

vrps[].memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrps[].initiationobject(VrpInitiation)required

The VRP initiation object.

vrps[].initiation.consentIdstringrequired

The id of the VRP consent.

Example: "vc:12345abcd:abcd"

vrps[].initiation.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"

vrps[].initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrps[].initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrps[].initiation.amountobject(Amount)required

The transaction amount and currency.

vrps[].initiation.amount.valuestringrequired

The transaction amount with up to four digits after the decimal point.

Example: "10.23"

vrps[].initiation.amount.currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"

vrps[].initiation.confirmFundsboolean

A flag indicating whether the bank should do a funds confirmation check before accepting the payment. If set to true, the funds will be checked.

Default false

Example: false

vrps[].initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrps[].createdDateTimestringrequired

The time when this VRP object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrps[].updatedDateTimestringrequired

The date and time this VRP object was last updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrps[].statusstring(VrpStatus)required

The Token.io VRP status.

INITIATION_PENDING - Token.io has received the payment initiation request and it has passed Token.io's validation.
INITIATION_PROCESSING - The VRP request has been acknowledged by the bank and is now being processed.
INITIATION_COMPLETED - Payment initiation has been completed.

INITIATION_REJECTED

INITIATION_REJECTED_INSUFFICIENT_FUNDS - The payment has been rejected because the funds check returned a negative result.
INITIATION_FAILED - Token.io failed to proceed with the initiation as a result of problems reaching the bank.
INITIATION_NO_FINAL_STATUS_AVAILABLE - The payment status has not been updated for some time and Token.io has stopped polling it. The recommended maximum polling time is 30 days. The status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days if the bank does not update the status. This is a final status, but it does not indicate success or failure. Please contact the bank to check the actual status of the payment.

Default "INITIATION_PENDING"

Enum"INITIATION_PENDING""INITIATION_PROCESSING""INITIATION_COMPLETED""INITIATION_REJECTED""INITIATION_REJECTED_INSUFFICIENT_FUNDS""INITIATION_FAILED""INITIATION_NO_FINAL_STATUS_AVAILABLE"

Example: "INITIATION_COMPLETED"

vrps[].bankVrpIdstring

The VRP id from the bank. This field can be empty if the VRP id isn't available on the bank's side.

Example: "4vn6aDyMiwBYbPDN"

vrps[].bankVrpStatusstring

The raw bank status. This field can be empty if payment status isn't available on the bank's side.

Example: "AcceptedCreditSettlementCompleted"

vrps[].statusReasonInformationstring

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 payment is settled on the debtor's side."

vrps[].refundDetailsobject(RefundDetails)

The refund-related information for this payment. This field requires specific permission and is only available if paymentInitiation.returnRefundAccount is set to true.

pageInfoobject(PageInfo)required

The information about the current page, which also indicates whether the next page exists.

pageInfo.limitinteger(int32)[ 1 .. 200 ]required

The limit (maximum number of objects to return) applied to this page.
The default and maximum allowed limit is 200. If this limit is exceeded, was not set or was set to 0, it will be set to 200.

Default 200

Example: 20

pageInfo.offsetstring

The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset is provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to the dynamic nature of the data.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "LerV6Jmex"

pageInfo.nextOffsetstring

The offset for the next page. If the page is empty, it is equal to this page offset. If the page is not empty, but there are no more objects to load (haveMore = false), it will be empty.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "KgwG8Qkat"

pageInfo.haveMoreboolean

This field indicates whether there are more objects to load, i.e. whether the next page exists.

Default false

Example: false

Response

application/json

{
  "vrps": [
    { … }
  ],
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  }
}

Initiate a VRP payment

Request

The POST /vrps initiates a new VRP payment.

Security

Bearer or BasicAuth

Bodyapplication/jsonrequired

initiationobject(VrpInitiation)required

The VRP initiation object.

initiation.consentIdstringrequired

The id of the VRP consent.

Example: "vc:12345abcd:abcd"

initiation.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"

initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

initiation.amountobject(Amount)required

The transaction amount and currency.

initiation.amount.valuestringrequired

The transaction amount with up to four digits after the decimal point.

Example: "10.23"

initiation.amount.currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"

initiation.confirmFundsboolean

A flag indicating whether the bank should do a funds confirmation check before accepting the payment. If set to true, the funds will be checked.

Default false

Example: false

initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

curl -i -X POST \
  https://api.token.io/vrps \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "initiation": {
      "consentId": "vc:12345abcd:abcd",
      "refId": "9htio4a1sp2akdr1aa",
      "remittanceInformationPrimary": "Sweepco",
      "remittanceInformationSecondary": "Secondary remittance information.",
      "amount": {
        "value": "10.23",
        "currency": "EUR"
      },
      "confirmFunds": false,
      "risk": {
        "psuId": "0000789123",
        "paymentContextCode": "PISP_PAYEE",
        "paymentPurposeCode": "DVPM",
        "merchantCategoryCode": "4812",
        "beneficiaryAccountType": "BUSINESS",
        "contractPresentIndicator": true,
        "beneficiaryPrepopulatedIndicator": true,
        "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"
        }
      }
    }
  }'

Responses

Successful response

Bodyapplication/json

vrpobject(Vrp)

The VRP object.

Response

application/json

{
  "vrp": {
    "id": "vrp:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "createdDateTime": "2017-04-05T10:43:07.123Z",
    "updatedDateTime": "2017-04-05T10:45:07.123Z",
    "status": "INITIATION_COMPLETED",
    "bankVrpId": "4vn6aDyMiwBYbPDN",
    "bankVrpStatus": "AcceptedCreditSettlementCompleted",
    "statusReasonInformation": "The payment is settled on the debtor's side.",
    "refundDetails": { … }
  }
}

Get VRP payments

Request

The GET /vrps endpoint provides you with a list of vrp payments and their details.

Security

Bearer or BasicAuth

Query

limitinteger(int32)[ 1 .. 200 ]required

The maximum number of records to return.

Example: limit=10

offsetstring

The offset from the previous page.

Example: offset=LerV6Jmex

idsArray of strings

Filters vrp payments by their ids - returns only payments with ids listed in this parameter.

Example: ids=vrp:4QExXrhKTxfShBdcTeqFabqJJhUF:2gFUX1NDgpN&ids=vrp:N5cJDFsQzVca3Qvr8kQocgEnjgX:2gFUX1NEdYA

invertIdsboolean

Invert ids query - returns only vrp payments with ids not listed in the ids parameter.

statusesArray of strings(VrpStatus)

Filters vrp payments by their statuses - returns only payments with statuses listed in this parameter.

Items Enum"INITIATION_PENDING""INITIATION_PROCESSING""INITIATION_COMPLETED""INITIATION_REJECTED""INITIATION_REJECTED_INSUFFICIENT_FUNDS""INITIATION_FAILED""INITIATION_NO_FINAL_STATUS_AVAILABLE"

Example: statuses=INITIATION_COMPLETED&statuses=INITIATION_REJECTED

invertStatusesboolean

Invert statuses query - returns only vrp payments with statuses not listed in the statuses parameter.

Example: invertStatuses=true

createdAfterstring

Returns only vrp payments created after this time (in ISO 8601 format).

Example: createdAfter=2022-04-05T17:00:00.000Z

createdBeforestring

Returns only vrp payments created before this time (in ISO 8601 format).

Example: createdBefore=2022-04-05T17:00:00.000Z

refIdsArray of strings

Filters vrp payments by their refId values - returns only payments with refIds listed in this parameter.

Example: refIds=ShBdcTeqFabqJJhUF&refIds=N5cJDFsQzVca3Q

vrpConsentIdstring

Filters vrp payments by their VRP consent id value - returns only payments with vrpConsentId listed in this parameter.

Example: vrpConsentId=vc:12345abcd:abcde

curl -i -X GET \
  'https://api.token.io/vrps?limit=10&offset=LerV6Jmex&ids=vrp%3A4QExXrhKTxfShBdcTeqFabqJJhUF%3A2gFUX1NDgpN%2Cvrp%3AN5cJDFsQzVca3Qvr8kQocgEnjgX%3A2gFUX1NEdYA&invertIds=true&statuses=INITIATION_COMPLETED%2CINITIATION_REJECTED&invertStatuses=true&createdAfter=2022-04-05T17%3A00%3A00.000Z&createdBefore=2022-04-05T17%3A00%3A00.000Z&refIds=ShBdcTeqFabqJJhUF%2CN5cJDFsQzVca3Q&vrpConsentId=vc%3A12345abcd%3Aabcde' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpsArray of objects(Vrp)required

vrps[].idstringrequired

The Token.io generated VRP id.

Example: "vrp:12345abcd:abcd"

vrps[].memberIdstring(memberId)required

The Token.io-assigned member id of the TPP.

Example: "m:123456abcd:abcd"

vrps[].initiationobject(VrpInitiation)required

The VRP initiation object.

vrps[].initiation.consentIdstringrequired

The id of the VRP consent.

Example: "vc:12345abcd:abcd"

vrps[].initiation.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"

vrps[].initiation.remittanceInformationPrimarystring(remittanceInformationPrimary)required

The primary field for remittance information. This should contain a reference, as assigned by the creditor, to unambiguously refer to the payment transactions under this consent. The value of this field should appear on the bank statement and reconciliation file, irrespective of the payment network being used.
We recommend that the remittanceInformationPrimary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 35 characters in length.

Example: "Sweepco"

vrps[].initiation.remittanceInformationSecondarystring(remittanceInformationSecondary)

The secondary field for remittance information. The information supplied should enable the reconciliation of an entry in an unstructured form. Depending on the payment network, information from this field may or may not be included in the bank statement and reconciliation file.
We recommend that the remittanceInformationSecondary field should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-') as banks may remove these when sending this field to the beneficiary. This field should not exceed 140 characters in length.

Example: "Secondary remittance information."

vrps[].initiation.amountobject(Amount)required

The transaction amount and currency.

vrps[].initiation.amount.valuestringrequired

The transaction amount with up to four digits after the decimal point.

Example: "10.23"

vrps[].initiation.amount.currencystringrequired

The ISO 4217 three letter currency code.

Example: "EUR"

vrps[].initiation.confirmFundsboolean

A flag indicating whether the bank should do a funds confirmation check before accepting the payment. If set to true, the funds will be checked.

Default false

Example: false

vrps[].initiation.riskobject(Risk)

This field is used to specify additional details for the risk scoring of payments.

vrps[].createdDateTimestringrequired

The time when this VRP object was created (in ISO 8601 format).

Example: "2017-04-05T10:43:07.123Z"

vrps[].updatedDateTimestringrequired

The date and time this VRP object was last updated (in ISO 8601 format).

Example: "2017-04-05T10:45:07.123Z"

vrps[].statusstring(VrpStatus)required

The Token.io VRP status.

INITIATION_PENDING - Token.io has received the payment initiation request and it has passed Token.io's validation.
INITIATION_PROCESSING - The VRP request has been acknowledged by the bank and is now being processed.
INITIATION_COMPLETED - Payment initiation has been completed.

INITIATION_REJECTED

INITIATION_REJECTED_INSUFFICIENT_FUNDS - The payment has been rejected because the funds check returned a negative result.
INITIATION_FAILED - Token.io failed to proceed with the initiation as a result of problems reaching the bank.
INITIATION_NO_FINAL_STATUS_AVAILABLE - The payment status has not been updated for some time and Token.io has stopped polling it. The recommended maximum polling time is 30 days. The status will change to INITIATION_NO_FINAL_STATUS_AVAILABLE after 30 days if the bank does not update the status. This is a final status, but it does not indicate success or failure. Please contact the bank to check the actual status of the payment.

Default "INITIATION_PENDING"

Enum"INITIATION_PENDING""INITIATION_PROCESSING""INITIATION_COMPLETED""INITIATION_REJECTED""INITIATION_REJECTED_INSUFFICIENT_FUNDS""INITIATION_FAILED""INITIATION_NO_FINAL_STATUS_AVAILABLE"

Example: "INITIATION_COMPLETED"

vrps[].bankVrpIdstring

The VRP id from the bank. This field can be empty if the VRP id isn't available on the bank's side.

Example: "4vn6aDyMiwBYbPDN"

vrps[].bankVrpStatusstring

The raw bank status. This field can be empty if payment status isn't available on the bank's side.

Example: "AcceptedCreditSettlementCompleted"

vrps[].statusReasonInformationstring

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 payment is settled on the debtor's side."

vrps[].refundDetailsobject(RefundDetails)

The refund-related information for this payment. This field requires specific permission and is only available if paymentInitiation.returnRefundAccount is set to true.

pageInfoobject(PageInfo)required

The information about the current page, which also indicates whether the next page exists.

pageInfo.limitinteger(int32)[ 1 .. 200 ]required

The limit (maximum number of objects to return) applied to this page.
The default and maximum allowed limit is 200. If this limit is exceeded, was not set or was set to 0, it will be set to 200.

Default 200

Example: 20

pageInfo.offsetstring

The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset is provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to the dynamic nature of the data.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "LerV6Jmex"

pageInfo.nextOffsetstring

The offset for the next page. If the page is empty, it is equal to this page offset. If the page is not empty, but there are no more objects to load (haveMore = false), it will be empty.
The offset is opaque to a user and should not be parsed and/or understood in any way.

Example: "KgwG8Qkat"

pageInfo.haveMoreboolean

This field indicates whether there are more objects to load, i.e. whether the next page exists.

Default false

Example: false

Response

application/json

{
  "vrps": [
    { … }
  ],
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  }
}

Get a VRP payment

Request

The GET /vrps/{id} endpoint retrieves the details for an individual VRP payment.

Security

Bearer or BasicAuth

Path

idstringrequired

VRP id

Example: vrp:12345abcd:abcde

curl -i -X GET \
  https://api.token.io/vrps/vrp:12345abcd:abcde \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

vrpobject(Vrp)

The VRP object.

Response

application/json

{
  "vrp": {
    "id": "vrp:12345abcd:abcd",
    "memberId": "m:123456abcd:abcd",
    "initiation": { … },
    "createdDateTime": "2017-04-05T10:43:07.123Z",
    "updatedDateTime": "2017-04-05T10:45:07.123Z",
    "status": "INITIATION_COMPLETED",
    "bankVrpId": "4vn6aDyMiwBYbPDN",
    "bankVrpStatus": "AcceptedCreditSettlementCompleted",
    "statusReasonInformation": "The payment is settled on the debtor's side.",
    "refundDetails": { … }
  }
}

Verify if funds are available or not

Request

The GET /vrps/{id}/confirm-funds endpoint confirms whether the funds are available to initiate VRP.

Security

Bearer or BasicAuth

Path

idstringrequired

The VRP consent id.

Example: vc:12345abcd:abcde

Query

amountstringrequired

The amount to confirm availability for.

Example: amount=1

curl -i -X GET \
  'https://api.token.io/vrps/vc:12345abcd:abcde/confirm-funds?amount=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json

fundsAvailableboolean(boolean)

A flag indicating whether funds are available or not. If set to true, funds are available for transfer.

Default false

Example: false

Response

application/json

{
  "fundsAvailable": false
}

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

Requests - for Payments v1 or AIS

Transfers - for Payments v1

Variable Recurring Payments

Create a VRP consent

RequestExpand all

Responses

Get VRP consents

Request

Responses

Get a VRP consent

Request

Responses

Revoke a VRP consent

Request

Responses

Get payments under a VRP consent

Request

Responses

Initiate a VRP payment

RequestExpand all

Responses

Get VRP payments

Request

Responses

Get a VRP payment

Request

Responses

Verify if funds are available or not

Request

Responses

Refunds

Payouts

Settlement Accounts

Accounts

Tokens

Banks v1

Banks v2

Sub-TPPs

Authentication keys

Reports

Webhooks

Request

Request