Skip to content
Developerhome
Product homepage
Banking Service

Posting Banks

  Less than to read

Bank Sync

Bank Sync registers your banks with Banking Service using a single POST request to the /banks endpoint.

📚 Complete API Documentation: POST /banks endpoint specification

Overview

Here’s what you need to know:

  • One endpoint: POST /banks
  • Two key fields: bankID and aggregatorID
  • Simple mapping:
    • Your bankID → Our principalID
    • Your aggregatorID → Our externalRef

Endpoints by Environment

🧪 Sandbox

  • URL: https://papi-snd01-{region}.sagebanking-sandbox.cloud/v1/banks
  • Regions: eu-west-1 or us-east-1
  • Management: Can be done entirely using the Bruno Collection

🚀 Production

  • URL: https://{region}-banking.fabric.sage.com/provider/v1/banks
  • Regions: eu or us
  • Management: Cannot be done via Bruno - you must implement this call in your solution

📚 Full API Specification: POST /banks endpoint

Watch the video below for a complete walkthrough.

Quick Example

Here’s a basic POST request to sync a bank:

POST /banks
{
  "data": [
    {
      "toCreate": [
        {
          "supportiframe": true,
          "countryCode": "GB",
          "name": "Your Bank Name",
          "callbackURLs": {
            "notification": "https://api.yourbank.com/banking-service/notification",
            "availableAccounts": "https://api.yourbank.com/banking-service/availableaccounts",
            "auth": "https://api.yourbank.com/banking-service/auth",
            "reAuth": "https://api.yourbank.com/banking-service/authrefresh"
          },
          "externalRef": "your-aggregator-id-here",
          "url": "https://yourbank.com"
        }
      ]
    }
  ]
}

This single request handles bank registration with Banking Service.

Field Mapping

Your Field Maps To Our Field What It Is
bankID principalId Your unique bank identifier (UUID format)
aggregatorID externalRef Your aggregator/provider identifier

Required Fields

When creating or updating a bank, you need to provide:

  • name - Bank name as it appears to users
  • countryCode - ISO country code (e.g., “GB”, “US”)
  • externalRef - Your aggregator identifier
  • callbackURLs - Your Connector API endpoints
  • url - Your bank’s website URL
  • supportiframe - Whether your auth flow supports iframes

Common Operations

✅ Create a New Bank

{
  "data": [
    {
      "toCreate": [
        {
          "supportiframe": true,
          "countryCode": "GB",
          "name": "Example Bank",
          "callbackURLs": {
            "notification": "https://api.yourbank.com/banking-service/notification",
            "availableAccounts": "https://api.yourbank.com/banking-service/availableaccounts",
            "auth": "https://api.yourbank.com/banking-service/auth",
            "reAuth": "https://api.yourbank.com/banking-service/authrefresh"
          },
          "externalRef": "aggregator-456",
          "url": "https://yourbank.com"
        }
      ]
    }
  ]
}

🔄 Update an Existing Bank

{
  "data": [
    {
      "toUpdate": [
        {
          "supportiframe": true,
          "countryCode": "GB",
          "name": "Updated Bank Name",
          "callbackURLs": {
            "notification": "https://api.yourbank.com/banking-service/notification",
            "availableAccounts": "https://api.yourbank.com/banking-service/availableaccounts",
            "auth": "https://api.yourbank.com/banking-service/auth",
            "reAuth": "https://api.yourbank.com/banking-service/authrefresh"
          },
          "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
          "externalRef": "aggregator-456",
          "url": "https://yourbank.com"
        }
      ]
    }
  ]
}

🗑️ Remove a Bank (Sandbox Only)

{
  "data": [
    {
      "toRemove": [
        {
          "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
          "externalRef": "aggregator-456"
        }
      ]
    }
  ]
}

Environment Details

🧪 Sandbox

  • Purpose: Test with dummy banks and development
  • Management: Use the Bruno Collection for easy testing
  • Cleanup: Use toRemove to clean up test data
  • Regions: eu-west-1 or us-east-1

🚀 Production

  • Purpose: Submit real banks for approval
  • Management: Must implement the API call in your solution (Bruno cannot be used)
  • Approval: Requires PM approval before banks appear to users
  • Regions: eu or us
  • Limitations: No toRemove operation (contact support if needed)

Summary

Bank Sync consists of:

  1. One POST request to /banks
  2. Field mapping: bankID → principalID, aggregatorID → externalRef
  3. Choose the appropriate operation: create, update, or remove

Need More Details?

What’s Next?

Once your banks are synced, move on to Stage 4: Go Live and Support to complete your integration.

Was this helpful?