Backbase TPP API Simulator

API simulator for UK Open Banking AIS (Account Information Services), PIS (Payment Initiation Services), and CBPII (Confirmation of Funds) consent flows with SaltEdge.

Setup

# 1. Install dependencies
npm install

# 2. Configure
cp env.example .env
# Edit .env: set OB_SOFTWARE_ID and OB_PRIVATE_KEY_PATH

# 3. Add private key
cp /path/to/your/key.pem ./private_key.pem

# 4. Start
npm start

Server runs on http://localhost:8080

Docker

Build Docker Image

docker build -t bb-tpp-api-simulator:latest .

Run Docker Container (Local Testing)

All configuration is provided via environment variables:

docker run -d \
  -p 8080:8080 \
  -e OB_SOFTWARE_ID=your-software-id \
  -e OB_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_KEY_CONTENT\n-----END PRIVATE KEY-----" \
  -e OB_PROVIDER_CODE=backbase_dev_uk \
  -e PRIORA_URL=priora.saltedge.com \
  -e PROTOCOL=https \
  -e REDIRECT_URI=https://backbase-dev.com/callback \
  -e PORT=8080 \
  --name bb-tpp-simulator \
  bb-tpp-api-simulator:latest

Note: The OB_PRIVATE_KEY environment variable supports Azure Key Vault format (single-line with spaces) and will be automatically converted to proper PEM format.

API Endpoints

Base URL Placeholder: {BASE_URL}

Local: http://localhost:8080

UK API version: UK AIS, PIS and CBPII consent API calls in this simulator target Open Banking v3.1.11.

Replace {BASE_URL} with the appropriate URL in all examples below.

1. Health Check

Check if the service is running.

curl {BASE_URL}/api/health

Response:

{
  "status": "ok",
  "timestamp": "2025-11-06T08:49:11.608Z",
  "version": "1.0.0",
  "service": "bb-tpp-api-simulator"
}

2. API Documentation

Get list of all available endpoints.

curl {BASE_URL}/

3. Create AIS Consent

Create an Account Information Services consent and get the authorization URL.

curl -X POST {BASE_URL}/api/uk/ais/consent \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body (all fields optional):

Field	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)
`redirectUri`	string	OAuth callback URL	Value from env `REDIRECT_URI`
`permissions`	array	List of AIS permissions	7 default account/transaction permissions
`expirationDateTime`	string \| null	ISO 8601 date when consent expires	See below

expirationDateTime behavior:

Not provided (omit from request): simulator sends now + 30 days to Salt Edge.
null: simulator omits the field entirely from the upstream payload (field not sent to Salt Edge).
String (e.g. "2025-12-31T23:59:59Z"): simulator forwards the value to Salt Edge.

To create a consent without any expiration date sent to Salt Edge, pass "expirationDateTime": null in your request body.

Note: For UK AIS v3.1.11, Salt Edge requires a Risk object in the upstream consent payload.
The simulator automatically sends Risk: {} when creating AIS consents.

Example with custom parameters:

curl -X POST {BASE_URL}/api/uk/ais/consent \
  -H "Content-Type: application/json" \
  -d '{
    "providerCode": "backbase_dev_uk",
    "redirectUri": "https://your-app.com/callback",
    "permissions": ["ReadAccountsBasic", "ReadBalances", "ReadTransactionsBasic"],
    "expirationDateTime": "2025-12-31T23:59:59Z"
  }'

Example to omit ExpirationDateTime from upstream (no expiration sent to Salt Edge):

curl -X POST {BASE_URL}/api/uk/ais/consent \
  -H "Content-Type: application/json" \
  -d '{"expirationDateTime": null}'

Response:

{
  "consentId": "urn-backbase_dev_uk-intent-12345",
  "authorizationUrl": "https://business-universal.dev.oblm.azure.backbaseservices.com/...",
  "status": "Pending"
}

➡️ Open authorizationUrl in a browser to authorize the consent.

4. Get AIS Consent Details

Retrieve details of an existing AIS consent by ID.

curl "{BASE_URL}/api/uk/ais/consent/{CONSENT_ID}"

Path Parameters:

Parameter	Type	Description	Required
`consentId`	string	The consent ID returned from create consent	Yes

Query Parameters (optional):

Parameter	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)

Example:

curl "{BASE_URL}/api/uk/ais/consent/urn-backbase_dev_uk-intent-12345?providerCode=backbase_dev_uk"

