NAV Navbar
shell

Getting Started

Introduction

The International Fintech API (Application Programming Interface) is a web service offered by International Fintech to TPPs (Third Party Providers) to simplify the integration process with International Fintech's systems. This API allows TPPs to easily interact with the International Fintech Platform. Via the API, TPPs can retrieve information about accounts, balances and transactions, as well as create new transactions.

Definitions

Term Definition
AISP Account Information Services provide consolidated information on Client payment accounts held at one or more PSP(s).
ASPSP Account Servicing Payment Service Providers provide and maintain a payment account for a Client.
CBPII Card Based Payment Instrument Issuers are PSPs that issue card-based payment instruments.
Client A bank account holder. International Fintech Clients can only ever be legal entities.
PISP Payment Initiation Services Providers facilitate the initiation of payment order(s) to an account held at another PSP on the request of a Client.
PSP A Payment Services Provider is an entity which carries out regulated payment services, including AISPs, PISPs, CBPIIs and ASPSPs.
TPP Third Party Providers are legal entities or natural persons that use APIs to access Client accounts in order to provide account information services and/or to initiate payments.
User A User in the context of this documentation is a person authorised to access and/or perform actions on a Client account held with International Fintech.

Become a TPP

TPP Registration

curl -X POST "https://api.international-fintech.com/api/v1/third-party-provider"
-H "Content-Type": "application/json"
-d '{
      "name": "demo name",
      "certificate": "Demo cert",
      "email": "[email protected]",
      "phoneNumber": "1112233"
    }'

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result": "Success. TPP key and TPP secret were sent to your email address."
}

The process of TPP registration is initiated via a request made to the International Fintech API. Following the request, the TPP certificate is validated and access is granted on successful validation.

HTTP Request

POST https://api.international-fintech.com/api/v1/third-party-provider

Body Parameters

Parameter Type Description
Name String name of the service providering company
Certificate String The eIDAS certificate confirming the TPP's license as a service provider.
Email String Email address of the contact person in the service providering company
PhoneNumber String Phone number of the contact person in the service providering company

Application Registration

curl -X POST "https://api.international-fintech.com/api/v1/application"
-H "Content-Type": "application/json"
-H "tpp-key": "<TPP_KEY>"
-H "tpp-secret": "<TPP_SECRET>"
-d '{
        "name": "Your application name",
        "redirectUri": "https://your-application-domain.com"
      }'

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result": "Success. Application key and Application secret were sent to your email address."
}

The TPP application might refer to a website, mobile application, and so on. The client authorizes access for the TPP's application to use the API resources. This authorization is acquired via the Access Authorization flow.

HTTP Request

POST https://api.international-fintech.com/api/v1/application

Body Parameters

Parameter Type Description
Name String Name (label) of the application.
RedirectUri String URI where user is redirected to after authorization.

Authentication

The International Fintech API is JSON based. In order to make an authenticated call to the API, you must include your access token with the call. OAuth2 uses a BEARER token that is passed along in an Authorization header.

After successfully registering as TPP, you will be given a set of 2 unique keys:

These two keys are subsequently used to obtain access tokens for making API calls.

Authentication Flow

Authentication endpoints are as follows:

The International Fintech API uses common OAuth 2.0 Authorization Code with Refresh Token flow

Authorization Code with Refresh Token

The Authorization Code flow is a redirection-based flow, which means the application must be able to redirect the application user and receive authorization codes via a web browser

Phase 1: Authorization Phase

open https://api.international-fintech.com/authorize?app-key=<APPLICATION_KEY>

Make sure to replace <APPLICATION_KEY> with your details.

An authorization code is the key used to retrieve the access token. In order to acquire an authorization code, you need to redirect the user's browser to the authorization endpoint. https://api.international-fintech.com/authorize?app-key=<APPLICATION_KEY>

Phase 2: User Authorization

