Playground bank
25 January 2023 Less than to read
Overview
This page provides details of how to use the Sage playground bank.
The playground bank allows integrating providers to 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.
This playground bank has been created for testing in 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.
When accessing the onboarding screen the playground bank will perform the following actions in the background:
-
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 }, }; -
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.
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.