Sandbox Assembly

Introduction - detailed features of the sandbox

You can use the 89C3 API sandbox:

  • Via the 89c3 portal Try-It (see « Try-It console » use case) ;
  • Directly through your application : this mode is described hereafter.

 In sandbox assembly, there are two types of requests:

  • A first request to identify/authentifie the customer, then to retrieve the authorization token (see "Retrieve your access token") or to refresh this token (see "Refresh your access token" use case);
  • A second request to call "Information sur compte" API (see "Get accounts list", "Forward customer's consent", " Get accounting balances", "Get transactions history", "Get trusted beneficiaries list" and "Get PSU's identity").

In the sandbox assembly, your APP consuming the "Account Information" API will need to retrieve an access token via its authentication key from AS (Authentication Server).

Thus your application will be able to consume the methods GET /accounts, PUT /consents, GET /accounts/transactions, GET /accounts/balances, GET /trustedBeneficiaries and GET /endUserIdentity thanks to its access token.

API method calls can be chained: 

  • By executing the GET /accounts request you retrieve the account list at first;
  • Then, executing the PUT /consents request, you transmit customer's consents ;
  • Then, by executing the GET /accounts/{accountResourceId}/balances request, you recover accounting balance, passing in parameter "resourceId" of one of the accounts recovered from the result of the first request.
  • You can also recover transactions history by executing GET /accounts/{accountResourceId}/transactions request;
  • Then, by executing the GET /trustedbeneficiaries request, you retrieve the list of customer's trusted beneficiaries => these methods will not be available in 2020. 
  • Finally, by executing the GET /endUserIdentity request, you recovery the customer's identity => these methods  will be implemented with STET standard v1.4.2.17.

The data used in the tests are based on persona (see “Test data” use case). This will enable you to choose specific profiles according to the tests so as to better understand the results.

If necessary, a pagination of results will be made to facilitate readability and navigation links between different pages of results will be present (see the examples in the use cases "Forward customer's consent" and "Get transactions history"), which implies that the consuming application can handle this pagination correctly.

 

Prerequisites

You must declare your APP on 89c3 API portal (see "My apps" menu) and send us  :

  • Your organizationId ;
  • QWAC and QSEALC test certificates public key ;
  • Callback URI that will be called by ASPSP  ;
    • If the customer has authorized the recovery of its data by the AISP;
    • In case of refusal of consent by customer ;
    • If the kinematics below is interrupted (for example: timeout on the screens)

Please note that as a TPP, you must be accredited (or in the on-going accreditation process) by any european competent authority (ACPR in France) for this Account Information Service Provider role ("AISP").

 

Sequence steps to test access to the AISP API from your APP

  • First step : Ask for an access token thru redirection

This call allows you to trigger the identification of the customer in the Banque Populaire that holds its accounts, prerequisites for obtaining an access token for this bank. This is to ask the connected customer to give his contentment to access his data for 90 days.

The description of the feature is given in the use case "Get your access token".

NB: The customer can domicile its accounts in several banks of Groupe BPCE, you will need a different token to access each of our banks if the customer wants to aggregate accounts from each of them => this call and the following calls will be therefore to be repeated for each of the bank concerned.

In order to be able to query the right backend, in the customer journey, it is therefore necessary that you plan to ask the customer in advance on its (their) Banque Populaire (s) of attachment.

For access to the sandbox assembly, the entry point depends on the institution code: « www.<bankcode>.sandbox.api.89C3.com ».

The only Banques Populaires that can be used in sandbox assembly for this API are the following (bank code <bankcode> used in URLs) : 

Bank code Bank name Bank short name
13807 B.P Grand Ouest BPGO
13807 CMM Grand Ouest CMMGO

Redirection request to the login page:

GET https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/authorize

 Headers :

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params :

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

client_id:PSDFR-ACPR-13807

response_type:code

scope:AISP

Notes on parameters :

client_id : your agreement number as defined by your national competent authority. (PSDXX-YYYY-ZZZZZ)

redirect_uri : callback URL as declared in your APP

                       AND

to be forwarded to ASPSP for each sandbox and Go Live requests to be forwarded to ASPSP for each sandbox and Go Live requests 

 

  • Second step : Redirection to screens