Response:

{
  "success": true,
  "data": {
    "Data": {
      "ConsentId": "urn-backbase_dev_uk-intent-12345",
      "Status": "AwaitingAuthorisation",
      "Permissions": ["ReadAccountsBasic", "ReadBalances", ...],
      "ExpirationDateTime": "2025-12-06T08:49:11Z"
    }
  }
}

5. Revoke AIS Consent

Revoke/Delete an existing AIS consent by ID. This permanently removes the consent and prevents further use.

curl -X DELETE "{BASE_URL}/api/uk/ais/consent/{CONSENT_ID}"

Path Parameters:

Parameter	Type	Description	Required
`consentId`	string	The consent ID to revoke	Yes

Query Parameters (optional):

Parameter	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)

Example:

curl -X DELETE "{BASE_URL}/api/uk/ais/consent/urn-backbase_dev_uk-intent-12345?providerCode=backbase_dev_uk"

Response:

{
  "success": true,
  "message": "Consent revoked successfully",
  "consentId": "urn-backbase_dev_uk-intent-12345"
}

6. Create PIS Consent

Create a Payment Initiation Services consent and get the authorization URL.

curl -X POST {BASE_URL}/api/uk/pis/consent \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body (all fields optional):

Field	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)
`redirectUri`	string	OAuth callback URL	Value from env `REDIRECT_URI`
`paymentProduct`	string	Payment product type	`domestic-payment-consents`
`initiation`	object	Payment initiation data	Default UK FPS payment structure
`authorisation`	object	Authorisation data (not used for scheduled payments)	Not sent unless provided
`scaSupportData`	object	SCA support data	Not sent unless provided
`risk`	object	Risk data	Not sent unless provided
`permission`	string	Permission for scheduled payments	`Create` (auto-set for scheduled)

Default Payment Initiation Structure: The default initiation includes:

LocalInstrument: UK.OBIE.FPS
InstructedAmount: 20.00 GBP
DebtorAccount: UK sort code account format
CreditorAccount: UK sort code account format
Remittance information

Example: Immediate Domestic Payment

curl -X POST {BASE_URL}/api/uk/pis/consent \
  -H "Content-Type: application/json" \
  -d '{
    "providerCode": "backbase_dev_uk",
    "redirectUri": "https://your-app.com/callback",
    "paymentProduct": "domestic-payment-consents",
    "initiation": {
      "InstructionIdentification": "PAY001",
      "EndToEndIdentification": "E2E-12345",
      "LocalInstrument": "UK.OBIE.FPS",
      "InstructedAmount": {
        "Amount": "100.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "John Doe"
      },
      "CreditorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Jane Smith"
      }
    }
  }'

Example: Scheduled Domestic Payment

curl -X POST {BASE_URL}/api/uk/pis/consent \
  -H "Content-Type: application/json" \
  -d '{
    "providerCode": "backbase_dev_uk",
    "redirectUri": "https://your-app.com/callback",
    "paymentProduct": "domestic-scheduled-payment-consents",
    "initiation": {
      "InstructionIdentification": "SCHD001",
      "EndToEndIdentification": "SCHEDULED-12345",
      "LocalInstrument": "UK.OBIE.FPS",
      "RequestedExecutionDateTime": "2026-02-15T09:00:00+00:00",
      "InstructedAmount": {
        "Amount": "100.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "John Doe"
      },
      "CreditorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Jane Smith"
      },
      "RemittanceInformation": {
        "Reference": "Monthly payment",
        "Unstructured": "Scheduled transfer"
      }
    }
  }'

Note: For scheduled payments:

RequestedExecutionDateTime is required in the initiation (future date/time)
permission defaults to "Create" automatically
Do NOT include authorisation in the request body

Example: Domestic Standing Order

curl -X POST {BASE_URL}/api/uk/pis/consent \
  -H "Content-Type: application/json" \
  -d '{
    "providerCode": "backbase_dev_uk",
    "redirectUri": "https://your-app.com/callback",
    "paymentProduct": "domestic-standing-order-consents",
    "permission": "Create",
    "initiation": {
      "Frequency": "EvryDay",
      "Reference": "Monthly rent payment",
      "FirstPaymentDateTime": "2026-02-01T09:00:00+00:00",
      "FirstPaymentAmount": {
        "Amount": "500.00",
        "Currency": "GBP"
      },
      "RecurringPaymentAmount": {
        "Amount": "500.00",
        "Currency": "GBP"
      },
      "FinalPaymentDateTime": "2027-01-31T09:00:00+00:00",
      "FinalPaymentAmount": {
        "Amount": "500.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "John Doe"
      },
      "CreditorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Landlord Ltd"
      }
    }
  }'

