Introduction

Enfuce Financial Services works as a service provider for the customer listed below and is technically responsible for developer documentation, sandbox API's and live API's.

  • Rocker
  • ST1 Finance
Contact information of the support you can find on this page. This site provides developer documentation for Account Information Service (AIS) API.

All APIs with their respective parameters and responses are described in the API documentation (Found under Documentation in the navigation menu).

The APIs follow the specification defined by The Berlin Group NextGenPSD2. This implementation is based on RESTful services, and the responses are in JSON format. APIs also consume requests with bodies in the JSON format.

We have collected all the needed information for you to get connected with our APIs. For any questions please contact our support for further information and guidance.

Terminology

Abbreviation Term Definition
TPP Third-party Provider Within PSD2, Third Party Providers are either/both Payment Initiation Service Providers (PISPs) and/or Account Information Service Providers (AISPs)
PSU Payment Service User An individual or corporate entity who has one or more accounts with an ASPSP
PISP Payment Initiation Service Provider TPP providing Payment initiation Services
CBPII Card Based Payment Instrument Issuer 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 held with another payment service provider
AISP Account Information Service provider TPP providing Account Information Services
- Consent The process by which a PSU gives a TPP permission to approach their ASPSP in order that the TPP can be granted access to the PSU’s account to provide a service to the PSU. This must be explicit, informed and time-bound

Get Started

Sign up and Log in

Sign Up and/or Login to gain access to the playground. Navigate to the sandbox/live playground through the playground button that appears in the navigation menu.

Certificates

Sandbox

Create the needed sandbox certificate set by clicking the generate button found under the certificate tab in the playground. In case your Certificate set is lost or you want to reset them, you can always re-generate a new set that will replace the old ones by clicking the re-generate button.

Live

Upload your qualified certificates by clicking upload certificate button found under the certificate tab in the playground. The certificates must be in PEM format. Both the QWAC and QC eSeal need to be valid and signed by a Qualified Trust Service Provider (QTSP). When uploading the certificates you are also required to sign a challenge string, this is to prove that you are in possession of the private key of the QC eSeal. Once the certificates are uploaded they will be validated against your NCA. You will be notified by us on the sign-up email address within three working days if the certificates are valid and you have been granted access.

Create apps

Once the certificates are set up, applications can be created. To create an application, navigate to the apps tab in the Playground and click the create application button.

Connect to APIs

The available APIs are found under the APIS tab in the playground. To connect an API to an application, click the connect button on the API you want to connect. The connections are visible on the apps under the Apps tab, here you can also remove connections.

Develop your application

Check out our example flows below and the API Docs for guidance when developing your application.

If you have any questions about how to use the developer portal contact the support.

Example flows

  1. Request and access token from token endpoint https://prod.auth.enfuce.com/token with your OAuth2.0 client credentials and mutual TLS
  2. Use the access token returned in step 1 together with your API key and mutual TLS to create a consent towards endpoint https://sandbox.api.[rocker][st1].openbanking.enfuce.com/consent/v1/consents
  3. Get the PSU authorization by redirecting the user to the authorization endpoint https://sandbox.api.[rocker][st1].openbanking.enfuce.com/v1/authorizations?scope=AIS:{consentId}&response_type=code&redirect_uri={redirect_uri}&state={state_string}&response_mode=query&code_challenge={PKCE_challenge}=code_challenge_method=S256
  4. After successful PSU authorization the PSU will be redirected back to clients redirect_uri with the authorization_code as a query parameter
  5. Exchange the authorization code for an access token at the https://prod.auth.enfuce.com/token and mutual TLS
  6. Request account information using the access token from step 5 to query against the Accounts API.

Environments

Sandbox

The Sandbox is a testing facility intended for TPPs to testing out their implementations before going live. The following text data/accounts are available in the sandbox environment.

Customer ID MaskedPan Name
1345611 5243 78** **** 8693 MC_CARD
1345611 5243 66** **** 8694 MC_CARD

Live

Live and sandbox are separate APIs, accessing the Live APIs requires you to become a registered TPP and upload your qualified certificates to the service. The certificates are used to validate you as a registered TPP and are a mandatory requirement for accessing Live data. Qualified Website Authentication Certificate (QWAC) is used for securing the communication on transport level through mutual authentication. Qualified Certificates for eSeal (QC eSeal) is used for signing the request payload to ensure the contents have not been tampered with. You can upload your certificates in the Playground by navigating to the Live section. The certificates must be in PEM format. Both the QWAC and QC eSeal need to be valid and signed by a Qualified Trust Service Provider (QTSP). When uploading the certificates you are required to sign a challenge string, this is to prove that you are in possession of the private key of the QC eSeal.

Rate limitations

Rate limitations are applied in all environments, in the Sandbox environment we have the following limit:

  • 5 requests per second / 1000 per day

Versioning and API Lifecycle

When a new version is released, the previous version will be available for 6 months. The upcoming version will be available in the sandbox at least 3 months before release. The API version number is always shown in the URL:

https://sandbox.api.[rocker][st1].openbanking.enfuce.com/card-account/v1/card-accounts