Once directed to the above link, the user will be asked to log in to their International Fintech account. They will then be asked to define the level of access (scope) for his account.

Phase 3: Authorization Code response

After the user successfully authorizes the application, they will be redirected back to the {redirectUri} (provided during application registration) with the authorization code as a query parameter named code.

e.g. https://my.tppawesomeapp.com/auth/callback?code=123c6348c57ccv920

Phase 4: Requesting an Access Token

curl -X POST https://api.international-fintech.com/token
-H "Content-type: application/x-www-form-urlencoded"
-H "app-key": "<APPLICATION_KEY>",
-H "app-secret":"<APPLICATION_SECRET>",
-H "app-authentication-code": "<AUTHENTICATION_CODE>"
-d '{"grant_type": "authorization_code"}'

The above command returns JSON structured like this:

{
  "access_token": "27dd301af04bf352e0sd45feb5ef469ab2f046aff66",
  "expires_in": 72059,
  "refresh_token": "9821344he0v6j82355tbfb30908769a00aea43d0u5s",
  "token_type": "bearer",
  ".issued": "Tue, 29 May 2019 09:00:00",
  ".expired": "Tue, 30 Jul 2019 09:00:00"
}

The access token is a unique key used to make requests to the API.

In order to get an access token, the application must make a POST request to https://api.international-fintech.com/token with the app-key, app-secret, app-authentication-code and grant_type as parameters.

Phase 5: Refreshing an Access Token

To authorize using refresh token, use this code:

curl -X POST https://api.international-fintech.com/token
-H "Content-type": "application/json"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"
-d '{ "refresh_token": "<REFRESH_TOKEN>", "grant_type": "refresh_token"}'

The above command returns JSON structured like this:

{
  "access_token": "27dd301af04bf352e0sd45feb5ef469ab2f046aff66",
  "expires_in": 7200,
  "refresh_token": "27dd301af04bf352e0sd45feb5ef469ab2f046aff66",
  "token_type": "bearer",
  ".issued": "Tue, 29 May 2019 09:00:00",
  ".expired": "Tue, 30 Jul 2019 09:00:00"
}

A refresh token is a unique token returned when creating an access token that can be used to request a new access token when the existing current access token expires.

To refresh an access token, the application must make a POST request to https://api.international-fintech.com/token with the app-key, app-secret, refresh_token and grant_type as parameters.

Consent

TPP can check if consent is present and it’s expiration date (via GET request) and send us a notification that user has granted the consent (via PUT request). PUT request will also contain expiration date in it’s response.

curl -X GET "https://api.international-fintech.com/api/v1/consent"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result":
  {
    "expirationDate": "2019-12-03T17:06:34.707"
  }
}

This endpoint checks if the client gave his consent for the TPP to access his account data. The endpoint Returns the content of an account information consent object.

HTTP Request

GET https://api.international-fintech.com/api/v1/consent

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process
curl -X PUT "https://api.international-fintech.com/api/v1/consent"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result":
  {
    "expirationDate": "2019-12-03T17:12:56.30"
  }
}

This endpoint creates a resource for the TPP, as per the client's consent, to access the client's account data which is specified in the request.

HTTP Request

PUT https://api.international-fintech.com/api/v1/consent

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Sandbox

Sandbox is the place where you can get to know our International Fintech API. It provides the same APIs as our production environment but with mock data.

Using the API in sandbox

For using an International Fintech API in sandbox just replace the https://api.international-fintech.com/ with https://sandbox.international-fintech.com/ and follow the same detailed instructions in the International Fintech API documentation.

Test credentials

Parameter Value Description
userName [email protected] The PSU username to be provided on login to PSU account
password Sitepassword001 The PSU password to be provided on login to PSU account
pin 123456 The PSU 2FA pin code to be provided on login to PSU account
OTP 1111 The PSU On-time-password to be provided in Payment Confirmation

Account Information (AIS)

