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 by calling the payment initiation API of the 89c3-API platform (sandbox assembly).
In sandbox assembly, there are two types of requests:
- A first request to retrieve the authorization token (see "Retrieve your access token") ;
- A second one to send a request to the payment initiation API (see "Send a single payment initiation request" and "Retrieve the statuts of a payment request initiation").
Your application must request the AS (authentication server) to get an access token via its authentication key.
This access token will enable your application to submit the POST /payment-requests and the GET /payment-requests methods of the payment Initiation API.
You can perform a series of requests :
- Submit POST /payment-requests method to initiate a payment
- Then, submit GET /payment-requests/{paymentRequestResourceId} with the parameter paymentRequestResourceId got in response of the first request, to get the payment status
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.
The list of current available bank institutions for sandbox assembly for this API is detailed below ("bkcode" parameter used in URLs) :
Bank code | Bank name | Bank short name |
13807 | B.P Grand Ouest | BPGO |
13807 | CMM Grand Ouest | CMMGO |
17515 | Caisse d'Epargne Ile De France | CEIDF |
12579 | Banque BCP | BBCP |
➤ Sequence stets to test access to the PISP API from your APP
Prerequisites
You must declare your APP on 89c3 API portal (see "My apps" menu) and send us your QWAC and QSEALC test certificates public keys so we can :
- Declare your APP as a consumer application of the API ;
- Integrate your QWAC and QSEALC test certificates public keys in our infrastructure ;
- Retrieve and control your organizationId and your "PISP" role in our TPP registry.
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 Payment Initiation Service Provider role ("PISP").
STEP #1 : Retrieve your access token
This call allows you to retrieve the access token from the institution's authentication server, which is a prerequisite for each access to one of the payment initiation API methods. The description of this feature and the fields of the request are given in the "Retrieve your access token".
The entry point for accessing to the sandbox assembly is : www.<bkcode>.sandbox.api.89c3.com
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-12345
grant_type : client_credentials
scope : pisp
Notes on parameters :
<bkcode> => bank code available in this environment :
13807 (Banque Populaire Grand Ouest) ;
17515 (Caisse d'Epargne Ile de France).
client_id : your agreement number as defined by your national competent authority. (PSDXX-YYYY-ZZZZZ)
grant_type => unchangeable = "client_credentials"
Response :
{
"access_token" : "firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz",
"token_type" : "Bearer",
"expires_in" : "3600",
"scope" : "pisp"
}
Notes on parameters :
access_token => tokenCredential to transmit in the header authorization of payment initiation API requests, next to Bearer XX.
expires_in => period of validity of the token in seconds
STEP #2 : Send a payment initiation request
This call method post /payment-requests/ allows you to initiate a payment by asking the connected customer to give his consent for the payment.
The description of this feature and the fields of the request is given in the "Send a single payment request initiation" use case.
Reminder: the authentication method supported by the bank is the REDIRECT authentication approach => the sequence of PSU identification and strong authentication (SCA) screens described below correspond to this authentication mode.
The entry point for accessing to the sandbox assembly is identical : www.<bankcode>.sandbox.api.89c3.com
Request :
POST https://www.13807.sandbox.api.89C3.com/stet/psd2/v1.4.2/payment-requests
Headers :
Authorization: Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type: application/json
Signature: keyId=\"https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\", 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 : MyXrequestId123
Body :
{ "paymentInformationId" : "MyPmtInfld123", "creationDateTime" : "2019-07-22T09:25:22.527+02:00", "numberOfTransactions" : 1, "debtorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "B.P Grand Ouest", "postalAddress" : { "country" : "FR", "addressLine" : [ "15 Boulevard de la Boutière", "CS 26858 35768 SAINT GREGOIRE CEDEX" ] } }, "initiatingParty" : { "name" : "MyPispName", "postalAddress" : { "country" : "FR", "addressLine" : [ "5 avenue Anatole France ", "75007 PARIS" ] }, "organisationId" : { "identification" : "12FR5", "schemeName" : "COID", "issuer" : "ACPR" } }, "paymentTypeInformation" : { "serviceLevel" : "SEPA", "categoryPurpose" : "DVPM" }, "debtor" : { "name" : "Marc ", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 rue de la coupe du monde", "94512 Charenton-le-Pont" ] }, "privateId" : { "identification" : "D0999990I0", "schemeName" : "BANK", "issuer" : "BICXYYTT512" } }, "debtorAccount" : { "iban" : "FR7613807008043001965405255" }, "beneficiary" : { "creditor" : { "name" : "myMerchant", "postalAddress" : { "country" : "FR", "addressLine" : [ "Place Charles de Gaulle", "75008 PARIS" ] }, "organisationId" : { "identification" : "852126790", "schemeName" : "BANK", "issuer" : "FR" } }, "creditorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "B.P Grand Ouest", "postalAddress" : { "country" : "FR", "addressLine" : [ "15 Boulevard de la Boutière", "CS 26858 35768 SAINT GREGOIRE CEDEX" ] } }, "creditorAccount" : { "iban" : "FR7613807008043001965406128" } }, "purpose" : "COMC", "chargeBearer" : "SLEV", "requestedExecutionDate" : "2019-07-23T13:25:22.527+04:00", "creditTransferTransaction" : [ { "paymentId" : { "instructionId" : "MyInstrId123", "endToEndId" : "MyEndToEndId123" }, "instructedAmount" : { "currency" : "EUR", "amount" : "327.12" }, "remittanceInformation" : [ "MyRemittanceInformation123" ] } ], "supplementaryData" : { "acceptedAuthenticationApproach" : [ "REDIRECT" ], "scaHint" : "scaExemption", "successfulReportUrl" : "https://extension.bpce.fr/calback.aspx&state=OK_12345&code_challenge_method=256&code_challenge=ABCD" } } |
Notes on parameters :
Authorization : Bearer => access_token recovered for the tokenCredential
Following data must be unique, otherwise the request is rejected because of duplicate (the replay is not allowed):
- paymentInformationId ;
- instructionId ;
- endToEndId ;
- x-request-id.
debtor/privateId/identification => customer remote banking identifier : when filled, the identification screen of the customer is not displayed.
debtorAccount => customer's IBAN : when it is filled, the only account selectable for the customer is the one that corresponds to this IBAN.
The implemented features may differ between the Banques Populaires and the Caisses d'Epargne (see "Send a single payment initiation" use case).
Response :
{
"appliedAuthenticationApproach" : "REDIRECT",
"_links" : {
"consentApproval" : {
"href" : "https://www.13807.sandbox.api.89c3.com/89C3api/accreditation/v1/identificationPisp?paymentRequestResourceId=0000000a22-156688979900016807956016&nonce=s7m9KD6UerBT1F5gPL3m",
"templated" : true
}
}
}
Headers :
X-Request-ID : MyXrequestId123
Status code : 201 OK
Notes on parameters :
paymentRequestResourceId => identifier to pass to the GET /payment-requests request to recover the status of the payment initiation request.
appliedAuthenticationApproach" = "REDIRECT" => only allowed value
href => URL of the redirection page to the identification and authentication screens of the banking institution
nonce => technical anti-replay
currency => recovered from the body given as input
successfulReportUrl => recovered from the body given as input
unsuccessfulReportUrl => recovered from the body given as input
iban => recovered from the body given as input
creditorName => recovered from the body given as input
X-Request-ID => transmitted as input
STEP #3: Nominal sequence of PSU identification & SCA
Sequence of identification and strong authentication screens:
Using the URI returned in consentApproval, it is possible to play the sequence of screens.
1) The PSU is redirected to an identification screen presented by his ASPSP (redirection mode) in which he will enter his remote banking identifier.
Warning : only one call to this screen can be made
=> the "nonce" parameter in the URL that gives access to this screen can only be used once (any second call with this nonce will rejected)
=> if necessary, a new call to PaymentRequests is required to get a new token
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 :
Note: If the PISP provides the remote banking identifier of the customer in its request (field "debtor/privateId/identification"), the following step is directly triggered.
For Caisses d'Epargne, if the customer is a professional or a corporate, he will have to enter is user number in addition to his remote banking identifier.
2) The customer is redirected to a first authentication screen proposed by its ASPSP in order to validate his/her identity:
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:
This sequence depends on the strong authentication method proposed to the customer by the bank (SMS OTP, soft token, etc...).
It also depends on the equipment connected to the PISP APP used by the customer (PC or mobile / smartphone / tablet).
3) The customer is redirected to a screen where he will have to select its account to be debited.
Example for the persona "Marc" of the Banques Populaires who has 4 accounts, three of which are eligible for DSP2 payment initiations (see "Test data" use case for the datasets of the banking institution):
IMPORTANT NOTE : If the PISP provides the IBAN of the customer to be debited in its request (field "debtorAccount"), only the corresponding account will be selectable and proposed to the customer : example below for the persona Tech'n Co of the Banques Populaires.
Note: If the customer does not have an account, the request for payment initiation will not succeed and the customer will be redirected to your APP. Example for the persona "Thomas" of the Banques Populaires.
4) The customer selects and validates the account to be debited :
5) The customer is redirected to a second strong authentication screen proposed by his banking institution to validate his payment (dynamic linking).
Screens are identical to the strong authentication screen of step 2) to validate the customer's identity.
The final decision whether or not to apply an authentication exemption is still at the discretion of the ASPSP as described in article 2 of the RTS of the DSP2. So far, exemptions are not possible for the SCA step to validate the payments.
6) The PSU is redirected to a confirmation screen of the transaction proposed by its ASPSP.
Note: when the customer does not validate the payment initiation (or in the event of a timeout on the account selection page for example) the customer is redirected to the next page :
The customer is redirected to the PISP APP which provides in its first initiation request one or two call back URLs:
The first (successfulReportUrl) will be called by the banking institution in case the payment initiation request is processed and if the customer has given its consent for the payment.
A "code" parameter is added to this successfulReportUrl which is mandated to request the access token for the /o-confirmation method :
Example : https://<votre SuccessfulReportUrl>?code=GbmTn1ZZ76bibgvCRLxD4lNp8wMzkd
The second one (unsuccessfulReportUrl) will be used by the bank in case of refusal of consent or if the validation kinematics of the payment initiation is interrupted at one of its stages (example: timeout on the identification screen, on the account selection screen to be debited or the strong authentication screens). This second URL is optional : the first URL call back (successfulReportUrl) will be used if the second is not filled.
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 (debtor/privateId/identification field in the payment initiation request) is filled in, the call to the identification screen of the customer is not performed, cf. drawing below :
(*) for Caisses d'Epargne, Banque BCP, Crédit Coopératif et BTP Banque PSU segments PRO & ENT : we require having the PSU subscription number separated fomr the usage number by a "-".
STEP #4 : Retrieve the Status of a payment initiation request (only available in live production)
This method get /payment-requests/{paymentRequestResourceId} allows you to retrieve all the payment initiation data enriched with the resource identifiers and the status of the payment initiation it contains.
The description of this feature and fields of the request is described in the use case "Retrieve the status of a payment request initiation". The data is accessible for 35 days.
For accessing to the sandbox assembly, the entry point is identical :
Request :
Headers :
Authorization: Bearer firstAccessToken_ABCXdBobTpdwRRaYy2H3w7pP5Xe61e1R9rwxMuhk7G0fULg8x6kJHz
Content-Type: application/json
Signature: keyId=\"https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\", 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 : MyXrequestId123
Notes on parameters :
Authorization:Bearer => access_token retrieved for tokenCredential.
x-request-id => must be the same as for the payment initiation request.
The paymentRequestResourceId is retrieved in response to the payment initiation request, when the payment initiation has been processed and the PSU has given its consent for the payment.
Response :
{ "paymentRequest" : { "resourceId" : "0000000a22-146329369000016907660677", "paymentInformationId" : "MyPmtInfld123", "creationDateTime" : "2019-07-22T09:25:22.527+02:00", "numberOfTransactions" : 1, "debtorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "B.P Grand Ouest", "postalAddress" : { "country" : "FR", "addressLine" : [ "15 Boulevard de la Boutière", "CS 26858 35768 SAINT GREGOIRE CEDEX" ] } }, "initiatingParty" : { "name" : "MyPispName", "postalAddress" : { "country" : "FR", "addressLine" : [ "5 avenue Anatole France ", "75007 PARIS" ] }, "organisationId" : { "identification" : "12FR5", "schemeName" : "COID", "issuer" : "ACPR" } }, "paymentTypeInformation" : { "serviceLevel" : "SEPA", "categoryPurpose" : "DVPM" }, "debtor" : { "name" : "Marc ", "postalAddress": { "country" : "FR", "addressLine" : [ "512 rue de la coupe du monde", "94512 Charenton-le-Pont" ] }, "privateId" : { "identification" : "D0999990I0", "schemeName" : "BANK", "issuer" : "BICXYYTT512" } }, "debtorAccount" : { "iban" : "FR7613807008043001965405255" }, "beneficiary" : { "creditorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "B.P Grand Ouest", "postalAddress" : { "country" : "FR", "addressLine" : [ "15 Boulevard de la Boutière", "CS 26858 35768 SAINT GREGOIRE CEDEX" ] } }, "creditor" : { "name" : "myMerchant", "postalAddress" : { "country" : "FR", "addressLine": [ "Place Charles de Gaulle", "75008 PARIS" ] }, "organisationId" : { "identification" : "852126790", "schemeName" : "BANK", "issuer" : "FR" } }, "creditorAccount" : { "iban" : "FR7613807008043001965406128" } }, "purpose" : "COMC", "chargeBearer" : "SLEV", "paymentInformationStatus" : "PDNG", "statusReasonInformation" : null, "fundsAvailability" : null, "booking": null, "requestedExecutionDate" : "2019-07-23T13:25:22.527+04:00", "creditTransferTransaction" : [ { "paymentId" : { "resourceId" : "0000000a22-146329369000016907660677", "instructionId" : "MyInstrId123", "endToEndId" : "MyEndToEndId123" }, "instructedAmount" : { "currency" : "EUR", "amount" : "327.12" }, "remittanceInformation" : [ "MyRemittanceInformation123" ], "transactionStatus" : "PDNG" } ], "supplementaryData" : { "appliedAuthenticationApproach" : "REDIRECT", "scaHint" : "scaExemption", "successfulReportUrl" : "https://extension.bpce.fr/calback.aspx&state=OK-12345&code_challenge_method=256&code_challenge=ABCD" } } } |
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK
Notes on parameters :
resourceId => equals to paymentRequestResourceId
paymentInformationStatus => gives payment initiation status
transactionStatus => gives transaction status
X-Request-ID => transmitted as input
STEP #5 : Confirm payment initiation status (only available in live production, NOT in sandbox)
This mandated method POST /payment-requests/{paymentRequestResourceId}/o-confirmation allow to confirm a payment status for security reasons.
Please note that the method POST /payment-requests/{paymentRequestResourceId}/confirmation is not implemented.
The TPP needs to request a specific access token :
Request :
POST https://www.13807.live.api.89C3.com/stet/psd2/oauth/token
Headers :
Content-Type : application/x-www-form-urlencoded; charset=utf-8
Body :
grant_type : authorization_code
client_id : the one generated if the TPP is enrolled using our API Register
code : code extracted from previous call in the successful URL at the end of STEP #3
code_verifier : depends on your PKCE data
redirect_uri: :predeclared uri communicated to ASPSP in the enrolment process
Response :
{
"access_token" : "secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs",
"token_type" : "Bearer",
"expires_in" : "3600",
"refresh_token": "1ji8KA9RJ5eXeJV1xKSDj1WDp8wwg3pRgDO2j0WhtbMsWz",
"scope" : "pisp",
"state": "OK-12345"
}
Notes :
access_token => tokenCredential to be included in the next method Authorization field after the Bearer
It is now possible to use the confirmation method (in live production environment only)
POST https://www.13807.live.api.89C3.com/stet/psd2/v1.4.2/payment-requests/0000000a22-156688979900016807956016/o-confirmation
Headers :
Authorization: Bearer secondAccessToken_NBVcxwwmLkjhgfdspoie00OIuyTRPFs
Content-Type: application/json
Signature: keyId=\"https://<www.myUrlPath.to>/myQsealCertificate_<footprint-sha256>\", 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 : MyXrequestId123
Body :
{ } |
Notes :
Authorization : Bearer => access_token extracted in the response of the previous POST /token method (the second one)
{paymentRequestResourceId} : same id used in previous GET /payments-requests
Response :
{ "paymentRequest" : { "resourceId" : "0000000a22-156688979900016807956016", "paymentInformationId" : "MyPmtInfld123", "creationDateTime" : "2021-09-05T09:25:22.527+02:00", "numberOfTransactions" : 1, "debtorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "Cpy Name", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 rue De Gaulle", "85000 LRSY" ] } }, "initiatingParty" : { "name" : "Pisp Name", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 rue Reaumur", "75512 PARIS" ] }, "organisationId" : { "identification" : "12FR5", "schemeName" : "COID", "issuer" : "ACPR" } }, "paymentTypeInformation" : { "serviceLevel" : "SEPA", "categoryPurpose" : "DVPM" }, "debtor" : { "name" : "Customer Name", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 rue Leclerc", "94512 Charenton-le-Pont" ] }, "privateId" : { "identification" : "D0999990I0", "schemeName" : "BANK", "issuer" : "BICXYYTT512" } }, "debtorAccount" : { "iban" : "FR7613807000243021933556300" }, "beneficiary" : { "creditorAgent" : { "bicFi" : "CCBPFRPP512", "name" : "Creditor Name", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 rue de la primaube", "12512 RODEZ" ] } }, "creditor" : { "name" : "Amazon SA", "postalAddress" : { "country" : "FR", "addressLine" : [ "512 avenue Maupassant", "75512 PARIS" ] }, "organisationId" : { "identification" : "852126790", "schemeName" : "BANK", "issuer" : "FR" } }, "creditorAccount" : { "iban" : "FR7613825002000400000541718" } }, "purpose" : "COMC", "chargeBearer" : "SLEV", "paymentInformationStatus" : "PDNG", "statusReasonInformation" : null, "fundsAvailability" : null, "booking" : null, "requestedExecutionDate" : "2021-09-06T14:10:10.109+01:00", "creditTransferTransaction" : [ { "paymentId" : { "resourceId" : "0000000a22-146329369000016907660677", "instructionId" : "instructionId 1630919339", "endToEndId" : "endToEndId 1630919339" }, "instructedAmount" : { "currency" : "EUR", "amount" : "2.41" }, "remittanceInformation": { "unstructured": [ "remittanceInformation01" ] }, "transactionStatus" : "PDNG" } ], "supplementaryData" : { "appliedAuthenticationApproach" : "REDIRECT", "scaHint" : "scaExemption", "successfulReportUrl" : "https://extension.bpce.fr/calback.aspx&state=OK-12345&code_challenge_method=256&code_challenge=ABCD" } } } |
Headers :
X-Request-ID : MyXrequestId123
Status code : 200 OK