OpenBanking specification

Introduction

Joompay implements a fallback mechanism as a part of the second EU Payment Services Directive (PSD2). Joompay provides gRPC-based API for secure and robust communications with clients. API can be used for retrieving different user’s account information and initiating payments secured by SCA.

Before integrating

For integrating you have to obtain an eIDAS compliant Qualified Certificate. However, you can start integrating before receiving a Qualified Certificate. You should follow next steps:

1. Connect us via open-banking@joompay.com and provide information about your company and application: company name, application name, description on what is application and integration purpose, website, callback URI for OAuth and expected payment service provider roles(check the 3rd paragraph).
2. We will send you back your test TPP Id and test certificate key-pair, which are obligatory for accessing sandbox API. Also, you will get access to our sandbox for testing integration before going to production.
3. After obtaining a real Qualified Certificate, email us with it and provide the public key to get access to the production API.

Integration flow

Flow consists of two main steps: firstly, you should onboard a Joompay user using OAuth mechanism and obtain a token for accessing the API, and secondly, accessing API using Qualified Certificate and user token. Further, we will cover both steps in details.

Obtaining user token

For managing users account access we use OAuth tokens.Next steps show how user token can be retrieved (note, that for the sandbox you should use domains provided in the email):

1. Redirect user to

   https://psd2-oauth.joompay.com/?response_type=code&state={SOME_STATE}&redirectUri={TPP_URI}&clientId={TPP_ID}

   • SOME_STATE – state, according to OAuth specification.
   • TPP_URI – TPP's callback URI, which was provided on onboarding
   • TPP_ID – TPP Id, which was provided on onboarding
2. User should follow steps, described on the website.
3. If authentication was successful, the user will be redirected to a callback with URL parameter code={AUTH_CODE}. Note that code is short lived, about 10 mins.
4. Insert parameters {TPP_ID}, {TPP_URI} and {AUTH_CODE} into the next command and run it in a terminal. (certificate.key, certificate.pem are Qualified Certificate key-pair, which were used on onboarding).

   curl -v \
    -d "grant_type=authorization_code&client_id={TPP_ID}&redirect_uri={TPP_URI}&code={AUTH_CODE}"\
    --cookie "OAuthFlow={AUTH_CODE}" \
    -H "content-type: application/x-www-form-urlencoded" \
    --request POST \
    --key certificate.key \
    --cert certificate.pem \
    'https://psd2-oauth-token.joompay.com/api/v1/oauth/token' 
   

5. Check the response for access_token and refresh_token. The first one will be used for accessing gRPC API. The second one is used for retrieving new access_token, because they are short lived (exact time can be found in response, in the parameter expires_in). To get new access token use this request:

   curl -v \
    -d "grant_type=refresh_token&client_id={TPP_ID}&redirect_uri={TPP_URI}&refresh_token={REFRESH_TOKEN}"\
    -H "content-type: application/x-www-form-urlencoded" \
    --request POST \
    --key certificate.key \
    --cert certificate.pem \
    'https://psd2-oauth-token.joompay.com/api/v1/oauth/token'

API specification

We use gRPC for accessing API, you can download proto files here. Using proto files you can get familiar with our API schema and endpoints. In the next examples, we will show how to access some of our API endpoints.

Before, we should note that we have some mandatory parameters in any endpoint:

1. x-tpp-id header (your TPP Id)
2. x-request-id (randomly generated UUID)
3. user-timezone (ISO-formatted timezone, e.g. Europe/London)
4. Authorization (authorisation in the format "Bearer {USER_ACCESS_TOKEN}")
5. Any request should be done with the Qualified Certificate key-pair.

Now, let’s get to the examples:

Account Information

1. Get balance

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -key certificate.key \
    -cert certificate.pem \
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingAccountInformationService/GetAccountBalance

2. Get account details

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -key certificate.key \
    -cert certificate.pem \
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingAccountInformationService/GetAccountDetails

3. Get activity screen

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -key certificate.key \
    -cert certificate.pem \
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingAccountInformationService/GetActivityScreen

Payment Initiation

API can be used for sending SEPA transfers to other banks. See an example:

1. Validate and get recipient info

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -d '{"iban": "{RECIPIENT_IBAN}", "recipient_name": "{RECIPIENT_NAME}"}' \
    -key certificate.key \
    -cert certificate.pem \
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingPaymentInitiationService/ValidateBankRecipient

2. Execute transfer and get SCA request info. Note, that you should provide the bank recipient id, which you got from the previous step.

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -d '{"client_operation_uuid": "{INDEMPONENCY_UUID}", "amount": {"currency_code": "EUR", "units": "2"}, "description": "{DESCRIPTION}", "to_bank_recipient_id": "{BANK_RECIPIENT_ID}"}' \
    -key certificate.key \
    -cert certificate.pem \
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingPaymentInitiationService/ExecuteBankTransfer

3. After previous step SCA code was sent to the user, you should use it making the next request:

   grpcurl \
    -use-reflection \
    -H 'x-tpp-id: {TPP_ID}' \
    -H "x-request-id: `uuidgen`" \
    -H 'user-time-zone: Europe/London' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -d '{"client_operation_uuid": "{INDEMPONENCY_UUID}", "sca_confirmation": {"authentication_id": "{AUTHENTICATION_ID_FROM_ERROR}", "authentication_code": "{USER_SCA_CODE}"}, "amount": {"currency_code": "EUR", "units": "2"}, "description": "{DESCRIPTION}", "to_bank_recipient_id": "{BANK_RECIPIENT_ID}"}' \
    -key certificate.key \
    -cert certificate.pem\
    https://psd2-fallback.joompay.com \
    joompay.openbanking.OpenBankingPaymentInitiationService/ExecuteBankTransfer

Afterword

Current API allows to perform basic actions on a user account. However, we work for the more convenient and exhaustive API. Check this page for new versions. If you found an error, contact us via open-banking@joompay.com.