1. INTRO

The following guide is meant to introduce the prospect developer to the MoneyGate Open Banking Sandbox APIs environment including scenarios where the endpoints as AIS,PIS and PIIS TPPs can be tested. This guide includes two sample scenarios intended to give an overview of the Open APIs functionality and help implement your own custom scenarios.

2. SETUP

2.1 Get started with Postman

Postman is perhaps the most popular helper application to test APIs. Using Postman is of course not mandatory, but if you opt to use it you can take advantage of our own ready built collection for testing our APIs.

Please visit https://www.getpostman.com/ to download and install Postman according to the provided instructions.Once you have finished with the installation, you are ready to download and import our Open API collections that will enable you to test the Sandbox APIs with minimum effort.

Please download the Postman Collections files from here

The files included in the archive you downloaded include:

  1. Open API calls collection, organized in categories for PISP/AISP/PIISP as well as 2 pre-configured scenarios that will be covered in Section 3

  2. Environment variables, so that will save you time in copying/pasting parameter values across calls and potentially enable the smooth transition to the Production API.

Please follow the steps bellow to import the files to your Postman workspace:

  1. Select “Import” at the top left corner in Postman. Click “Choose files” and select all the files that you downloaded and extracted previously.

  2. After your confirmation, you should be able to see the Collection to the left side of your postman, and the environment variables at the topright corner as displayed bellow

Picture
Picture

                                                                                                                                                                                                                                                                                                                             Now you are ready to make some API calls and test the included scenarios!

2.2 Developer Sign-Up and Product Subscription

In order to use the MoneyGate Open APIs you need to register an account at the Developer Portal

MoneyGate Developer Portal: https://developers.moneygate.com

  1. Select “Login” in the Developer portal. If you don’t have an account yet, select “Create an account”

Picture

       2.Fill in the application form and validate your account via the confirmation mail sent to your email address

       3.Once logged in, navigate to the “Products” page. select the product you wish to subscribe to and click “Add Subscription

Picture Picture

4.Enter a name for your subscription and click “Subscribe”.

Picture

5.From the top right corner in the Developer portal, navigate to your user profile where you can see your current subscriptions to the various API products. Copy the “Primary key” since you will need to attach it later to your postman invocations.

Picture

6.Navigate to the “APIs” page and select the API that you wish to test. in the API documentation that you will be landed you will find all essential documentation for the selected API as well as the option to “Try it” via the portal. For the purposes of this guide, in the sections to follow, we will test via Postman instead of the Portal's "Try it" capability.

Picture

3. API USAGE SCENARIOS

3.1 How to use Postman environment variables for your invocations

Postman environment variables for your invocations

Postman environment variables allow you to set them once and use them in every subsequent call. As you can see in a sample request below, the parameters within {{brackets}} are included in the environment variables.

  1. Select “Manage Environments” (the gearbox) on the topright corner.

  2. Select the “Sandbox Moneygate" environment as active.

In order to finish setting up your Postman variables, please fill in the values bellow:

  • Ocp-Apim-Subscription-Key: Your Subscription Primary key that you copied from the Developer Portal.

  • X-Request-ID: You can use a randomly generated UUID.

You are now ready to run AISP & PISP scenarios.

3.2 Strong Customer Authentication (SCA)

Strong Customer Authentication is mandated for the initiation of payments as well as for the creation of consents for account access. There are multiple approaches for banking clients to grant TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data. The MoneyGate Open API Sandbox utilizes a Redirect SCA Approach.

To simulate the SCA procedure for the purposes of the Sandbox, fake Customer Ids and corresponding IBANs are already defined within the Sandbox environment. In the table below, you can see the faked Sandbox IBANs.

Users                   IBANS                                                    Credentials

Mock User 1              CY19903000011334111345191062                u:user@company.com

                                    CY28903000017935312893607072                 p:123456!

                                                                                                                     sca:sms

Mock User 2             CY40903000016778300044350962                 u:user1@company1.com

                                                                                                                     p:123456@

                                                                                                                     sca:push