Nominal kinematics of the sequences of identification and strong authentication screens:

cinématique globale AISP UK

Sequence of identification and strong authentication screens:

1) The customer is redirected to an identification screen offered by his bank and in which he will enter his remote banking identifier.

AISP 1 1 Identification

The remote banking identifier of the customer is to be entered (see "Test data" use case for the data sets of the banking institution), example for the persona "Marc" of the Banques Populaires :

AISP 1 2 Identification

NB: If the AISP provides the remote banking identifier of the customer in its request (field XXX), the following step is directly triggered : this possibility will be taken into account in the first half of 2020.

2) The customer is redirected to a first authentication screen proposed by its banking institution to validate its identity.

AISP 2 1 MireAuthentBP

The SMS code for authentication is to be entered (see "Test data" use case for the data sets of the banking institution), example for the persona "Marc" of the Banques Populaires :

AISP 2 2 MireAuthentBP

The kinematics of this step depends on the strong authentication method made available to the customer by the bank (SMS OTP, secur'pass, etc.).

It also depends on the equipment connected to the AISP APP used by the customer (PC or mobile / smartphone / tablet).

In some cases, a notification may be sent to the customer to activate its strong authentication means, and to complete this step.

 

Sequence of the identification and strong authentication screens when the remote bank identifier of the customer is transmitted in the request:

When the access identifier for the remote bank for the customer (field "XXX") is filled in, the call to the identification screen of the customer is not performed, cf. drawing below => this possibility will be available in the first half of 2020.

 

AISP kinematic with rmId transmitted 20190805

 

 

  • Third step : Get an access_token

This call allows AISP to recover the token to access data from the AISP registered callback URL in its consuming application.

Sample : https://bred.demoseo.turbosa.banquepopulaire.fr/Home/OAuth2Callback?code=NnZx1hqHY2CLkCFjiTwhJeflgNnCrB

If the customer has allowed you to retrieve data for a Banque Populaire, you will find in the response to the previous call, the one-time code that retrieves an access_token.

This access_token is valid for 1 hour and is a prerequisite for each access to one of the methods of the account information API. The description of the functionality and the fields of the request is described in the use case "Get your access token".

This token is accompanied by a refresh_token valid for 90 days that you must keep. When your access_token expires, you can request a new one by following the kinematics "Refresh your access_token" below.

After 90 days your refresh_token expires. To recover a new one, you need to follow again the kinematics "Get your access token" and go through a new step of strong authentication of the customer with the bank.

Request:

POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token

Headers :

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params :

redirect_uri:https://myAPP.fr/Home/OAuth2Callback

client_id:PSDFR-ACPR-13807

grant_type:authorization_code

code:NnZx1hqHY2CLkCFjiTwhJeflgNnCrB

Notes on parameters :

client_id : your agreement number as defined by your national competent authority. (PSDXX-YYYY-ZZZZZ)

Code : recovered in the callback URL.

redirect_uri : callback URL as declared in your APP

                       AND

to be forwarded to ASPSP for each sandbox and Go Live requests to be forwarded to ASPSP for each sandbox and Go Live requests 

!!! It is necessary that the redirect_uri is the same as for the GET / authorize request  !!!

Response : 

"access_token": "KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw",

"token_type": "Bearer", 

"expires_in": 3600, 

"scope": "aisp offline_access",  

"refresh_token": "KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa"

}

 

  • Fourth step : Consume the methods of the API

Get the list of the customer current accounts and delayed debit cards

This call allows you to list the accounts of the customer connected or not.

The description of the functionality and fields of the request are described in the use case "Get accounts list".

Example of a request to retrieve the list of accounts in sandbox assembly:

Request :

GET https://www.13807.sandbox.api.89C3.com/stet/psd2/v1/accounts

Headers :

Authorization:Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw

Signature : keyId=\"MZGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB\",algorithm=\"rsa-sha256\",headers=\"(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\",signature=\"LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\

X-request-id:id-1234567890111121 1

Psu-Ip-Address:192.168.0.1

Notes on parameters :

Authorization:Bearer => access_token

Psu-Ip-Address => allows to distinguish between the batch calls and the calls with the connected customer : this field is to feed for a connected customer.

Response : 200 OK

Headers :

