Guides

Getting Started with APIs in Digital Banking

Suggest Edits

This page offers a developer-focused guide on the application of APIs in digital banking. It outlines the fundamental concepts related to APIs, details the terminology essential for understanding and implementing APIs, and presents practical use cases for APIs in banking systems. The guide also provides a brief introduction on how to use APIs with Postman, a popular API testing tool. This concise overview aims to support developers in harnessing APIs to optimize the operation and efficiency of digital banking systems.

Getting Started with Braid API

Braid API is a robust solution designed for developers to create and manage financial products with ease. Our operations follow a systematic flow consisting of six fundamental steps:

  1. Authentication
  2. Product/Program Setup
  3. Create Customer Entity
  4. Create an Account
  5. Create a Counterparty
  6. Create a Transaction

Authentication with Basic Authentication

Overview:

The Braid API supports authentication using Basic Authentication, a simple and widely-used authentication mechanism. Basic Authentication requires clients to include a username and API key with each request. This documentation provides guidance on how to authenticate with the Braid API using Basic Authentication, ensuring secure access to protected resources.

Note: Our API collection utilizes two distinct base URLs:

int.braid.zone (indicating a sandbox environment)

dev.braid.zone (indicating a developer environment)

Authentication Endpoint:

The Braid API does not have a dedicated authentication endpoint for Basic Authentication. Instead, clients include their credentials in the request headers for each API endpoint they access.

Authentication Header:

To authenticate with the Braid API using Basic Authentication, clients must include an Authorization header in their HTTPS request. The Authorization header value consists of the word "Basic" followed by a space and a base64-encoded string of the username and API key, separated by a colon.

Example:

Suppose the username is "example_user" and the API key is "2dc3dcfc-dd43-4b26-b16b-9028159f3dad". The Authorization header value would be "Basic ZXhhbXBsZV91c2VyOjJkYzNkY2ZjLWRkNDMtNGIyNi1iMTZiLTkwMjgxNTlmM2RhZA==", resulting in an Authorization header of "Basic ZXhhbXBsZV91c2VyOjJkYzNkY2ZjLWRkNDMtNGIyNi1iMTZiLTkwMjgxNTlmM2RhZA==".

Request Example:

GET /api/resource HTTP/1.1
Host: int.braid.zone
Authorization: Basic ZXhhbXBsZV91c2VyOjJkYzNkY2ZjLWRkNDMtNGIyNi1iMTZiLTkwMjgxNTlmM2RhZA==

Security Considerations:

Transport Layer Security (TLS): Basic Authentication transmits credentials in plaintext, so it's crucial to use HTTPS (TLS) to encrypt the communication between the client and the server.
Secure Password Storage: Store passwords securely on the client side to prevent unauthorized access to user credentials.

Error Handling:

If authentication fails, the API returns a 401 Unauthorized status code along with an error message indicating the reason for the failure. Clients should handle this error gracefully and prompt users to re-enter their credentials if necessary.

Data Formats:

The Braid API accepts and returns data in standard formats such as JSON. To avoid errors during authentication, ensure that request and response payloads are formatted correctly according to the API documentation.

Basic Authentication provides a simple and effective way to authenticate with the Braid API using a username and API key. By following the guidelines outlined in this documentation, clients can securely access protected resources and integrate seamlessly with the Braid platform.

Programs and Products

In Braid, a financial program serves as the parent entity, and the bank partner is responsible for setting up both programs and products within their Braid instance. Programs organize various products under them, creating a structured hierarchy.

For example, a bank might establish a Virtual Wallet Program or a Business Payment Program, each containing products like:

  • Virtual Wallets: Digital accounts for customers to store funds and make payments.
  • International Payments: Accounts enabling domestic cross-border payments.
  • Business Payment Accounts: Customized accounts for managing payroll and vendor payments.
  • Wholesale ACH Accounts: Accounts designed for high-volume ACH transactions.

Developers are assigned unique product IDs, which are essential for creating and managing business entities within the system.

Create Customer Entity

The progression begins with creating a customer entity, which may represent a business or an individual.

For Businesses, the following endpoint should be used: POST/business

{
  "ach": {
    "accountNumber": "string",
    "bankAccountType": "SAVINGS",
    "bankName": "string",
    "routingNumber": "string"
  },
  "achCompanyId": "string",
  "address": {
    "city": "string",
    "countryCode": "string",
    "line1": "string",
    "line2": "string",
    "postalCode": "string",
    "state": "string",
    "type": "MAILING"
  },
  "businessEntityType": "SOLE_PROPRIETOR",
  "businessIdType": "EIN",
  "dba": "string",
  "email": "string",
  "formationDate": "2024-05-28",
  "idNumber": "string",
  "incorporationState": "string",
  "mobilePhone": "string",
  "name": "string",
  "productId": 0,
  "submittedBy": {
    "contactPersonEmail": "string",
    "contactPersonFirstName": "string",
    "contactPersonLastName": "string",
    "contactPersonPhone": "string"
  },
  "website": "string"
}

For individuals, the following endpoint should be used: POST/individual