Mock User 3              CY50903000013680998857193055                 u:user2@company2.com

                                    CY10903000016267826540327443                  p:123456$

                                                                                                                      sca:sms

Mock User 4             CY35903000013451009824465011                  u:user3@company3.com

                                                                                                                      p:123456#

                                                                                                                      sca:push

When the IBAN within the request does not match the PSU-ID (as passed within a request), the SCA does not have an effect on the transaction or consent status. Not passing any PSU-ID will lead to a Format Error.

For the purposes of this guide, you will implement two common scenarios to demonstrate the functionality of the APIs. These scenarios include:

  • (AIS functionality) --> Get consent as TPP from a MoneyGate customer and access his/her account balance.

  • (PIS functionality) --> Initiate a payment as a TPP, get consent from the customer and execute the payment.

3.3 AISP

  • This basic AISP scenario includes:

    1. Creation of a consent to access a PSU's account information

    2. Check that the consent request has been created by reading its status

    3. Since the SCA Redirect method is used, following the redirect link provided by the API to validate the TPP's request through SCA (emulated)

    4. Validation of the consent by mimicking the PSU SCA process

    5. Getting the list of all available accounts for the created consent

    6. Getting the account’s balance

    In Postman, navigate to the Moneygate_Sandbox folder (the one you imported earlier). For the AIS scenario, open the AIS Consent folder. In addition, please make sure that the Sandbox Moneygate environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

    1. Choose the createConsent POST call. This call creates a consent request to access a specific PSU's account data.

    The PSU-ID header parameter is required. For the purposes of the Sandbox API, you can use a test username value as the PSU-ID within the Sandbox is mocked.

    The Ocp-Apim-Subscription-Key header parameter is required. This parameter refers to the subscription key you copied earlier from your Developer Portal Account Profile page.

    The request Body is required. Specify the PSU account (use IBAN) and the type of account access (details, balances, transactions) using values from the IBAN table in the Strong Customer Authentication section of this guide. For the purposes of testing, a pre-defined body is included in the call (within the Postman collection) that requests access to account details, balances and transactions of a mock user’s account

Picture

Press “Send” and you should get a response indicating that the consent has been created, as well as the consentId and a psuMessage at the end of the response, that contains a link to validate the consent request.

Picture

2. Select the getConsentStatus GET call. The consentId is already included in the request path via a Postman script. Press “Send” and you should be able to see that the consent status is set to “Received” (RCVD).

Picture

3. You now need to authorize the consent that will be provided to the TPP by mimicking the PSU Authentication process of MoneyGate's environment. Open the scaRedirect link from the initiatePayment call response in your browser. Normally this is the stepwhere the PSU enters his MoneyGate credentials to login, but for the purposes of the Sandbox API a mocked authentication and push notification SCA is employed. In order to log in, provide the credentials listed in the table above.

Picture

4. Depending on the SCA method that is activated on the Mock User account that you logged in (see table above), you will see a mock "Push Notification" screen, which indicates that a push notification has been sent to the user's phone for confirmation, or a mock "SMS OTP screen", which would ask the user to provide the SMS sent to his phone. The "SMS OTP" functionality is mocked for the purpose of the Sandbox, so providing any random digits will suffice. Once the consent authorization is finished, the consent information will be displayed once more for reference before redirecting back to the redirect-uri provided in the consent call headers. You can now close your browser window.

Picture

Picture

Picture

5. Choose the getAccountList GET invocation and press “Send”. A successful response returns all the accounts that the user provided access to via the previous step.

Picture

6. Choose the getBalances GET invocation. In the query parameters, you need to fill the account-id parameter with one of the available IBANS that the user has provided access to. Please hit “Send” to get the account’s balance information.

Picture

(Optional) If you want to revoke a consent, you can Choose the deleteConsent DELETE invocation and press “Send”. The consentId included in the call will be revoked and access to the user’s accounts is no longer viable.

3.4 PISP