X-request-id:id-1234567890111121 1

Notes on parameters :

X-request-id: transmitted as input

Body :

  {

  "_links": {
    "last": {
    },
    "self": {
    },
    "first": {
    }
  },
  "accounts": [
    {
      "cashAccountType": "CACC",
      "accountId": {
        "iban": "FR7613807008043001965409135"
      },
      "resourceId": "038-CPT30019654091",
      "product": "COMPTE COURANT",
      "_links": {},
      "usage": "ORGA",
      "psuStatus": "Account Holder",
      "name": "Tech-N Co",
      "bicFi": "CCBPFRPPNAN",
      "currency": "EUR",
      "details": "COMPTE COURANT"
    }
  ]
}

 (case of persona Tech-N Co - D0999993I0 for which no consent was given via the method PUT /consents)

{
  "_links": {
    "last": {
    },
    "self": {
    },
    "first": {
    }
  },
  "accounts": [
    {
      "cashAccountType": "CACC",
      "accountId": {
        "iban": "FR7613807008043001965405158"
      },
      "resourceId": "038-CPT30019654051",
      "product": "COMPTE CHEQUE",
      "balances": [
        {
          "balanceType": "VALU",
          "name": "Solde en Valeur",
          "balanceAmount": {
            "amount": "4321.95",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-04"
        },
        {
          "balanceType": "CLBD",
          "name": "Solde Comptable",
          "balanceAmount": {
            "amount": "4179.95",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-03"
        },
        {
          "balanceType": "OTHR",
          "name": "Solde TP",
          "balanceAmount": {
            "amount": "4348.95",
            "currency": "EUR"
          }
        }
      ],
      "_links": {
        "balances": {
          "templated": false,
        },
        "transactions": {
          "templated": false,
        }
      },
      "usage": "PRIV",
      "psuStatus": "Account Holder",
      "name": "Compte perso",
      "bicFi": "CCBPFRPPNAN",
      "currency": "EUR",
      "details": "COMPTE CHEQUE"
    },
    {
      "cashAccountType": "CACC",
      "accountId": {
        "iban": "FR7613807008043001965405255"
      },
      "resourceId": "038-CPT30019654052",
      "product": "COMPTE CHEQUE",
      "balances": [
        {
          "balanceType": "VALU",
          "name": "Solde en Valeur",
          "balanceAmount": {
            "amount": "459.56",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-04"
        },
        {
          "balanceType": "CLBD",
          "name": "Solde Comptable",
          "balanceAmount": {
            "amount": "459.56",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-03"
        },
        {
          "balanceType": "OTHR",
          "name": "Solde TP",
          "balanceAmount": {
            "amount": "459.56",
            "currency": "EUR"
          }
        }
      ],
      "_links": {
        "balances": {
          "templated": false,
        },
        "transactions": {
          "templated": false,
        }
      },
      "usage": "PRIV",
      "psuStatus": "Account Holder",
      "name": "Retrait et Cheques",
      "bicFi": "CCBPFRPPNAN",
      "currency": "EUR",
      "details": "COMPTE CHEQUE"
    },
    {
      "cashAccountType": "CACC",
      "accountId": {
        "iban": "FR7613807008043001965405352"
      },
      "resourceId": "038-CPT30019654053",
      "product": "COMPTE CHEQUE",
      "balances": [
        {
          "balanceType": "VALU",
          "name": "Solde en Valeur",
          "balanceAmount": {
            "amount": "2165.50",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-04"
        },
        {
          "balanceType": "CLBD",
          "name": "Solde Comptable",
          "balanceAmount": {
            "amount": "2165.50",
            "currency": "EUR"
          },
          "referenceDate": "2019-09-03"
        },
        {
          "balanceType": "OTHR",
          "name": "Solde TP",
          "balanceAmount": {
            "amount": "2165.50",
            "currency": "EUR"
          }
        }
      ],
      "_links": {
        "balances": {
          "templated": false,
        },
        "transactions": {
          "templated": false,
        }
      },
      "usage": "PRIV",
      "psuStatus": "Account Holder",
      "name": "Compte mensualités",
      "bicFi": "CCBPFRPPNAN",
      "currency": "EUR",
      "details": "COMPTE CHEQUE"
    }
  ],
  "connectedPsu": "MALLOW MARC"

(case of persona Marc - D0999990I0 for which a consent was already transmitted via the method PUT /consents)

 

Forward customer's consented accounts list for the balances consultation and/or transactions

Same principle of passage of the access token as in the paragraph above "Get the list of the customer current accounts and delayed debit cards".

The description of the functionality and fields of the request are described in the use case "Forward customer's consent".

Request :

PUT https://www.13807.sandbox.api.89C3.com/stet/psd2/v1/consents

Headers :

Authorization : Bearer KXZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoI0Kr2rSi1mSCFNehAs6iLw

Signature : keyId=\"MZGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB\",algorithm=\"rsa-sha256\",headers=\"(request-target) psu-ip-address psu-ip-port psu-http-method psu-date psu-user-agent psu-referer psu-accept psu-accept-charset psu-accept-encoding psu-accept-language digest\",signature=\"LbkxgICM48J6KdWNaF9qT7OWEorNlAwWNo6R+KkP7cP4TIGkk8wxcsGQXJ9ZnC+ZiA8mjL5S8WQyL41M7iPt+vJX4xh679gdGwmlKzn7E+ZtZ1I4qalRxcdLp4gBL7fll+C2lVBNJrViMJBezFK7AYVjnSWH7t1QxiMVg3CmoRM=\

X-request-id:id-1234567890111121 2

Psu-Ip-Address : 192.168.0.1 

Notes on parameters :

Authorization:Bearer => access_token

Psu-Ip-Address => allows to distinguish between the batch calls and the calls with the connected customer : this field is to feed for a connected customer.

Body (with an IBAN of the customer) :

{

  "balances": [
    {
      "iban": " FR7613807008043001965405158"
    }
  ],
  "transactions": [
    {
      "iban": " FR7613807008043001965405158"
    }
  ],
  "trustedBeneficiaries": true,
  "psuIdentity": true
}

Response :

               Headers :

X-request-id:id-1234567890111121 2

Notes on parameters :

X-request-id: transmitted as input

No body but a response code « 201 – Created » 

  

  • Get customer's account balances report or outstandings list of the linked delayed debit card

Same principle of passage of the access token as in the paragraph above "Get the list of the customer current accounts and delayed debit cards".

The description of the functionality, an example and fields of the request are described in the use case "Get accounting balance".

 

  • Obtenir les transactions d'un compte à vue ou les facturettes des cartes à débit différé adossées à ce dernier

Same principle of passage of the access token as in the paragraph above "Get the list of the customer current accounts and delayed debit cards".

The description of the functionality, an example and fields of the request are described in the use case "Get transactions history".

 

  • Obtenir la liste des bénéficiaires de confiance d'un PSU => ce service sera disponible au dernier trimestre 2019.

Same principle of passage of the access token as in the paragraph above "Get the list of the customer current accounts and delayed debit cards".

The description of the functionality, an example and fields of the request are described in the use case "Get trusted beneficiaries=> this feature  will be implemented with STET standard v1.4.2.17.

  

  • Get PSU's identity

Same principle of passage of the access token as in the paragraph above "Get the list of the customer current accounts and delayed debit cards".

The description of the functionality, an example and fields of the request are described in the use case "Obtenez l'identité du PSU" => this feature will not be available in 2020.

 

  • Refresh access_token with refresh_token 

Request :

POST https://www.13807.sandbox.api.89C3.com/stet/psd2/oauth/token

Headers :

Content-Type:application/x-www-form-urlencoded; charset=utf-8

Params :

client_id:PSDFR-ACPR-13807

grant_type:refresh_token

refresh_token:KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa

Notes on parameters :

client_id : your agreement number as defined by your national competent authority. (PSDXX-YYYY-ZZZZZ)

Response: 

"access_token": "4s2Bt3MRL7nlPUZcRTPe5Tjs0v8p7ZOXOyEKs1juYesj9pPaU7hXFA",

"token_type": "Bearer", 

"expires_in": 3600, 

"scope": "aisp offline_access",  

"refresh_token": "KUZyspFBZ1R6NqWQdmsZhfdo1nbjK7MoD0Kr2rSi1mSCFNehAs6iLa"

}