PSD2 API

Open Banking with PSD2

The revised Payment Services Directive (PSD2) requires banks to allow third party providers (TPPs) to access account and make payments on their customer’s behalf and with their consent. This regulation ensures that banks put into place the necessary systems to securely and reliably share their services and data with registered TPP. APIs are already widely used across the internet to share information and provide secure access to accounts and payment services.

Genome PSD2 API

Genome open API can be used for both account information (AISP) and payment services (PISP). Since our priority is to secure customer’s data and ensuring a smooth customer experience, as well as adhering to market standards, our PSD2 services are based on OAuth2.0 method. Our PSD2 API are free to use for all registered AISPs and PISPs. If you are a registered TPP and wish to use our API, please contact us at psd2@genome.eu

This API can be used to access the accounts IBAN of Genome customers. This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not an replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API.

Authentication

Genome API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

1. Acquire an access token, and optionally a refresh token
2. Use the access token to make authenticated requests

Strong Customer Authentication

We don’t grant any permissions to the access token until the owner of the account that your client wants to access has approved access. Your user will receive a sms or email notification after authenticating with their phone or email.

Acquire an access token

Acquiring an access token is a three-step process:

1. Redirect the user to Genome to authorise your app
2. Exchange the authorization code for an access token.

This access token doesn’t have any permissions until your user has approved access to their data.

Base URLs

We’ve included the Base URL for Production environment below.

Redirect the user to Genome

Send the user to Genome in a web browser, where they will log in and grant access to their account.

Strong Customer Authentication

In addition to authenticating with email or phone, the user will receive a OTP code to email or phone to confirm authentication with second factor.

Request Method

GET

Endpoint

Copy
/oauth2/authorize?client_id={client_id}&response_type=code&redirect_uri={uri}&state={random_string}

Response Body (Example)

Copy
Response example
1. User already authenticated response = 302 redirect to OAUTH2 approval page
2. Unauthorized HTTP 302 redirect to login page

Exchange the authorization code

When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Genome user, and is valid for 30 minutes.

Request Method

POST

Endpoint

Copy
/oauth2/token

Request Body (Example)

Copy
grant_type=authorization_code&code={code}&redirect_uri={uri}&client_id={client_id}

Response Body (Example)

Copy
{
    "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "{scope}"
}

Authenticating requests

All requests must be authenticated with an access token supplied in the Authorization header using the Bearer scheme. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.

Account Information Services API

The Account Information Services API lets authorised Account Information Service Providers (AISP) access balances, transactions, and more for our customers.

Base URLs

We’ve included the Base URL for Production environment below.

Create a consent

Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request.

Request Method

POST

Endpoint

Copy
/psd2/v1/consents

Request Body (Example)

Copy
{
    "access": {
        "accounts": [{
            "currency": "EUR",
            "iban": "{{iban_none}}"
        }],
        "balances": [{
            "currency": "EUR",
            "iban": "{{iban_none}}"
        }],
        "transactions": [{
            "currency": "EUR",
            "iban": "{{iban_none}}"
        }]
    },
    "combinedServiceIndicator": false,
    "frequencyPerDay": 400,
    "recurringIndicator": true,
    "validUntil": "2021-12-31"
}

Response Body (Example)

Copy
{
    "consentStatus": "received",
    "consentId": "7uhkasdtaydfem43",
    "_links": {
        "self": {
            "href": "/psd2/v1/consents/7uhkasdtaydfem43"
        },
        "startAuthorisation": {
            "href": "/psd2/v1/consents/7uhkasdtaydfem43/authorisations"
        },
        "status": {
            "href": "/psd2/v1/consents/7uhkasdtaydfem43/status"
        }
    },
    "psuMessage": "OTP Password required"
}

Start the authorisation process for a consent

Start the authorisation process for a consent

Request Method

POST

Endpoint

Copy
/psd2/v1/consents/{consent_id}/authorisations

Request Body (Example)

Copy
Request body is empty

Response Body (Example)

Copy
{
    "scaStatus": "received",
    "authorisationId": "hc7aascfcncf4dhk",
    "_links": {
        "scaRedirect": {
            "href": "/psd2/ais/hc7aascfcncf4dhk/7uhkasdtaydfem43"
        }
    }
}

