Skip to main content

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​

FieldTypeDescription
aliasstringA custom name for the account to help identify it.
descriptionstringA brief description of the bank account.
bankAccountNumberstringThe bank account number.
bankRoutingNumberstringThe bank routing number (ABA routing number).
bankBeneficiaryNamestringThe full name of the account holder.
bankNamestringThe name of the bank.
beneficiaryAddressobjectThe address of the beneficiary.

Address Object Fields​

FieldTypeDescription
streetLine1stringThe street address.
citystringThe city.
statestringThe state or province.
postalCodestringThe postal or ZIP code.
countrystringThe 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​

FieldTypeDescription
subAccountIdstringThe ID of a sub-account. If provided, data will be fetched for the sub-account; leave empty for main account.
createdAfterint64Filters results to include only those created after this timestamp.
createdBeforeint64Filters results to include only those created before this timestamp.
cursorstringCursor for pagination. Pass the value from the previous response to retrieve the next set of results.
aliasstringFilters 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.