Navbar MENU

Getting Started

Welcome

Welcome to the OrangePay PSD2 API documentation. The OrangePay PSD2 API allows Third-Party Service Providers to communicate with OrangePay ASPSP in a simple, programmatic way using convetional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions. The API terms and methods based on STET API Specification at https://www.stet.eu/en/psd2/. For example, acronyms from PSD2 (TPP, AISP, etc.) and the public STET Specification will be used without further elaboration.

The SCA workflows reference a number of endpoints defined in various OAuth 2-related specifications, here is a summary of the available endpoints, their role, and their URLs.

Authorization

OAuth2 endpoints are used as the entry point for the authorization code workflows, which, in the PSD2 context, are used so that the PSU can grant access to the TPP in an SCA process.

Redirect user to:

/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=aisp&state=1234zyx

Parameter Description
response_type Indicates that your server expects to receive an authorization code
client_id The client ID you received from ASPSP
redirect_uri Indicates the URI to return the user to after authorization is complete
scope One or more scope values indicating which parts of the user's account you wish to access
state A random string generated by your application, which you'll verify later

AISPs can specify the following scopes:

CBPIIs can specify the following scope:

Then user will see the authorization prompt.

If the user clicks "Allow", the service redirects the user back to your site with an auth code:

https://domain.ltd/cb?code=AUTH_CODE_HERE&state=1234zyx

Parameter Description
code The server returns the authorization code in the query string
state The server returns the same state value that you passed

You should first compare this state value to ensure it matches the one you started with. This ensures your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.

Token Exchange

If the state parameter matches, you should issue a POST request to request an access token. The request should include the authorization code that was issued by API when the user approved the authorization request.

POST /oauth/token

Parameter Description
grant_type The grant type for this flow is authorization_code
code This is the code you received in the query string
redirect_uri Must be identical to the redirect URI provided in the original link
client_id The client ID you received from ASPSP
client_secret The secret you received from ASPSP

This route will return a JSON response containing access_token, refresh_token, and expires_in attributes.
The expires_in attribute contains the number of seconds until the access token expires.

Refreshing Tokens

Sometimes you will need to refresh access tokens via the refresh token that was provided to you when the access token was issued. For achieving this, you need make next POST request:

POST /oauth/token

Parameter Description
grant_type The grant type for this flow is authorization_code
code This is the code you received in the query string
redirect_uri Must be identical to the redirect URI provided in the original link
client_id The client ID you received from ASPSP
client_secret The secret you received from ASPSP
scope One or more scope values

This route will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

PSD2 API Request Headers

The PSU-* family of headers, that allow the TPP to forward PSU device, location and usage information to the ASPSP, are facultative. The following headers are defined:

Header Description
PSU-IP-AddressThe IP Address on which the PSU is connected to the TPP;
PSU-IP-PortThe TCP Port of the PSU Terminal on which he is connected to the TPP;
PSU-DateThe timestamp of the relevant PSU action;
PSU-HTTP-MethodHTTP Method for the most relevant PSU's HTTP request to the TPP;
PSU-AcceptAccept HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-CharsetAccept-Charset HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-EncodingAccept-Encoding HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-LanguageAccept-Language HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-RefererReferer HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-User-AgentUser-Agent HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-GEO-LocationThe PSU location as returned by their mobile terminal;
PSU-Device-IDThe PSU Device ID - usually only available on a mobile terminal;

AISP Endpoints

There is list of methods avaliable for AISPs.

The TPP must be registered as an AISP.

The TPP must have obtained the PSU's authorization for API Access, with an SCA.

The TPP must access the API using an Authorization Code access token derived from the PSU's authorization.

GET /accounts - This call returns all payment accounts linked to the PSU.

Example response content:

