Skip to content
Developerhome

Playground bank

  Less than to read


Overview

This page provides details of how to use the Sage playground bank.

The playground bank allows integrating providers explore the various Banking Service flows by acting as the external provider and returning demo data. This lets you walk through the API calls involved in each flow without having your connector API currently deployed and responding to our requests.

Image showing the playground bank flow.

:

This playground bank has been created for testing within our sandbox environment.


Setup

We recommend using the playground bank when exploring the Banking Service APIs and the flows involved with integration.

To use this bank with our Banking Service public postman collection, obtain your Postman environment file by registering your interest. You can then add the playground bank Id:

_preset_consumer_bankId: 3993ba12-039d-43a5-a5ae-1493e5ac1ff8

This bank can also be used for testing if you are accessing a consuming product which is pointed at our sandbox environment. Search for ‘Playground Bank’ when attempting to connect your account to begin the onboarding flow.

The playground bank is currently only setup in the US region.


Onboarding

You can initiate the onboarding of the playground bank by either:

  • selecting ‘Playground Bank’ in the consuming product bank selection screen, or
  • in the Postman collection by calling the /indirectlinkaccount request and pasting the returned redirect URL into your browser.
:

The ‘Email’ and ‘Password’ field is just for demonstration purposes. These can be left empty.

Image showing an example login screen.

When accessing the onboarding screen the playground bank will perform the following actions in the background:

  1. Retrieve a token from the Sage ID Shadow service to authenticate the following call.

    View Sage ID token request
             
                 // Shadow API call to Sage ID config    
                 var data = JSON.stringify({
                     grant_type: 'client_credentials',
                     client_id:'(Your client id)',
                     client_secret: '(Your client secret)',
                     audience: 'sfdsbanking/sfdsBankingProvider-Pre'
                 });
                 var options = {
                     hostname: 'id-shadow.sage.com',
                     path: '/oauth/token',
                     method: 'POST',
                     headers: {
                     'Content-Type': 'application/json',
                     'Content-Length': shadowData.length
                     },
                 };
             
         
  2. Send a PATCH request to the banking service authorisation endpoint with 2 demo bank accounts.

    View PATCH Authorisations request
             
                 // Banking Service API call to patch authorisations 
                 var bankingServiceData = '{
                     "data":{
                         "status":"success",
                         "bankAccounts":[
                             {
                                 "bankAccountExternalId":"1234",
                                 "accountName":"Playground-Account-1",
                                 "bankIdentifier":"1234",
                                 "branchIdentifier":"branch-1",
                                 "accountIdentifier":"1342"
                             },
                             {
                                 "bankAccountExternalId":"12345",
                                 "accountName":"Playground-Account-2",
                                 "bankIdentifier":"12345",
                                 "branchIdentifier":"branch-2",
                                 "accountIdentifier":"12345"
                             }
                         ]
                     }
                 }';
                 var bankingServiceOptions = {
                     "method": "PATCH",
                     "hostname": "papi-snd01-us-east-1.sagebanking-sandbox.cloud",
                     "port": null,
                     "path": `/v1/authorisations/${authorisationId}`,
                     "headers": {
                         "authorization": cloudIdToken,
                         "x-api-key": "(Your API Key))",
                         "cache-control": "no-cache",
                         "content-type": "application/x-www-form-urlencoded"
                     }
                 };
             
         

You should then select Redirect back to Sage Banking Service. This will open the Banking Service “Select an account” screen. Choose one of the playground accounts and select OK. You can then close the window and continue the flow in the Postman collection or the consuming product.

Image showing the select account screen.


Transactions

When you have onboarded an account with the playground bank, it will automatictly post 2 statements onto the account. This amends the account from pending to active. The account only turns active when the first statement has been pushed by the provider.

Statement request body
            
            {
            "data": {
                "principalId": "",
                "bankId": "",
                "expected": {
                    "transactionDetailsCount": 2,
                    "accountDetailsCount": 1,
                    "transactionCreditSum": 100,
                    "transactionDebitSum": -100
                },
                "accountDetails": [
                    {
                        "bankAccountId": "",
                        "status": "active",
                        "ledgerBalance": 0,
                        "ledgerBalanceDate": "2019-11-24T12:00:00.000Z",
                        "availableBalance": 0,
                        "availableBalanceDate": "2019-11-24T12:00:00.000Z"
                    }
                ],
                "transactionDetails": [
                    {
                        "uniqueId": "1",
                        "bankAccountId": "",
                        "transactionAmount": 100,
                        "transactionType": "CREDIT",
                        "transactionStatus": "posted",
                        "datePosted": "2019-11-02T23:00:12.000Z",
                        "dateUserInitiated": "2019-11-04T22:54:00.000Z",
                        "exchangeCurrency": "EUR",
                        "exchangeAmount": 120,
                        "checkNumber": "123456",
                        "referenceNumber": "00000001",
                        "description": "DEBIT DESCRIPTION 1",
                        "payee": {
                            "payeeDescription": "100001",
                            "address1": "1 the something",
                            "address2": "on some street",
                            "address3": "on some estate",
                            "city": "in a city",
                            "state": "in a state",
                            "postalCode": "MY POST CODE",
                            "country": "GBR",
                            "phoneNumber": "0091299291212",
                            "payeeBankId": "123456",
                            "payeeAccountId": "654321"
                        },
                        "coordinates": {
                            "lat": 0.9812,
                            "long": 1.0238
                        },
                        "narrative1": "DEBIT NARRATIVE 1",
                        "narrative2": "DEBIT EXTENDED NARRATIVE 1",
                        "category": {
                            "topLevelCategory": "TopCategory",
                            "subCategory": "SubCategory",
                            "categoryId": 12,
                            "standardIndustrialCode": "9089"
                        }
                    },
                    {
                        "uniqueId": "2",
                        "bankAccountId": "",
                        "transactionAmount": -100,
                        "transactionType": "DEBIT",
                        "transactionStatus": "posted",
                        "datePosted": "2019-11-02T23:00:12.000Z",
                        "dateUserInitiated": "2019-11-04T22:54:00.000Z",
                        "exchangeCurrency": "EUR",
                        "exchangeAmount": -120,
                        "checkNumber": "123456",
                        "referenceNumber": "00000002",
                        "description": "DEBIT DESCRIPTION 2",
                        "payee": {
                            "payeeDescription": "100001",
                            "address1": "1 the something",
                            "address2": "on some street",
                            "address3": "on some estate",
                            "city": "in a city",
                            "state": "in a state",
                            "postalCode": "MY POST CODE",
                            "country": "GBR",
                            "phoneNumber": "0091299291212",
                            "payeeBankId": "123456",
                            "payeeAccountId": "654321"
                        },
                        "coordinates": {
                            "lat": 0.9812,
                            "long": 1.0238
                        },
                        "narrative1": "DEBIT NARRATIVE 2",
                        "narrative2": "DEBIT EXTENDED NARRATIVE 2",
                        "category": {
                            "topLevelCategory": "TopCategory",
                            "subCategory": "SubCategory",
                            "categoryId": 12,
                            "standardIndustrialCode": "9089"
                        }
                    }
                ]
            }
            }
            
        

When you have onboarded, you can continue to push additiional transactions through the provider API /statements endpoint using the Postman collection.


Was this helpful?