Note: For standing orders:

paymentProduct must be "domestic-standing-order-consents"
Frequency is required (e.g., EvryDay, EvryWorkgDay, IntrvlWkDay:01:03 for every 3rd day)
FirstPaymentDateTime, RecurringPaymentAmount are required
FinalPaymentDateTime and FinalPaymentAmount are optional (omit for indefinite standing order)
permission field is automatically set to "Create"

Response:

{
  "consentId": "urn-backbase_dev_uk-intent-12345",
  "authorizationUrl": "https://business-universal.dev.oblm.azure.backbaseservices.com/...",
  "status": "AwaitingAuthorisation"
}

➡️ Open authorizationUrl in a browser to authorize the payment consent.

7. Get PIS Consent Details

Retrieve details of an existing PIS consent by ID.

curl "{BASE_URL}/api/uk/pis/consent/{CONSENT_ID}"

Path Parameters:

Parameter	Type	Description	Required
`consentId`	string	The consent ID returned from create consent	Yes

Query Parameters (optional):

Parameter	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)
`paymentProduct`	string	Payment product type	`domestic-payment-consents`

Example:

curl "{BASE_URL}/api/uk/pis/consent/urn-backbase_dev_uk-intent-12345?providerCode=backbase_dev_uk&paymentProduct=domestic-payment-consents"

Response:

{
  "success": true,
  "data": {
    "Data": {
      "ConsentId": "urn-backbase_dev_uk-intent-12345",
      "Status": "AwaitingAuthorisation",
      "Initiation": {
        "InstructionIdentification": "ANSM023",
        "EndToEndIdentification": "FRESCO.21302.GFX.37",
        "LocalInstrument": "UK.OBIE.FPS",
        "InstructedAmount": {
          "Amount": "20.00",
          "Currency": "GBP"
        },
        ...
      },
      "Risk": {
        "PaymentContextCode": "EcommerceGoods",
        ...
      }
    }
  }
}

8. Create CBPII Consent

Create a Confirmation of Funds (CBPII) consent and get the authorization URL.

curl -X POST {BASE_URL}/api/uk/cbpii/consent \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body (all fields optional):

Field	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)
`redirectUri`	string	OAuth callback URL	Value from env `REDIRECT_URI`
`expirationDateTime`	string	ISO 8601 date when consent expires	30 days from now
`debtorAccount`	object	Debtor account data used for CBPII consent	Default UK SortCodeAccountNumber account

Example with custom parameters:

curl -X POST {BASE_URL}/api/uk/cbpii/consent \
  -H "Content-Type: application/json" \
  -d '{
    "providerCode": "backbase_dev_uk",
    "redirectUri": "https://your-app.com/callback",
    "debtorAccount": {
      "SchemeName": "UK.OBIE.SortCodeAccountNumber",
      "Identification": "60304560543816",
      "Name": "Ricardos Current Account"
    }
  }'

Response:

{
  "consentId": "urn-backbase_dev_uk-intent-12345",
  "authorizationUrl": "https://business-universal.dev.oblm.azure.backbaseservices.com/...",
  "status": "Pending"
}

➡️ Open authorizationUrl in a browser to authorize the CBPII consent.

9. Get CBPII Consent Details

Retrieve details of an existing CBPII consent by ID.

curl "{BASE_URL}/api/uk/cbpii/consent/{CONSENT_ID}"

Path Parameters:

Parameter	Type	Description	Required
`consentId`	string	The consent ID returned from create consent	Yes

Query Parameters (optional):

Parameter	Type	Description	Default
`providerCode`	string	Open Banking provider code	`backbase_dev_uk` (from env)

Example:

curl "{BASE_URL}/api/uk/cbpii/consent/urn-backbase_dev_uk-intent-12345?providerCode=backbase_dev_uk"

Response:

{
  "success": true,
  "data": {
    "Data": {
      "ConsentId": "urn-backbase_dev_uk-intent-12345",
      "Status": "AwaitingAuthorisation"
    }
  }
}

Default Consent Objects (Empty Request Body)

When caller sends {}, the simulator applies these defaults before calling Salt Edge.

Common request defaults (applies to all three):