The Account & Transaction API gives read-only access to the client's account information and transaction data. Access is granted through an explicit consent, which must be provided to the AISP by the client.

Get Accounts

curl -X GET "https://api.international-fintech.com/api/v1/accounts/all"
-H "Content-Type": "application/json"
-H "Authorization": "Bearer <ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result":
  [
    {
      "id": 4536547,
      "iban": "DE89 3704 0044 0532 0130 00",
      "bankName": "Commerzbank",
      "balanceAmount": 100155.00,
      "pendingAmount": 32654.15,
      "minBalance": 500,
      "description": "Collection account",
      "currency": "EUR"
    },
    {
      "id": 756854,
      "iban": "GB33BUKB20201555555555",
      "bankName": "BARCLAYS BANK UK PLC",
      "balanceAmount": 1500000.00,
      "pendingAmount": 0.0,
      "minBalance": 450,
      "description": "GBP account",
      "currency": "GBP"
    }
  ]
}

Returns all accounts owned and consented to by the end user (account owner). Account balance will only be returned if the end user has consented to the application accessing the account's information.

HTTP Request

GET https://api.international-fintech.com/api/v1/accounts/all

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Get Single Account

curl -X GET "https://api.international-fintech.com/api/v1/accounts/4536547/balances"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "APPLICATION_SECRET"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result":
  [
    {
      "balanceAmount": 100155.11,
      "pendingAmount": 32654.15,
      "minBalance": 500,
      "description": "Collection account",
      "currency": "EUR"
    }
  ]
}

Returns the balance of each currency held in the client's account, based on the provided {accountId}.

HTTP Request

GET https://api.international-fintech.com/api/v1/accounts/{accountId}/balances

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Get Account Transactions

curl -X GET "https://api.international-fintech.com/api/v1/accounts/{accountId}/transactions/range?startdate=20190601Z&enddate=20190615Z"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result":
  [
    {
      "id": 512461,
      "source": 3,
      "company": "Reimer GmbH",
      "counterparty":
      {
        "name": "Appel Wilhelm KG",
        "country":
        {
          "name": "Germany",
          "dialCode": "+49",
          "code": "DE"
        },
        "address": "Luise-Brückner-Platz 89b00129 Ratingen"
      },
      "bankDetails":
      {
        "name": "Commerzbank",
        "country":
        {
          "name": "Germany",
          "dialCode": "+49",
          "code": "DE"
        },
        "address": "Köln 50447",
        "bic": "COBADEFF"
      },
      "intermediaryBank": "",
      "accountNumber": "DE89370400440532013000",
      "routingNumber": "",
      "reason": "Salary payments Jun 19",
      "createDate": "2019-06-11T16:58:29.57",
      "lastModifyDate": "2019-06-13T11:30:36.403",
      "amount": 130000,
      "currency": "EUR",
      "status": 1,
      "isDebit": true,
      "isUrgent": true
    },
    {
      "id": 512789,
      "source": 3,
      "company": "Lang and Sons",
      "counterparty":
      {
        "name": "Hamill, Zboncak and Weimann",
        "country":
        {
          "name": "United Kingdom",
          "dialCode": "+44",
          "code": "UK"
        },
        "address": "38 Jayden DriveRoseburghBB4 5TZ"
      },
      "bankDetails":
      {
        "name": "BARCLAYS BANK UK PLC",
        "country":
        {
          "name": "United Kingdom",
          "dialCode": "+44",
          "code": "UK"
        },
        "address": "Leicester LE87 2BB",
        "bic": "BUKBGB22"
      },
      "intermediaryBank": "",
      "accountNumber": "GB33BUKB20201555555555",
      "routingNumber": "",
      "reason": "Invoice ref num. 43256723",
      "createDate": "2019-06-11T16:58:29.57",
      "lastModifyDate": "2019-06-13T11:30:36.403",
      "amount": 5000.00,
      "currency": "GBP",
      "status": 1,
      "parentId": null,
      "isDebit": true,
      "isUrgent": false
    }
  ]
}