Version 2 would have the following URL:

https://sandbox.api.[rocker][st1].openbanking.enfuce.com/card-account/v2/card-accounts

Good To Know

Authentication and Authorization

Our APIs use OAuth2 to authorize payments and access to account information. We use the "integrated OAuth2 approach" described in NextGenPSD2 XS2A Framework Implementation Guidelines 4.31.

To access an API, you will need to retrieve an access token. The required flow for acquiring the access token depends on whether the API acts on behalf of the end-user or not. APIs that act on behalf of the end-user requires the authorisation code flow to be used while APIs that act on their behalf use the client credentials grant.

Authorization Code Flow

Accessing account data and initiating payments requires authorization from the end-user. To do this you will have to construct an OAuth2 authorization request as depicted in section 13.1 of NextGenPSD2 XS2A Framework Implementation Guidelines 4.31 and redirect the end-user to it. The authorization request should contain the following parameters.

Parameter Description
response_type Should be set to 'code'.
client_id Set to the client id of your application.
scope
  • PIS: The scope is the reference to the payment resource in the form "PIS[paymentId]".
  • AIS: The scope is the reference to the consent resource for account access in the form "AIS:[consentId]".
  • PIIS: The scope is the reference to the consent resource for account access in the form "PIIS:[consentId]".
state A dynamical value set by the TPP and used to prevent XSRF attacks.
redirect_uri The redirect uri of your application.
code_challenge PKCE challenge according to cryptographic RFC 7636 (https://tools.ietf.org/html/rfc7636) used to prevent code injection attacks.
code_challenge_method Code verifier transformation method, Should be set to 'S265'.

Here is an example code snippet for the Pre-Request script to generate the authorization url.


                                    var CryptoJS = require("crypto-js");
                                    function base64URLEncode(word)
                                    {
                                        return word.toString(CryptoJS.enc.Base64)
                                        .replace(/\+/g, '-')
                                        .replace(/\//g, '_')
                                        .replace(/=/g, '');
                                    }
                                    function sha256(buffer) {
                                        return CryptoJS.SHA256(buffer);
                                    }
                                    var wordArray = CryptoJS.lib.WordArray.random(32);
                                    var verifier = base64URLEncode(wordArray)
                                    pm.globals.set("ais_ac_verifier", verifier);
                                    var challenge = base64URLEncode(sha256(verifier));
                                    var scope = "AIS:" + pm.globals.get("ais_consentId");
                                    var auth_endpoint = pm.variables.get("authorization_endpoint");
                                    var redirect_uri = encodeURIComponent(pm.variables.get("redirect_uri"));
                                    var client_id = pm.variables.get("client_id")

                                    var url = auth_endpoint + "?scope=" + scope + "&response_type=code&redirect_uri=" + redirect_uri +"&state=tiRLNLYw3IN6dI6_2Jh4qvJ5-tqh8SyWI50Ax0LZWYk&client_id="+ client_id + "&response_mode=query&code_challenge=" + challenge +"&code_challenge_method=S256"
                                

Authorization Endpoint

Redirect the end-user to the authorization endpoint when you need her consent to access an API.

Token Endpoint

Use the token endpoint to exchange authorisation codes or refresh tokens for access tokens and to retrieve access tokens using client credentials grant.

Proof Key for Code Exchange

As an additional security measure Proof Key for Code Exchange (PKCE) as described in [https://tools.ietf.org/html/rfc7636], is required. This mitigates the threat of having the authorization code intercepted. The technique involves the client first passing a hash of a secret in the authorization redirect, and then using the secret when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

Message Signing

All HTTP requests sent by a TPP must be digitally signed with a qualified certificate for electronic seals (QSEALC) as defined in draft-cavage-http-signatures-10 and XS2A Framework Implementation Guidelines version 1.3.4, chapter 121. A digital signature consists of the mandatory HTTP headers listed in the table below.

Header Description
TPP-Signature-Certificate This http-request header contains QSEALC in PEM-format without the enclosing "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" strings. This certificate must be the same certificate that was uploaded in in the developer portal.
Digest This header contains a hash of the message body as defined in RFC3230. If there is no message body, then the hash must be an empty bytelist. The only hash algorithms allowed are SHA-256 and SHA-512. Digest value consists of algorithm, '='-character and base64 encoded hash value. E.g. SHA-256 digest value for an empty message body: "SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=". The algorithm must match the algorithm used in the presented certificate.
Signature A Signature-header consists of multiple mandatory comma-separated parameters:
  • keyId is a string identifier for QSEALC included in the TPP-Signature-Certificate header, consisting of the certificate serial number and the distinguished name of the QSEALC issuer CA. It is formatted as: keyId="SN=XXX,CA=YYY", where XXX is the serial number of the QSEALC in hexadecimal coding and YYY is the url encoded distinguished name of the CA.
  • algorithm is the signature algorithm used, either rsa-sha256 or rsa-sha512. The algorithm must match with the algorithm used in the QSEALC.
  • headers is list of HTTP headers used in generating the signature. The list must be a quoted list of lowercased headers, separated by a single space. The list order defines the order of headers used in the signature calculation. The list must contain the following headers: digest, x-request-id. Optionally it can contain, if and only if header is present in the request: psu-id, psu-corporate-id, tpp-redirect-uri. No other headers are allowed.
  • signature is a base64 encoded digital signature. The signature is calculated by forming a canonicalised signing string using the headers list. The signing string is then signed with a private key using specified algorithm and is then base64-encoded. The signing string construction is specified in section 2.3 of draft-cavage-http-signatures-10.

Example Request

X-Request-ID:               12345
Content-Type:               application/json
Digest:                     SHA-256=mTyeWvzT1sQIX/Av5eZy2a06bzRddKYyQB7hJ7po/HQ=
TPP-Signature-Certificate:  MIIDqTCCApGgAwIBAgIJAOYqi7MJB8K6MA0GCSqGSIb3DQEBCwUAMF0xCzAJBgNVBAYTAkZJMQ4wDAYDVQQIDAVBbGFuZDESMBAGA1UEBwwJTWFyaWVoYW1uMQ8wDQYDVQQKDAZFbmZ1Y2UxGTAXBgNVBAMMEG9icC1sb2NhbGhvc3QtY2EwHhcNMTkwOTIzMDAwMDAwWhcNMjAwOTIyMDAwMDAwWjBNMR8wHQYDVQRhDBZQU0RGSS1GSUVORi1rUE9GSUh6cHZNMRQwEgYDVQQDDAtTYW5kYm94IFRQUDEUMBIGA1UECgwLU2FuZGJveCBUUFAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCbhfkHcAaitjodExFUtMNYjzeG17p7CEfaQ6rh+TJwqukthQXR5Q7E9Cb+h/bSkpqAc2A5kdnVnWhiVjyeu6tqlI6fYA3gsy6UOuiP+MWrc4Lj7BFgaqK1/e9febvcgrlSA15h2LRuUwdENdBzhCnTucEkOa66xh/GH4Yct6dD+HVAgyGDPx/Rsy0ycw1dxcOjuFHD5bhe1C3NmRSoAvd7g+b0Ywg0qz3IFHRhZuo3KpLQLY4pL7vTQv14hEywF6Uh/cQsvNGR9u+CDswTjpldd+9kkfDG4Zasc9RzvaH5MbOfrTbSBE3D0f5TadtUMeqCzObOdaMyidMLZkn5zOrTAgMBAAGjfDB6MHgGCCsGAQUFBwEDBGwwagYGBACBmCcCMGAwOTARBgcEAIGYJwEEDAZQU1BfSUMwEQYHBACBmCcBAwwGUFNQX0FJMBEGBwQAgZgnAQIMBlBTUF9QSQwZRW5mdWNlIEZpbmFuY2lhbCBTZXJ2aWNlcwwIRkktRklFTkYwDQYJKoZIhvcNAQELBQADggEBACRAgEoFWZFQnox6rLDMRZ2ES5B5fnI3fzHqtvWv5ilSmm0dGjoB8u7vLqIEZRp/+zM7BKTaeAqamEii6oc/e64SID6H9qR1jDVMjU5/VG+exJOu5GCfiLhkLttdP3b33fiOGJCV+I1gKwLzbIYSuq+XCUl1ExFJq25W7Yphw0D/W8y3s2VoTFZrJ5JOSaDEmd2TOPjCHvHZhWeYdo49wlSerGeoVXgjBw+AkSF2parAvJc8xcEi7R9A2KboQzCo6nLeAYKZVbh+6g76kA1bybg7z+RecyXtwkO/G1uYDmKsq+yvzBoDyJVP3+8p8QshdpN762WAUw4Z/HuvR2Lf0sA=
Signature:                  keyId="SN=00E62A8BB30907C2BA,CA=CN=some-ca",algorithm="rsa-sha256",headers="x-request-id digest",signature="MkPrFfsjt8Li1qfGZKVJ3JC23RF19ZOxNcYSPJ1fB4q4Ph1MRiFEiWe3I0h0MyCAUpQU1Cxzrz1mnnVqa+UREjJHPhtSvJaOfC8FTKB2xdnMv7P2VAGamOZvuFNY50amsdkGKkD//p5zvdPlGwg2/jg7TAWs7xXSSGfXyh2ubMqH+Vbojr5/RocVYFwTguic/3jSedFkj83enZsbpa02tzvZutP3bp+ZVkTMl3F4ArItZxFIA2sRy1ABZor5BYqbRm+V16lmWC5WvM4TkPzD3RSPZwMq47OJp6YC8QyKyZ2Sf8s9VjoF6Dvtq8Eqr+h95pf+ESuAnGN9LZGPXx2bdA=="
{
    "test:" true
}
Where the signing string is:
X-Request-ID:               12345
Digest:                     SHA-256=mTyeWvzT1sQIX/Av5eZy2a06bzRddKYyQB7hJ7po/HQ=
1NextGenPSD2 XS2A Framework – Implementation Guidelines