providerCode: backbase_dev_uk (or OB_PROVIDER_CODE from env)
redirectUri: https://backbase-dev.com/callback (or REDIRECT_URI from env)

AIS default payload sent upstream (`POST /api/uk/ais/consent`)

When request body is {}, the simulator sends ExpirationDateTime as now + 30 days.

To omit ExpirationDateTime entirely (field not sent to Salt Edge at all), pass "expirationDateTime": null in the request. The upstream payload will then contain only Permissions and Risk under Data—no ExpirationDateTime key.

Default payload (when {} or when expirationDateTime is not provided):

{
  "Data": {
    "ExpirationDateTime": "<now + 30 days, ISO-8601>",
    "Permissions": [
      "ReadAccountsBasic",
      "ReadAccountsDetail",
      "ReadBalances",
      "ReadTransactionsBasic",
      "ReadTransactionsCredits",
      "ReadTransactionsDebits",
      "ReadTransactionsDetail"
    ]
  },
  "Risk": {}
}

PIS default payload sent upstream (`POST /api/uk/pis/consent`)

{
  "paymentProduct": "domestic-payment-consents",
  "Data": {
    "Initiation": {
      "InstructionIdentification": "ANSM023",
      "EndToEndIdentification": "FRESCO.<timestamp>.GFX.37",
      "LocalInstrument": "UK.OBIE.FPS",
      "InstructedAmount": {
        "Amount": "20.00",
        "Currency": "GBP"
      },
      "DebtorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "11280001234567",
        "Name": "Andrea Smith",
        "SecondaryIdentification": "0002"
      },
      "CreditorAccount": {
        "SchemeName": "UK.OBIE.SortCodeAccountNumber",
        "Identification": "08080021325698",
        "Name": "Bob Clements",
        "SecondaryIdentification": "0003"
      },
      "RemittanceInformation": {
        "Reference": "FRESCO-037",
        "Unstructured": "Internal ops code 5120103"
      }
    },
  }
}

Authorisation, SCASupportData, and Risk are omitted unless explicitly provided in request.

CBPII default payload sent upstream (`POST /api/uk/cbpii/consent`)

{
  "Data": {
    "ExpirationDateTime": null,
    "DebtorAccount": {
      "SchemeName": "UK.OBIE.SortCodeAccountNumber",
      "Identification": "60304560543816",
      "Name": "Ricardos Current Account"
    }
  }
}

Configuration (.env)

# Required
OB_SOFTWARE_ID=your-software-id
OB_PRIVATE_KEY_PATH=./private_key.pem

# Optional
OB_PROVIDER_CODE=backbase_dev_uk
REDIRECT_URI=https://backbase-dev.com/callback
PRIORA_URL=priora.saltedge.com
PORT=8080

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
server		server
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
env.example		env.example
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Backbase TPP API Simulator

Table of Contents

Setup

Docker

Build Docker Image

Run Docker Container (Local Testing)

API Endpoints

1. Health Check

2. API Documentation

3. Create AIS Consent

4. Get AIS Consent Details

5. Revoke AIS Consent

6. Create PIS Consent

7. Get PIS Consent Details

8. Create CBPII Consent

9. Get CBPII Consent Details

Default Consent Objects (Empty Request Body)

AIS default payload sent upstream (`POST /api/uk/ais/consent`)

PIS default payload sent upstream (`POST /api/uk/pis/consent`)

CBPII default payload sent upstream (`POST /api/uk/cbpii/consent`)

Configuration (.env)

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Backbase TPP API Simulator

Table of Contents

Setup

Docker

Build Docker Image

Run Docker Container (Local Testing)

API Endpoints

1. Health Check

2. API Documentation

3. Create AIS Consent

4. Get AIS Consent Details

5. Revoke AIS Consent

6. Create PIS Consent

7. Get PIS Consent Details

8. Create CBPII Consent

9. Get CBPII Consent Details

Default Consent Objects (Empty Request Body)

AIS default payload sent upstream (POST /api/uk/ais/consent)

PIS default payload sent upstream (POST /api/uk/pis/consent)

CBPII default payload sent upstream (POST /api/uk/cbpii/consent)

Configuration (.env)

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

AIS default payload sent upstream (`POST /api/uk/ais/consent`)

PIS default payload sent upstream (`POST /api/uk/pis/consent`)

CBPII default payload sent upstream (`POST /api/uk/cbpii/consent`)

Packages