status and source values can be found in Enums section

Returns transactions information for a given account, based on the provided {accountId}.

The operation limits the transactions to the date range set by the startDate and endDate parameters.

Transactions will only include one of the creditor and debtor properties, depending on the type of the transaction. The irrelevant field will be null.

HTTP Request

GET https://api.international-fintech.com/api/v1/accounts/{accountId}/transactions/range?startDate=yyMMddZ&endDate=yyMMddZ

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Query Parameters

Parameter Description
startDate The date from which to start showing the transactions. (e.g: 190915Z = Sep 15, 2019)
endDate The date to which to end showing the transactions. (e.g: 190915Z = Sep 15, 2019)

Payment Initiation (PIS)

Service propositions enabled by customers (PSUs) consenting to Payment Initiation Service Providers (PISPs) initiating payments from their payment accounts.

Payment Initiation Request

curl -X POST "https://api.international-fintech.com/api/v1/payment"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"
-d '{
      "counterparty": {
        "name": "Weber, Gulgowski and Turner",
        "country": {
          "code": "DE"
        },
        "address": "Kareemville, MS 67792"
      },
      "bankDetails": {
        "name": "Commerzbank",
        "country": {
          "code": "DE"
        },
        "address": "Köln 50447",
        "bic": "COBADEFF"
      },
      "intermediaryBank": null,
      "accountNumber": "DE89370400440532013000",
      "amount": 12500,
      "currency": "EUR",
      "routingNumber": "124566457889",
      "reason": "INVOICE 04 2018 - Directors Fees",
      "isUrgent": false
  }'

The above command returns JSON structured like this:

[
  {
    "version": "4.0.0",
    "statusCode": 200,
    "success": true,
    "result": {
        "transactionId": "cd2c8a30-055d-4628-b5f0-30265f4f2209"
    }
  }
]

This operation will create a payment initiation request at International Fintech as a resource with all data relevant for the corresponding payment.

HTTP Request

POST https://api.international-fintech.com/api/v1/payment

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Body Parameters

Level Parameter Type Description
* counterparty Object Counter-party details.
** name String (M) Counter-party full name (first name and surname in case of individual person or company name of legal body). See String Validator.
** countryCode String (M) ISO 3166-1 alpha-2 country code of counter-party address. See Country_code validator.
** address String (M) Counter-party’s address, usually consists of street name, building number, ZIP code, city name, country name. See String Validator.
* bankDetails Object Counter-party's bank details.
** name String (C) Name of counter-party's bank. Optional if "accountNumber" is a Valid IBAN. See String Validator.
** countryCode String (C) ISO 3166-1 alpha-2 country code of counter-party's bank address. Optional if "accountNumber" is a Valid IBAN. See Country_code validator.
** address String (C) Counter-party’s bank address, usually consists of street name, building number, ZIP code, city name, country name. Optional if "accountNumber" is a Valid IBAN. See String Validator.
** bic String (C) BIC code of counter-party's bank. Optional if "accountNumber" is a Valid IBAN. See BIC Validator.
* intermediaryBank String (O) An intermediary bank is any bank between the issuing bank and the beneficiary bank. Adding an intermediary bank to a beneficiary describes the precise path a payment as to follow to reach a beneficiary bank account. There is no intermediary bank for local or SEPA payments. See String Validator.
* accountNumber String (M) Account number (IBAN / BBAN) of the counter-party. See Alphanumeric validator.
* amount Decimal (M) The amount given with fractional digits, where fractions must be compliant to the currency definition. See Positive_decimal validator.
* currency String (M) Transaction amount ISO 4217 currency code. See Currency_code validator.
* routingNumber String (O) Bank clearing number (ABA, FW, CNAPS, etc.), used usually when sending money to North America. See Alphanumeric validator.
* reason String (M) purpose of the payment (usually includes a reference to a provided service or goods). See String Validator.
* isUrgent Boolean (M) A transaction marked as urgent will be sent express at the bank, ahead of the next scheduled processing time. Possible values: true, false.