This basic PIS scenario includes:

  1. Sending a payment initiation request

  2. Checking that the payment request has been created

  3. Since SCA Redirect method is used, following the redirect link provided by the API to validate the request (emulated)

  4. Authorizing the payment by mimicking the PSU Authentication Process

  5. Verifying that the payment has been executed by checking its status

In Postman, navigate to the Moneygate_Sandbox folder (the one you imported earlier). For the PIS scenario, open the PIS Consent folder. Also, make sure the Sandbox Moneygate environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

  1. Select the initiatePayment call.

The PSU-IP-Address header parameter is required. For the purposes of testing please use a mock value like “192.168.1.1”.

The Ocp-Apim-Subscription-Key header parameter is required. This parameter refers to the subscription key you copied earlier from your Developer Portal Profile Page.

The request Body is required. Please specify the Debtor’s account IBAN, the Creditor’s account IBAN and the amount to be transferred, as well as the address of the Creditor. You can use values from the IBAN table in the Strong Customer Authentication section of this guide. For the purposes of testing a pre-defined body is included in the invocation for your convenience.

Press “Send” and you should get a response indicating that the consent has been created, as well as the consentId and a psuMessage at the end of the response, that contains a link to validate the consent request.

Picture

2. Select the getPaymentInitiatonStatus GET invocation. Τhe paymentId is already included in the request path which is fetched automatically from the Postman test scripts. Press “Send” and you should be able to see that the payment status is set to “Received” (RCVD).

Picture Picture

Picture

3. You now need to authorize the payment consent by mimicking the PSU Authentication Process in the MoneyGate's environment. Open the link contained in the psuMessage field from the initiatePayment invocation response in your browser. Normally this is the step where the PSU performs the SCA Process, but for the purposes of the Sandbox you will experience a mocked SCA. You should now be able to see the payment authorization validation page right away as displayed in the picture below.

Picture

4. After logging in, the next screen will display the payment information and prompt you to either accept or reject it. Choosing either of the two, will navigate you to a "push notification screen" which is for testing purposes. Normally, this would be where the PSU would have to authorize the payment via his mobile app. After the push notification screen, details of the payment will be displayed. Once successful, you will automatically be redirected to the url provided in the tpp-redirect-uri header. You can now close your browser window.

Picture

Picture

5. Choose the getPaymentInitiationStatus GET invocation. You can verify that the payment status has been changed to Finalized (ACCC).

(Optional) If you want to cancel a payment, you can Choose the cancelPayment DELETE invocation and press “Send”, as this will cancel the payment referenced by the previous paymentId. Please keepin mind that you can only cancel payments that have not been authorized.

3.5 PIISP

For the purposes of the Sandbox, you can execute a confirmation of funds request without consent, as per the Berlin Groupspecification.

In Postman, navigate to the Moneygate_Sandbox folder (that you imported earlier). For the PIIS scenario and open the PIIS Consent folder. In addition, please make sure that the Sandbox Moneygate environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

Choose the checkAvailabilityOfFunds POST call.

The Ocp-Apim-Subscription-Key header parameter is required. This parameter refers to the subscription key you copied earlier from the Developer Portal

The request Body is required. Specify the account that you wish to perform a funds availability check as well as the desired amount. You can use one of the IBANs provided in the SCA section of this guide.

Press “Send” and you should get a true/false response depending on whether the account has sufficient funds.

Picture

Picture

4. Go to Production 

The following paragraphs demonstrate how to use the PSD2 Open Banking APIs in the production environment, for certified TPPs. If you have tested your application scenarios with the Sandbox APIs, there are only a few changes you need to make in order to go live.

If you haven’t familiarised yourself with the Sandbox APIs, please visit the Sandbox Documentation page to learn more about the API calls and the AISP/PISP/PIISP scenarios.

A Postman collection for the production environment is also available here

You can check the available PSD2 Production API calls from the Swagger UI:

https://api.psd2.moneygate.com/swagger-ui.html#/

4.1  TPP Identification