{
  "data": {
    "accounts": [
      {
        "id": "11111110000",
        "balance": "1000.00",
        "attributes": {
          "title": "Account (Euro)",
          "type": "BAEUR",
          "currency": "EUR"
        },
        "links": {
          "transactions_uri": "/api/accounts/11111110000/transactions"
        }
      },
      {
        "id": "11111110001",
        "balance": "0.00",
        "attributes": {
          "title": "Account (United States Dollar)",
          "type": "BAUSD",
          "currency": "USD"
        },
        "links": {
          "transactions_uri": "/api/accounts/11111110001/transactions"
        }
      }
    ]
  },
  "meta": {
    "server_time": 1568204939,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

GET /accounts/{accountResourceId} - This call returns all data of requested PSU payment account.

Example response content:

{
  "data": {
    "id": "11111110001",
    "balance": "0.00",
    "attributes": {
      "title": "Account (United States Dollar)",
      "type": "BAUSD",
      "currency": "USD"
    },
    "links": {
      "transactions_uri": "https://domain.ltd/api/accounts/11111110001/transactions"
    }
  },
  "meta": {
    "server_time": 1568205085,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

GET /accounts/{accountResourceId}/transactions - This call returns transaction information for one of the PSU's accounts. Returned results may be paginated.

Example response content:

{
  "data": {
    "transactions": {
      "total": 1,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1,
      "next_page_url": null,
      "prev_page_url": null,
      "from": 1,
      "to": 1,
      "data": [
        {
          "id": "ff160f90-d490-11e9-bcf5-6b2bb9667cfa",
          "attributes": {
            "type": "withdrawal",
            "status": "pending",
            "amount": "50.00",
            "currency": "EUR",
            "description": "Bank account transfer",
            "created_at": 1568205519
          }
        }
      ]
    }
  },
  "meta": {
    "server_time": 1568205957,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

GET /accounts/{accountResourceId}/transactions/{transactionResourceId} - This call returns requested transaction information.

Example response content:

{
  "data": {
    "transaction": {
      "id": "ff160f90-d490-11e9-bcf5-6b2bb9667cfa",
      "attributes": {
        "type": "withdrawal",
        "status": "pending",
        "amount": "50.00",
        "currency": "EUR",
        "description": "Bank account transfer",
        "created_at": 1568205519
      }
    }
  },
  "meta": {
    "server_time": 1568206055,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

CBPII Endpoints

There is list of methods avaliable for CBPIIs.

The TPP must be registered as an CBPII.

The TPP must have obtained the PSU's authorization for API Access, with an SCA.

The TPP must access the API using an Authorization Code access token derived from the PSU's authorization.

POST /funds-confirmations - This call returns whether a payment with the given characteristics (account, payee, amount) may be covered.

Parameters

Parameter Description
amountrequiredTransfer amount
currencyrequiredTransfer currency (possible values: USD, EUR, RUB)

Example response content: (funds could be covered)

{
  "data": {
    "result": true,
  "meta": {
    "server_time": 1568206055,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

Example response content: (funds could not be covered)

{
  "data": {
    "result": false,
  "meta": {
    "server_time": 1568206055,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

PISP Endpoints

There is list of methods avaliable for PISPs.

The TPP must be registered as an PISP.

The TPP must have obtained the PSU's authorization for API Access, with an SCA.

The TPP must access the API using an Authorization Code access token derived from the PSU's authorization.

Parameter Description
amountrequiredTransfer amount
currencyrequiredTransfer currency (possible values: USD, EUR, RUB)
beneficiary_namerequiredBeneficiary name
beneficiary_addressrequiredBeneficiary address
beneficiary_account_numberrequiredBeneficiary account number
beneficiary_swiftrequiredBeneficiary swift number
beneficiary_bankrequiredBeneficiary bank
beneficiary_countryrequiredBeneficiary country
beneficiary_cityrequiredBeneficiary city
intermediary_swiftIntermediary swift number
intermediary_bankIntermediary bank
intermediary_account_numberIntermediary account number
intermediary_addressIntermediary address
reference_numberReference number

There are available transfer statuses:

Example response content:

{
  "data": {
    "transfer": {
      "id": "0c1a2690-d493-11e9-ba52-6d2a9f4b7b3b",
      "attributes": {
        "type": "transfer",
        "status": "pending",
        "amount": 50,
        "currency": "EUR",
        "description": null,
        "requisites": {
          "beneficiary_name": "John Doe",
          "beneficiary_address": "Test street 42",
          "beneficiary_account_number": "10101111",
          "beneficiary_swift": "CHASUS00XXX",
          "beneficiary_bank": "Test BANK",
          "beneficiary_country": "CZ",
          "beneficiary_city": "Prague",
          "intermediary_swift": null,
          "intermediary_bank": null,
          "intermediary_account_number": null,
          "intermediary_address": null,
          "reference_number": "Payment for goods #1110111"
        },
        "created_at": 1568206363
      }
    }
  },
  "meta": {
    "server_time": 1568206364,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}

GET transfers/{transferResourceId} - This call returns requested transfer details.

Example response content:

{
  "data": {
    "transfer": {
      "id": "0c1a2690-d493-11e9-ba52-6d2a9f4b7b3b",
      "attributes": {
        "type": "transfer",
        "status": "pending",
        "amount": 50,
        "currency": "EUR",
        "description": null,
        "requisites": {
          "beneficiary_name": "John Doe",
          "beneficiary_address": "Test street 42",
          "beneficiary_account_number": "10101111",
          "beneficiary_swift": "CHASUS00XXX",
          "beneficiary_bank": "Test BANK",
          "beneficiary_country": "CZ",
          "beneficiary_city": "Prague",
          "intermediary_swift": null,
          "intermediary_bank": null,
          "intermediary_account_number": null,
          "intermediary_address": null,
          "reference_number": "Payment for goods #1110111"
        },
        "created_at": 1568206363
      }
    }
  },
  "meta": {
    "server_time": 1568206364,
    "server_timezone": "UTC",
    "api_version": "v2"
  }
}