{
  "ach": {
    "accountNumber": "string",
    "bankAccountType": "SAVINGS",
    "bankName": "string",
    "routingNumber": "string"
  },
  "achCompanyId": "string",
  "address": {
    "city": "string",
    "countryCode": "string",
    "line1": "string",
    "line2": "string",
    "postalCode": "string",
    "state": "string",
    "type": "MAILING"
  },
  "customerToken": "string",
  "dateOfBirth": "2024-05-28",
  "email": "string",
  "firstName": "string",
  "idNumber": "string",
  "idType": "string",
  "lastName": "string",
  "middleName": "string",
  "mobilePhone": "string",
  "productId": 0,
  "ssn": "string"
}

Create Account

Following the customer entity creation, the next step is to establish an account associated with the customer entity:

On successful execution of these requests, business or individual bank accounts will be created and linked to the respective entity. These accounts can now perform financial transactions.

Create a Counterparty

Subsequently, a counterparty is created for the customer entity. This process utilizes corresponding accounts rather than the customer type:

  • The [POST/Counterparty] API endpoint facilitates counterparty creation. It accepts information for various linked accounts such as accountId, ach details, braid account details, businessId, name details, individualId, productId, and wire transfer details.
{
  "accountNumber": "string",
  "ach": {
    "accountNumber": "string",
    "bankAccountType": "SAVINGS",
    "bankName": "string",
    "routingNumber": "string"
  },
  "braid": {
    "accountNumber": "string"
  },
  "businessId": 0,
  "email": "string",
  "individualId": 0,
  "name": "string",
  "phone": "string",
  "productId": 0,
  "type": "BUSINESS",
  "wire": {
    "accountNumber": "string",
    "address": {
      "city": "string",
      "countryCode": "string",
      "line1": "string",
      "line2": "string",
      "postalCode": "string",
      "state": "string",
      "type": "MAILING"
    },
    "bankName": "string",
    "intermediaryRoutingNumber": "string",
    "routingNumber": "string",
    "routingNumberType": "ABA"
  }
}

Create a Transaction

The final step involves creating a transaction. This operation is contingent on the type of transaction to be executed. Generally, transactions fall into two categories: Push/Pull and Funding/Withdrawal.

  • Transaction push/pull: Refers to transactions to and from a counterparty
  • Transaction funding/withdrawal: Refers to transactions pertaining to self, which are managed via the payment instrument endpoint.

Specific transaction operations include:

  • Transaction ACH push: [POST/transactions/ach/push] to initiate a push transaction
  • Transaction ACH pull: [POST/transactions/ach/pull] to initiate a pull transaction
  • Transaction ACH funding: The [POST/transactions/ach/funding] endpoint facilitates the initiation of a transaction, transferring a specified amount of funds to a designated account within the service.
  • Transaction ACH withdrawal: With the [POST /transactions/ach/withdrawal] endpoint, a specified amount of funds can be withdrawn from a specific account, utilizing the ACH network for secure and reliable transactions.

By progressing systematically through these six core steps, developers can effectively navigate the Braid API and effortlessly create a range of financial products.

Getting Started with APIs in Digital Banking

1. Understanding APIs

APIs, or Application Programming Interfaces, are sets of rules and protocols allowing software applications to communicate and interact. In the context of digital banking, APIs facilitate efficient information flow between different systems, making numerous operations possible such as real-time balance updates, secure money transfers, and instant loan approvals.

2. Key API Concepts and Definitions

Understanding certain API concepts and terminologies is pivotal to managing and implementing APIs effectively.

  • HTTP and REST Protocols: HTTP is the foundation for data exchange on the web while REST, an architectural style built upon HTTP, is used to build web services.

  • API Requests and Responses: An API Request is a call sent from a software to a server to perform a task. When the server processes the request, it returns an API Response indicating the result of the operation or providing the requested data.

  • API Endpoints: API Endpoints are paths or URLs where an API can be accessed. Each endpoint corresponds to a specific function or a set of functions on the server.

  • Status Codes, Headers, Message Body: Status codes in an API response indicate whether a specific HTTP request has been successfully completed. Headers are additional parameters for the HTTP request or response, and the message body contains the actual data.

  • HTTP Methods: GET, POST, PUT, PATCH, DELETE: These describe the action to be performed on a given resource. GET retrieves data, POST creates data, PUT updates data, PATCH updates specific limited data, and DELETE removes data.

3. Applying APIs in Banking Systems

Implementing APIs into banking operations can greatly enhance system performance and efficiency.

  • Mobile Banking Apps: APIs enable communication between the user interface and the backend of mobile banking apps, facilitating functionalities like data retrieval and transaction processing.

  • Payment Gateways: APIs ensure secure and quick communication between the payment gateway, issuing bank, and the merchant's website/app, making online transactions smoother.

  • Real-time Transfers and Transactions: APIs establish protocols for real-time communication between banking systems, enabling services like instant money transfers and real-time balance checks.

  • Customer Authentication and Account Information Services: APIs provide procedure for verifying user credentials, maintaining session information, and managing account information in real-time.

4. Using APIs with Postman

Postman is a robust tool for sending requests to APIs and inspecting responses.

  • Navigating the Postman Interface: The Postman dashboard has numerous options to import, create, manage, and share API requests.

  • Sending Requests to APIs: You can create requests in POSTMAN, specify the HTTP method (GET, POST, PUT, DELETE, etc.), and send them to the server.

  • Interpreting API Responses: Postman structures API responses to include status, time taken to complete the request, size of the response, headers, message body (actual data), and cookie information.

Learning to work with APIs effectively demands time and patience. With regular practice and persistent exploration, you're set to optimize the numerous opportunities provided by APIs in the world of digital banking.

Updated about 1 month ago