The first area that needs to be covered while moving into the production APIs, is the identification of TPPs. In the Sandbox Developers portal, Client ID and Client Secret parameters were produced for the test application, and were used in the API calls as an identification method for the TPP.

According to PSD2, only certified TPPs are allowed to access the Bank’s dedicated interface. TPPs need to carry a valid PSD2 eIDAS Qualified Website Authentication Certificate (QWAC- see https://portal.etsi.org/webapp/workprogram/Report_WorkItem.asp?WKI_ID=54717)

to identify themselves and use the APIs via a secured channel. The PSD2 eIDAS certificates are issued by Qualified Trusted Service Providers (QTSPs). The European Banking Authority (EBA) provides a list of the trusted QTSPs here.

So in order to use the production Open Banking APIs, instead of attaching Client ID and Client Secret in your call headers, you need to:

  • provide your eIDAS certificate in the tpp-qwac-certificate header parameter.

The XS2A interface will check the validity of the certificate against known formats, and also check the regulatory status of the TPP by referring to the TPP register provided by the EBA here.

Note: On your first interaction with the API as a certified TPP, you might have to wait a few seconds to receive a response, in order for the regulatory checks to be performed. Once the eIDAS certificate validation is complete, subsequent calls will be performed faster.

If the certificate provided in the tpp-qwac-certificate is invalid (e.g the PSD2 roles required to perform the requested action do not exist), then you will get a “Certificate invalid” response with 400 error code as demonstrated in the picture below

4.2 SCA Workflow

 According to the PSD2 Directive, Strong Customer Authentication (SCA) practices need to be implemented so that PSUs can authorise consents and provide TPPs with access to their accounts. Amongst the available approaches, the Bank’s implementation supports the SCA Decoupled flow.

More specifically, whenever a consent request is created by the TPP:

  1. PSU is redirected to a secure environment provided by the Bank’s infrastructure

  2. PSU authenticates himself by providing his web banking credentials 

  3. PSU is informed about the mobile application that will be used for authentication and a waiting screen is being displayed  

  4. A push notification  is automatically sent to his/her phone for approval

  5. PSU can then provide his/her approval for that the TPP can access his account information

  6. Once the consent is authorised, PSU is redirected back to the TPP application

In the Sandbox flow, this procedure was simulated by the Sandbox server, and PSU data was mocked for testing purposes using an SMS OTP authorisation flow.

To manage consents, as well as the authorisation of PSUs in a secure environment, the Bank has developed a Consent management application that has the same look & feel as the one available in the Sandbox version, although it is connected to the Bank’s secure identity server.

In order to complete the Decoupled SCA flow, you have to follow the steps above and provide the scaRedirect link to the PSU, who can authenticate by using his/her web banking credentials in the Bank’s safe environment.

4.3  General notes

Some things to consider:

  • As an AISP, the SCA process has to be followed once. Each account access consent has a validity of 90 days by default (unless explicitly requested for less). For this duration, you can implement the rest of the API calls for access to accounts as in the Sandbox case, with a maximum frequency of 4 invocations per day.

  • As a PISP, the SCA process has to be followed for every payment initiation. Once the user has given consent for a specific payment initiation, the payment is forwarded to the Bank’s system for processing. You can use the rest of the calls regarding a specific payment (such as check its status) as in the Sandbox case.

  • As a PIISP, you cannot invoke the Confirmation of Funds call immediately, as in the Sandbox case, where it is allowed for testing purposes. According to PSD2, the consent model for the Confirmation of Funds API differs from the Payments API and the Accounts API, as the consent is held between the PSU and the ASPSP, rather than between the PSU and the TPP.. In order to be able to perform a funds confirmation check, the TPP has to contact the ASPSP in order to get access to the service, by providing his eIDAS certificate for identification.

4.4 Conclusion

The guide was focused on demonstrating how to move your application from the sandbox testing environment, to the production environment. For more detailed information on how to use the PSD2 APIs and implement basic scenarios, please visit the Sandbox Developers Portal and follow the instructions in the Documentation page.

Useful links: