Skip to main content

​
Introduction

This document is a guide to help your team evaluate and implement the ach_debit transfer type. It covers what the ach_debit functionalities are, how to get set up, and the key steps to go from initial testing to production. Use it as a reference while you integrate. When making POST requests Brale requires an Idempotency-Key header to be included and used on retries. Read more about idempotency keys in Brale. Using ach-debits required your business to be fully onboarded, and branded ach_debits are a premium feature.
  • Testnet Environment
    • If users wants to first test the below endpoints on testnet, they will need to create API credentials that are scoped to testnet - please follow the below link for more information:
  • Production Environment
    • Partners can leverage mainnet APIs by using their mainnet API keys generated in the Brale Portal.

​
End Customer Account Creation

  • Here is an example of how to get your account_id 
    curl --request GET \
  --url https://api.brale.xyz/accounts \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
  • Managed account model: where Partner’s end users can create an account under Partner account, where Partner will have access to those accounts. This will allow end users to view their account and transaction history for all onramp operations executed. The Partner will be able to execute onramp operations on behalf of the end users as well.
  • The following request is an example of how to create a Plaid Token that you will need to use next section when setting up addresses for funding your transactions. Specifically, you will want to store the link_token as this is the plaid token you will need to use in subsequent requests.
  • iOS/Android considerations (Plaid Link):
    • Your backend should create the link_token. Your mobile app uses the link_token to initialize Plaid Link.
    • Configure a redirect URI in your Plaid dashboard (and in your mobile app) so Plaid can return the user back to your app after they finish the Link flow.
    • Use either a custom URL scheme (e.g., myapp://plaid-redirect) or a universal/app link (e.g., https://example.com/plaid-redirect) depending on your app’s setup.
    • Make sure the redirect URI configured in Plaid exactly matches what the app is registered to handle, otherwise the Link handoff back to the app can fail.
curl --request POST \
  --url https://api.brale.xyz/accounts/{account_id}/plaid/link_token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "legal_name": "John Doe",
  "email_address": "user@example.com",
  "phone_number": "+1234567890",
  "date_of_birth": "1990-01-01"
}
'
Response Body Example: 
{
  "link_token": "link-sandbox-123456789",
  "expiration": "2024-01-01T12:00:00Z",
  "callback_url": "https://customer.com/webhooks/plaid-updates"
}
  • Your backend should call the endpoint indicated by callback_url (which is the Brale “register account” step) and pass the public_token (and your webhook URL, if applicable). This registers the bank account inside Brale and returns an address_id for subsequent transfers.

​
Setup addresses (Funding)

  • If the user wants to connect a financial institution to fund their stablecoin with, they will need to create an external address for it. The same goes for funding stablecoins with existing digital assets from an external wallet. When transferring to an external address (on-chain wallet or off-chain bank account), use:
  • POST /accounts/{account_id}/addresses/external
  • Include an Idempotency-Key header and a JSON body. Examples: On-chain wallet (e.g., Solana) request body example: 
    {
  "name": "User Solana Wallet",
  "address": "7xKXtg...",
  "transfer_types": ["solana"]
}
    Off-chain bank account request example:
    • Partner will need to create a form that requests this information from end users to provide the below data
    • Once the below data has been recorded, Brale will generate a “Address ID” that corresponds to the financial institution OR the external wallet, and for any future debit operations we will reference the “Address ID”. Create off-chain external address:
    curl --request POST \
  --url https://api.brale.xyz/accounts/{account_id}/addresses/external \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Operating Account (ACH Debit)",
  "transfer_types": [
    "ach_debit"
  ],
  "plaid_token": "PUBLIC_TOKEN_EXCHANGED_WITH_BRALE"
}
'

​
Requesting Mint/On-ramping

  • At this stage your end users’ accounts should already be connected, where Brale will execute debits and mint to desired stablecoins from the process below:
  • You will need to call the following below endpoints with the relevant data to be able to execute a swap or a transfer. POST https://api.brale.xyz/accounts/account_id/transfers
    • USDC to SBC request body example:
    {
  "amount": {
    "value": "100",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "USDC",
    "transfer_type": "Solana"
  },
  "destination": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4",
    "value_type": "SBC",
    "transfer_type": "Solana"
  }
}

    {
  "amount": {
    "value": "1",
    "currency": "USD"
  },
  "source": {
    "address_id": "2VcUIonJeVQzFoBuC7LdFT0dRe4", // address_id is the primitive, even for onchain sources
    "value_type": "USD",
    "transfer_type": "ach_debit"
  },
  "destination": {
    "address_id": "34yGFQf7tP1HJCPAWNGaN4rh4nX",
    "value_type": "SBC",
    "transfer_type": "polygon"
  },
  "brand": { "account_id": "34lCJZ2bxbPAzB3ou67Md01veUo" }
}