Bank Account USD

Introduction

USD Bank Account is used as the destination bank account when you off-ramp to USD fiat through WIRE or ACH. In order to receive money into your USD bank account, you need to register it here first and then reference it in tickets that send USD out to a bank.

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

Register a USD Beneficiary Account

Let's take a look at the data needed to create your USD bank account:

HTTP POST Request

Endpoint:

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/

cURL Example:

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "alias": "Primary business checking account",
  "description": "Primary business checking account for USD transactions",
  "bankAccountNumber": "581984177591",
  "bankRoutingNumber": "721738952",
  "bankBeneficiaryName": "John Smith",
  "bankName": "JPMorgan Chase Bank N.A.",
  "beneficiaryAddress": {
    "streetLine1": "123 Main Street",
    "streetLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}'

Fields

Field	Type	Required	Description
alias	string	Yes (1–100 chars)	Custom name to identify the account.
description	string	No (max 255 chars)	Brief description of the bank account.
bankAccountNumber	string	Yes	Bank account number.
bankRoutingNumber	string	Yes	ABA routing number.
bankBeneficiaryName	string	Yes	Full name of the account holder.
bankName	string	Yes	Name of the bank.
beneficiaryAddress	object	Yes	Structured address of the beneficiary (see below).

Address Object Fields

Schema Note

beneficiaryAddress is a structured object, not a plain string. All fields below are required except streetLine2.

Field	Type	Required	Description
streetLine1	string	Yes	Street address line 1.
streetLine2	string	No	Apartment, suite, unit, etc.
city	string	Yes	City.
state	string	Yes	State or province.
postalCode	string	Yes	Postal or ZIP code.
country	string	Yes	Country code (e.g., "USA").

Sample JSON Body

{
  "alias": "Primary business checking account",
  "description": "Primary business checking account for USD transactions",
  "bankAccountNumber": "581984177591",
  "bankRoutingNumber": "721738952",
  "bankBeneficiaryName": "John Smith",
  "bankName": "JPMorgan Chase Bank N.A.",
  "beneficiaryAddress": {
    "streetLine1": "123 Main Street",
    "streetLine2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}

JSON Response

{
  "id": "00000000-0000-0000-0000-000000000000"
}

List all USD beneficiaries bank accounts

To get all the USD bank accounts, let's use the endpoint below, with filter fields:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/

Filter Fields

Field	Type	Description
subAccountId	string	The ID of a sub-account. If provided, data will be fetched for the sub-account; leave empty for main account.
createdAfter	int64	Filters results to include only those created after this timestamp.
createdBefore	int64	Filters results to include only those created before this timestamp.
cursor	string	Cursor for pagination. Pass the value from the previous response to retrieve the next set of results.
alias	string	Filters results to include only those with the specified alias.

cUrl Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/?subAccountId=&createdAfter=1700000000&createdBefore=1800000000&cursor=NEXT_CURSOR&alias=John Primary Account" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "bankAccounts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "userId": "11111111-1111-1111-1111-111111111111",
      "alias": "Primary business checking account",
      "description": "Primary business checking account for USD transactions",
      "bankAccountNumber": "581984177591",
      "bankRoutingNumber": "721738952",
      "bankBeneficiaryName": "John Smith",
      "bankName": "JPMorgan Chase Bank N.A.",
      "beneficiaryAddress": {
        "streetLine1": "123 Main Street",
        "streetLine2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "USA"
      },
      "createdAt": "2025-02-20T15:13:08.320462Z"
    }
  ],
  "cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}

Get USD beneficiary bank account by ID

To retrieve the details of a specific USD bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/00000000-0000-0000-0000-000000000000

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "bankAccount": {
    "id": "00000000-0000-0000-0000-000000000000",
    "userId": "11111111-1111-1111-1111-111111111111",
    "alias": "Primary business checking account",
    "description": "Primary business checking account for USD transactions",
    "bankAccountNumber": "581984177591",
    "bankRoutingNumber": "721738952",
    "bankBeneficiaryName": "John Smith",
    "bankName": "JPMorgan Chase Bank N.A.",
    "beneficiaryAddress": {
      "streetLine1": "123 Main Street",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "USA"
    },
    "createdAt": "2025-02-20T15:13:08.320462Z"
  }
}

Delete USD beneficiary bank Account

To delete a specific USD bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP DELETE Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/00000000-0000-0000-0000-000000000000

cUrl Example

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/usd/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Your USD bank account has been deleted!

Conclusion

In this section, you have learned how to manage USD bank accounts within the Avenia API system.

What we've covered:

• ✅ Creating a USD Bank Account – Register a new USD bank account for WIRE/ACH transfers.
• ✅ Fetching All USD Bank Accounts – Retrieve all your USD bank accounts.
• ✅ Fetching a Specific USD Bank Account by ID – Retrieve details by UUID.
• ✅ Deleting a USD Bank Account – Permanently remove a USD bank account.

By following these steps, you now have full control over your USD bank accounts within Avenia API. You can now use the returned beneficiaryUsdBankAccountId when creating output tickets that off-ramp USD to a bank.