Get a consent

Returns the content of an account information consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.

Request Method

GET

Endpoint

Copy
/psd2/v1/consents/{consent_id}

Response Body (Example)

Copy
{
    "access": {
        "accounts": [{
            "iban": {
                "iban": "1231231231231231312"
            },
            "currency": "EUR"
        }],
        "balances": [],
        "transactions": [],
        "availableAccounts": "allAccounts"
    },
    "recurringIndicator": true,
    "validUntil": "+53743-10-28",
    "frequencyPerDay": 1,
    "lastActionDate": "+51645-08-30",
    "consentStatus": "received"
}

Get a consent status

Can check the status of an account information consent resource.

Request Method

GET

Endpoint

Copy
/psd2/v1/consents/{consent_id}/status

Response Body (Example)

Copy
{
    "consentStatus": "received"
}

Get the SCA status of the consent authorization

Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request. Side Effects When this Consent Request is a request where the "recurringIndicator" equals true, and if it exists already a former consent for recurring access on account information for the addressed PSU submitted by this TPP, then the former consent automatically expires as soon as the new consent request is authorised by the PSU.

Request Method

GET

Endpoint

Copy
/psd2/v1/consents/{consent_id}/authorisations/{authorisation_id}

Response Body (Example)

Copy
{
    "scaStatus": "psuAuthenticated"
}

Delete a consent

Delete an account information consent object.

Request Method

DELETE

Endpoint

Copy
/psd2/v1/consents/{consent_id}

Response Body (Example)

Copy
Response body is empty

Get accounts list

Reads a list of bank accounts, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed list of accounts depends then on the PSU ID and the stored consent addressed by consentId, respectively the OAuth2 access token.

Request Method

GET

Endpoint

Copy
/psd2/v1/accounts

Response Body (Example)

Copy
{
    "accounts": [{
        "resourceId": "1051011800072884134",
        "iban": "LT561010038693502211",
        "currency": "EUR",
        "cashAccountType": "OTHR",
        "status": "enabled",
        "bic": "MNNELT21XXX",
        "usage": "PRIV",
        "balances": [{
            "balanceAmount": {
                "currency": "EUR",
                "amount": "9.0"
            },
            "balanceType": "authorised",
            "lastChangeDateTime": "2019-09-10T11:22:11.470751Z",
            "referenceDate": "2019-09-10"
        }],
        "_links": {
            "transactions": {
                "href": "psd2/v1/accounts/1051097800072884134/transactions"
            }
        }
    }]
}

Get account balances list

Reads account data from a given account addressed by "account-id".

Request Method

GET

Endpoint

Copy
/psd2/v1/accounts/{account_id}/balances

Response Body (Example)

Copy
{
    "account": {
        "iban": "LT551010000034206191",
        "currency": "EUR"
    },
    "balances": [{
        "balanceAmount": {
            "currency": "EUR",
            "amount": "10"
        },
        "balanceType": "authorised",
        "lastChangeDateTime": "2019-09-12T14:06:23.596594Z",
        "referenceDate": "2019-09-12"
    }]
}

Get account transactions list

Reads account transactions list from a given account addressed by "account-id".

Request Method

GET

Endpoint

Copy
/psd2/v1/accounts/{account_id}/transactions

Response Body (Example)

Copy
{
    "account": {
        "iban": "LT551010000034206191",
        "currency": "EUR"
    },
    "transactions": {
        "pending": [{
            "transactionId": "335313",
            "creditorId": "1041097800072641102",
            "valueDate": "2019-09-12",
            "transactionAmount": {
                "currency": "EUR",
                "amount": "1.0"
            },
            "currencyExchange": [],
            "creditorName": "Sender",
            "creditorAccount": {
                "currency": "EUR"
            },
            "ultimateCreditor": "",
            "debtorName": "Receiver",
            "debtorAccount": {
                "currency": "EUR"
            },
            "remittanceInformationUnstructured": "Ref. Number WBG-1222",
            "remittanceInformationStructured": ""
        }]
    }
 }

Read Transaction Details

