--- title: "Get payments" method: GET path: "/v2/payments" tags: ["Payments v2"] --- # Get payments `GET /v2/payments` The `GET /v2/payments` endpoint provides you with a list of payments and their details. ## Query parameters - `limit` integer, required - `offset` string - `ids` string[] - `invertIds` boolean - `statuses` PaymentStatus[] - `invertStatuses` boolean - `createdAfter` string - `createdBefore` string - `refIds` string[] - `onBehalfOfId` string - `refundStatuses` PaymentRefundStatus[] - `partial` boolean - `externalPsuReference` string — An external reference provided by the TPP (Third Party Provider) to uniquely identify the PSU (Payment Service User). - `type` 'SINGLE_IMMEDIATE_PAYMENT' | 'VARIABLE_RECURRING_PAYMENT' - `vrpConsentId` string ## Response `200` Successful response - PaymentsResponse - `payments` Payment[], required - `id` string, required — The Token.io generated payment id. - `memberId` string, required — The Token.io-assigned member id of the TPP. - `initiation` PaymentInitiation, required — The initiation payload for the payment. All standard flow types — amount and remittanceInformationPrimary are required. - `bankId` string — 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.** - `refId` string, 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. - `remittanceInformationPrimary` string, 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 (18 characters for UK Faster Payments). - `remittanceInformationSecondary` string — 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. - `onBehalfOfId` string — 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. - `vrpConsentId` string — Only for Variable recurring payments (VRP). VRP consent id. - `amount` Amount, required — The transaction amount and currency. - `value` string, required — The transaction amount with up to four digits after the decimal point. - `currency` string, required — The ISO 4217 three letter currency code. - `localInstrument` 'SEPA' | 'SEPA_INSTANT' | 'FASTER_PAYMENTS' | 'ELIXIR' | 'EU_DOMESTIC_NON_EURO' | 'EU_DOMESTIC_NON_EURO_INSTANT' | 'BANKGIRO' | 'PLUSGIRO' | 'AUTO_SELECT', required — The bank's payment service used to make the payment.
Depending on which local instrument you select, you will require different account identifiers in the `debtor` and `creditor` objects. The `creditor` object is mandatory, but the `debtor` object is only required if it is mandatory for a specific bank. However, if the TPP decides to provide debtor details, account identifier field(s) within the `debtor` object are mandatory.
The fields within the `creditor` and `debtor` objects are populated as follows: - `debtor` union — Debtor information. Provide either an Account on File OR full Debtor Account details. These two modes are mutually exclusive. - union - object — SEPA account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — SEPA Instant account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — A UK or Irish account where the sort code and account number are required. - `accountNumber` string, required — The unique identifier for the bank account in the UK or Ireland. - `sortCode` string, required — The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Polish account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the bban is required and the bic is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the bban is required and the clearing number is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the bban is required and the bic is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the bban is required and the clearing number is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the bankgiroNumber is required and the bic is optional. - `bankgiroNumber` string, required — The unique identifier for the bank account in Sweden (known in Swedish as Bankgironummer), it consists of 7 or 8 digits. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - object — Account details where the plusgiroNumber is required and the bic is optional. - `plusgiroNumber` string, required — The unique identifier for the Swedish money transaction system owned by Nordea. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The debtor’s account owner name. - `ultimateDebtorName` string — The ultimate debtor’s name. - `address` Address — Address - … - TokenizedAccountIdentifier - `tokenizedAccountId` string, required — Account on File identifier. - `creditor` union, required - object — SEPA account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — SEPA Instant account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — A UK or Irish account where the sort code and account number are required. - `accountNumber` string, required — The unique identifier for the bank account in the UK or Ireland. - `sortCode` string, required — The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Polish account details where the account number is required and the bic is optional. - `accountNumber` string, required — The payee's Elixir-registered bank account number. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Polish account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the bban is required and the bic is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the bban is required and the clearing number is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the iban and bban are required and the bic and clearing number are optional. This is ONLY allowed for an HP flow if there is no `bankId` provided in the initiation AND the currency is SEK or NOK. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the bban is required and the bic is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the bban is required and the clearing number is optional. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the iban and bban are required and the bic and clearing number are optional. This is ONLY allowed for an HP flow if there is no `bankId` provided in the initiation AND the currency is SEK or NOK. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bban` string, required — Represents a country-specific bank account number. The BBAN is the last part of the IBAN when used for international funds transfers. Every country has its own specific BBAN format and length. At present, there is no common EU or other standard unifying the BBAN. This is why IBAN was introduced to standardise international bank transfers. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `clearingNumber` string — The bank clearing number or BC number is a number used for the identification of financial institutions in Switzerland and Liechtenstein. Bank clearing numbers are connected to the Swiss Interbank Clearing and the EuroSIC system. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the bankgiroNumber is required and the bic is optional. - `bankgiroNumber` string, required — The unique identifier for the bank account in Sweden (known in Swedish as Bankgironummer), it consists of 7 or 8 digits. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — Account details where the plusgiroNumber is required and the bic is optional. - `plusgiroNumber` string, required — The unique identifier for the Swedish money transaction system owned by Nordea. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long." - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - object — The creditor settlement account details. - `virtualAccountId` string, required — The unique identifier for the settlement account. This field is mandatory for unregulated TPPs. - `name` string, required — The owner's name for the creditor account. This parameter is not required for settlement accounts. - `ultimateCreditorName` string — The ultimate creditor's name. - `address` Address — Address - `addressLine` string[] - `streetName` string — Street number - `buildingNumber` string — Building number - `postCode` string — Post Code - `townName` string — Town name - `state` string — State - `district` string — The district. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `bankName` string — The creditor's bank name. - `executionDate` string — This field specifies the future date for executing the payment in ISO 8601 format.". ***This field is optional and can only be used if the bank supports scheduled payments and the customer has permission to initiate future dated payments.*** - `confirmFunds` boolean — This field determines whether the bank will carry out a funds confirmation check before accepting the payment. Default = false. - `returnRefundAccount` boolean — Supported banks will provide the debtor account details selected by the user during authorization. Default = false. - `disableFutureDatedPaymentConversion` boolean — This field determines whether an auto-conversion of a single immediate payment to a future dated payment can be disabled. This may be required if the payment was initiated outside bank working hours. Default = false. - `returnTokenizedAccount` boolean — This field generates tokenized account ID for given debtor account details. - `callbackUrl` string, 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. - `callbackState` string — 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. - `chargeBearer` 'INVALID_CHARGE_BEARER' | 'CRED' | 'DEBT' | 'SHAR' | 'SLEV' — The bearer of the charge, if any, for international transfers. - `risk` Risk — This field is used to specify additional details for the risk scoring of payments. - `psuId` string — The merchant's unique customer identifier for the user. - `paymentContextCode` 'INVALID_PAYMENT_CONTEXT_CODE' | 'BILLING_GOODS_AND_SERVICES_IN_ADVANCE' | 'BILLING_GOODS_AND_SERVICES_IN_ARREARS' | 'PISP_PAYEE' | 'ECOMMERCE_MERCHANT_INITIATED_PAYMENT' | 'FACE_TO_FACE_POINT_OF_SALE' | 'TRANSFER_TO_SELF' | 'TRANSFER_TO_THIRD_PARTY' — This field describes the context of the payment context. This field is an OBIE standard and also maps to NextGenPsd2's `purposeCode` and `categoryPurposeCode` fields. We recommend that the TPP populates this field. - `paymentPurposeCode` 'CASH' | 'CORT' | 'DVPM' | 'INTC' | 'TREA' | 'SUPP' — The category code conforming to the Recommended UK Purpose Code in the ISO 20022 Payment Messaging List, related to the type of services or goods corresponding to the underlying purpose of the payment. This list applies to all banks that follow ISO 20022. - `merchantCategoryCode` string — The category code conforming to ISO 18245, relating to the type of services or goods provided by the merchant. A list of codes can be purchased here." - `beneficiaryAccountType` 'PERSONAL' | 'JOINT_PERSONAL' | 'PERSONAL_SAVINGS_ACCOUNT' | 'BUSINESS' | 'BUSINESS_SAVINGS_ACCOUNT' | 'CHARITY' | 'COLLECTION' | 'CORPORATE' | 'GOVERNMENT' | 'EWALLET' | 'INVESTMENT' | 'ISA' | 'PREMIER' | 'WEALTH' | 'PENSION' — This information should be provided if the `AccountType` is known. - `contractPresentIndicator` boolean — This field indicates whether a Payee has a contractual relationship with the Payment Initiation Service Provider (PISP). - `beneficiaryPrepopulatedIndicator` boolean — This field indicates whether the Payment Initiation Service Provider (PISP) has immutably prepopulated payment details for the user. - `deliveryAddress` DeliveryAddress — Specifies the recipient's delivery address details. - `addressLine` string[] — Specifies the delivery address using multiple lines, as necessary. - `addressType` 'INVALID_ADDRESS_TYPE' | 'BUSINESS' | 'CORRESPONDENCE' | 'DELIVERYTO' | 'MAILTO' | 'POBOX' | 'POSTAL' | 'RESIDENTIAL' | 'STATEMENT' — Specifies the type of address. - `buildingNumber` string — The building number within the delivery address. - `country` string — Two-letter country code in upper case (ISO 3166-1 alpha-2). - `countrySubDivision` string[] — Identifies a subdivision of a country; for instance, a state, region, or county. - `department` string — This OBIE specification maps to house number. - `postCode` string — An identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. - `streetName` string — The name of the respective street or thoroughfare in which the dwelling or business is located or where mail is received. - `subDepartment` string — This OBIE specification maps to flats. - `townName` string — The name of a built-up area with defined boundaries and a local government. - `flowType` 'API_ONLY' | 'FULL_HOSTED_PAGES' | 'EMBEDDED_HOSTED_PAGES', required — The integration option requested by the TPP. - `externalPsuReference` string — An external reference provided by the TPP (Third Party Provider) to uniquely identify the PSU (Payment Service User). - `convertedToFutureDatedPayment` boolean — This field indicates whether a payment has been converted from a single immediate payment to a future dated payment. This can happen if the payment is initiatied outside bank working hours and `paymentInitiation.disableFutureDatedPaymentConversion` = false. - `refundDetails` RefundDetails — The refund-related information for this payment. This field requires specific permission and is only available if `paymentInitiation.returnRefundAccount` is set to `true`. - `refundAccount` union, required - object — SEPA Instant account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string — The name of the account owner. - object — SEPA account details where the iban is required and the bic is optional. - `iban` string, required — The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters. - `bic` string — The Business Identifier Code (BIC), ISO 9362, is the address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs can be either 8 or 11 characters long. - `name` string — The name of the account owner. - object — A UK or Irish account where the sort code and account number are required. - `accountNumber` string, required — The unique identifier for the bank account in the UK or Ireland. - `sortCode` string, required — The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland. - `name` string — The name of the account owner. - `paymentRefundStatus` 'NONE' | 'PARTIAL' | 'FULL' — The refund status for this payment. - `settledRefundAmount` object — The transaction amount and currency. - `value` string, required — The transaction amount with up to four digits after the decimal point. - `currency` string, required — The ISO 4217 three letter currency code. - `remainingRefundAmount` object — The transaction amount and currency. - `value` string, required — The transaction amount with up to four digits after the decimal point. - `currency` string, required — The ISO 4217 three letter currency code. - `status` 'INITIATION_PENDING' | 'INITIATION_PENDING_REDIRECT_AUTH' | 'INITIATION_PENDING_REDIRECT_AUTH_VERIFICATION' | 'INITIATION_PENDING_REDIRECT_HP' | 'INITIATION_PENDING_REDIRECT_PBL' | 'INITIATION_PENDING_EMBEDDED_AUTH' | 'INITIATION_PENDING_EMBEDDED_AUTH_VERIFICATION' | 'INITIATION_PENDING_DECOUPLED_AUTH' | 'INITIATION_PENDING_REDEMPTION' | 'INITIATION_PENDING_REDEMPTION_VERIFICATION' | 'INITIATION_PROCESSING' | 'INITIATION_COMPLETED' | 'INITIATION_REJECTED' | 'INITIATION_REJECTED_INSUFFICIENT_FUNDS' | 'INITIATION_FAILED' | 'INITIATION_DECLINED' | 'INITIATION_EXPIRED' | 'INITIATION_NO_FINAL_STATUS_AVAILABLE' | 'SETTLEMENT_IN_PROGRESS' | 'SETTLEMENT_COMPLETED' | 'SETTLEMENT_INCOMPLETE' | 'CANCELED', required — The Token.io Payment Status:
During settlement of a settlement accounts payment, the status update job will run first for up to 30 days. Payment will then enter into a 'final' status, normally `INITIATION_COMPLETED`.
Once the status update job has run, the reconciliation job looks for matching inbound payments.
For SEPA payments:For SEPA Instant payments: - `statusReasonInformation` string — 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. - `bankPaymentStatus` string — The raw bank status. This can be the ISO 20022 payment status code. See ISO 20022 payment status codes for more information. This field can be empty if no payment status is available on bank side. - `bankPaymentId` string — The payment id from the bank. Not all banks provide this. This field can be left empty if information is not available from the bank side. - `bankTransactionId` string — The transaction id from the bank when the transaction is settled. Not all banks provide this. This field can be left empty if information is not available from the bank. - `bankVrpId` string — Present only if payment is VRP. The VRP id from the bank. This field can be empty if the VRP id isn't available on the bank's side. - `bankVrpStatus` string — Present only if payment is VRP. The raw bank status. This field can be empty if payment status isn't available on the bank's side. - `authentication` union — The authentication operation required to proceed with payment creation. This is present when additional steps are required to authorize the payment. - object - `redirectUrl` string, required — The url used to redirect the user to in order to authorize the consent creation. This should be populated if the payment status is `INITIATION_PENDING_REDIRECT_AUTH`.
If the status is: `INITIATION_PENDING_REDIRECT_AUTH`, the authentication object should have the `redirectUrl`. Redirect the user to this url in order to proceed with the flow.
If the status is: `INITIATION_PENDING_REDIRECT_PBL`, the authentication object will contain the payment link (redirect url). Redirect the user to this url to initiate the Pay by Link Hosted Pages flow, where any missing information (such as amount or reference) can be collected before proceeding with payment authentication.
If the TPP is responsible for handling the callbacks, the bank will callback to the TPP's callbackUrl provided in the payment initiation, after the user finishes authentication at the bank. Send the query of the bank's callback url to Token.io via the `POST /callback/initiation` endpoint to proceed with the flow.
Otherwise Token.io will receive the callback from the bank and callback the TPP when the bank callback is processed. Fetch the payment object and check its status for further steps, if any. - object — Information and fields presented to the user in order to collect the requested data. This should be populated if the payment status is `INITIATION_PENDING_EMBEDDED_AUTH`.
If the status is: INITIATION_PENDING_EMBEDDED_AUTH, the authentication object should list the required embedded fields. Collect the data from the user and provide it using POST /v2/payments/{paymentId}/embedded-auth to proceed with the flow. - `description` string — The text displayed to a user. This should contain the instructions the user needs to proceed with the authentication. - `image` string — A Base64 representation of an image displayed to the user. - `flickerCode` string — The Flicker code displayed to the user. - `fields` RequiredField[], required — The required fields. The values for these are collected from the user. - `type` 'FIELD' | 'PASSWORD' | 'CHOICE_FIELD', required — The `type` determines how the field is presented to the user. - `id` string, required — The ID used when passing the value of this field to Token.io. - `displayName` string, required — The name of the requested field displayed to the user. - `additionalInformation` string — Additional information about this field. - `options` string[] — A list of options for the user to select from. For example, it can be an SCA method choice (SMS message, phone call etc.), or confirm/decline options for a confirmation page. The customer sends one of the values back to Token.io with the corresponding id. - `isRetry` boolean — This field indicates whether the previously submitted values are incorrect and whether the user needs to retry. If `isRetry` = true, the values are resubmitted. Default = false. - `createdDateTime` string, required — The date and time this payment object was created (in ISO 8601 format). - `updatedDateTime` string, required — The date and time this payment object was last updated (in ISO 8601 format). - `errorInfo` ErrorInfo — This field will be populated if the status is final and the payment is not successful, or there has been an error that caused payment rejection, or the bank could not be reached to get a status update. - `httpErrorCode` integer, required — The HTTP error code. - `message` string — The message accompanying the HTTP error code. - `tokenExternalError` boolean — Is set to `true` the error is external, e.g., a 5xx error resulting from the bank. This field can be populated as a result of both 4xx and 5xx errors. We recommend that you only rely on it for 5xx errors. - `tokenTraceId` string — The unique trace identifier, captured from the originating request and sent to the bank to be stored with the request throughout its lifecycle. It serves primarily as an audit-trail aid, for debugging the message exchange flow during sandbox testing, and for issue resolution in production. - `paymentLinkStatus` 'LINK_ACTIVE' | 'LINK_EXPIRED' | 'LINK_CANCELED' | 'LINK_REDEEMED' — If the payment was initiated using a Pay by Link flow type, this shows the status of the payment link. For all other flows, this field is empty. - `pageInfo` PageInfo, required — The information about the current page, which also indicates whether the next page exists. - `limit` integer, 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. - `offset` string — 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. - `nextOffset` string — 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. - `haveMore` boolean — This field indicates whether there are more objects to load, i.e. whether the next page exists. ## Other responses - `400` — The client specified an invalid argument. - `401` — The authorization information is missing or invalid - `500` — An unexpected or internal server error --- [API](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps.md) · [All operations](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/token/token-io-s-open-banking-api-for-tpps/versions/5e8d6d2c24a1/schema)