Payment Confirmation

curl -X POST "https://api.international-fintech.com/api/v1/payment/confirm"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"
-d '{
      "transactionId": "cd2c8a30-055d-4628-b5f0-30265f4f2209",
      "code": "882968"
    }'

The above command returns JSON structured like this:

[
  {
    "transactionId": "123",
    "code":"123"
  },
  {
    "version": "4.0.0",
    "statusCode": 200,
    "success": true
  }
]

This endpoint confirms the payment initiation is not fradulent, through a one-time password sent via SMS to the client.

HTTP Request

POST https://api.international-fintech.com/api/v1/payment/confirm

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Body Parameters

Level Parameter Type Description
* transactionId String (M) Unique identifying number of the transaction from Payment initiation request.
* code String (M) one-time password which was sent to the client via SMS.

Confirmation Availability of Funds (CBPII)

Funds confirmation

curl "https://api.international-fintech.com/api/v1/accounts/{accountId}/check-funds?currency=EUR&amount=322.32"
-H "Content-Type": "application/json"
-H "Authorization": "<ACCESS_TOKEN>"
-H "app-key": "<APPLICATION_KEY>"
-H "app-secret": "<APPLICATION_SECRET>"

The above command returns JSON structured like this:

{
  "version": "4.0.0",
  "statusCode": 200,
  "success": true,
  "result": false
}

A Card Based Payment Instrument Issuer is a payment services provider that issues card-based payment instruments, that can be used to initiate a payment transaction from a payment account (based on the provided {accountId}) held with another payment service provider. Service propositions enabled by customers (PSUs) giving their consent to a CBPII to submit Confirmation of Funds (CoF) requests to an ASPSP.

HTTP Request

GET https://api.international-fintech.com/api/v1/accounts/{AccountId}/check-funds?currency={Currency}&amount={Amount}

Header Parameters

Parameter Description
app-key the application's client ID provided when registering your application
app-secret the application's client secret provided when registering your application
Authorization Authorization token granted during the authorization process

Query Parameters

Parameter Description
currency The currency to check if it has enough balance See Currency_code validator
amount Amount to check if there is enough balance to credit it. See Positive_decimal validator

Enums

Transaction Status Enums

Enum Meaning
1 Pending
2 Settled / Completed
3 Rejected
5 Waiting to be signed.

Transaction source Enums

Enum Meaning
1 FX sell
2 Fx buy
3 Outgoing (debit)
4 Incoming (credit)
5 Fee
6 Correction (credit)
7 Correction (debit)
10 Refund (credit)
11 Refund (fee, credit)
12,13,14 Fix fee (monthly, additional user, setup)

Validations

Validator Meaning
String Upto 100 characters. allows only alphanumeric characters (A-Z, a-z, 0-9) whitespace and some of the special characters (. , ( )_ -)
Alphanumeric Upto 100 characters. allows only alphanumeric characters (A-Z, a-z, 0-9)
Country_code 2 UPPERCASE characters. ISO 3166-1 alpha-2 country code
Positive_decimal amount (D:2) Positive greater than zero decimal number
BIC ISO 9362 BIC (Business Identifier Code). BICs can be 8 or 11 characters in length and contains only UPPERCASE letters or digits.
Currency_code ISO 4217 currency code Length: 3 UPPERCASE letters
Account_number An ISO 13616:2007 valid IBAN OR valid account number / BBAN (alphanumeric (A-Z, a-z, 0-9)

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The data requested is hidden for administrators only.
404 Not Found -- The specified data could not be found.
405 Method Not Allowed -- You tried to access data with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The data requested has been removed from our servers.
429 Too Many Requests
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.