Reads transaction details from a given transaction addressed by “resourceId” on a given account addressed by "account-id". This call is only available on transactions as reported in a JSON format.

Request Method

GET

Endpoint

Copy
/psd2/v1/accounts/{account_id}/transactions/{transaction_id}

Payment Initiation Services API

The Payment Initiation Services API lets authorised Payment Initiation Service Providers (PISP) make single payments from the IBAN accounts of our customers.

Base URLs

We’ve included the Base URL for Production environment below.

Payment Initiation

Creates a payment initiation request at the ASPSP.

Request Method

POST

Endpoint

Copy
/psd2/v1/payments/sepa-credit-transfers

Request Body (Example)

Copy
{
    "endToEndIdentification": "WBG-123456789",
    "debtorAccount": {
        "currency": "EUR",
        "iban": "LT651010555095422166"
    },
    "instructedAmount": {
        "currency": "EUR",
        "amount": "1.00"
    },
    "creditorAccount": {
        "currency": "EUR",
        "iban": "LT553100016548456548"
    },
    "creditorAgent": "AAAADEBBXXX",
    "creditorName": "WBG",
    "creditorAddress": {
        "buildingNumber": "56",
        "city": "Nürnberg",
        "country": "DE",
        "postalCode": "90543",
        "street": "WBG Straße"
    },
    "remittanceInformationUnstructured": "Ref. Number WBG-1222"
}

Response Body (Example)

Copy
{
    "transactionStatus": "RCVD",
    "paymentId": "fs37ex3ddjdfcffz",
    "transactionFeeIndicator": false,
    "challengeData": {
        "otpMaxLength": 6,
        "otpFormat": "characters"
    },
    "_links": {
        "scaStatus": {
            "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/authorisations/azfj3uck7t84fxce"
        },
        "scaRedirect": {
            "href": "psd2/v1/pis/azfj3uck7t84fxce/fs37ex3ddjdfcffz"
        },
        "self": {
            "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz"
        },
        "status": {
            "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/status"
        }
    }
}

Get Payment Information

Returns the content of a payment object

Request Method

GET

Endpoint

Copy
/psd2/v1/payments/sepa-credit-transfers/{payment_id}

Response Body (Example)

Copy
{
    "endToEndIdentification": "WBG-123456789",
    "debtorAccount": {
        "iban": "LT401010000000007777",
        "currency": "EUR"
    },
    "instructedAmount": {
        "currency": "EUR",
        "amount": "1"
    },
    "creditorAccount": {
        "iban": "LT313570012345678933",
        "currency": "EUR"
    },
    "creditorName": "WBG",
    "creditorAddress": {
        "street": "WBG Straße",
        "buildingNumber": "56",
        "city": "Nürnberg",
        "postalCode": "90543",
        "country": "WBG Straße"
    },
    "transactionStatus": "RCVD"
}

Read the SCA Status of the payment authorisation

This method returns the SCA status of a payment initiation's authorisation sub-resource.

Request Method

GET

Endpoint

Copy
/psd2/v1/payments/sepa-credit-transfers/{payment_id}/authorisations/{authorisation_id}

Response Body (Example)

Copy
{
    "scaStatus": "started"
}

Payment initiation status request

Check the transaction status of a payment initiation.

Request Method

GET

Endpoint

Copy
/psd2/v1/payments/sepa-credit-transfers/{payment_id}/status

Response Body (Example)

Copy
{
    "transactionStatus": "ACCC"
}

Confirmation of Funds API

The Confirmation of Funds API lets authorised Card Based Payment Instrument Issuers check that Genome customers have enough money for a purchase.

Base URLs

We’ve included the Base URL for Production environment below.

Confirmation of Funds Request

Creates a confirmation of funds request at the ASPSP.

Request Method

POST

Endpoint

Copy
/psd2/v1/funds-confirmations

Request Body (Example)

Copy
{
    "account": {
        "iban": "LT651010019095493166"
    },
    "instructedAmount": {
        "amount": "48.01",
        "currency": "EUR"
    },
    "payee": "Check24"
}

Response Body (Example)

Copy
{
    "fundsAvailable": false
}