HIFI Docs

An External Account is a bank account belonging to a Counter Party. Once registered, it can act as:

The destination for an Offramp - stablecoins converted and paid out to this account.
The source for an ACH-pull Onramp - HIFI debits this account to fund the onramp, instead of the user sending fiat in directly.

HIFI supports many payment rails (ACH, WIRE, RTP, SEPA, PIX, SWIFT, and others), each requiring a different set of fields. The rail is selected by the combination of bankAddress.country, currency, and transferType - not every combination is supported, so an unsupported combination is rejected with a validation error. For more details checkout Coverage and Account Information.

Counterparty requirements

The counterparty must be ACTIVE, and have the following accepted fields set in addition to its own minimum, before you can add an external account for them:

Counterparty type	Additional required fields
Individual	`address`
Business	`address`

For some corridors we may require additional information for the counterparty - for example, MXN and BRL, which require the counterparty’s taxId. See Account Information for more details.

If a required field is missing, HIFI rejects the request with ACTION_NOT_ALLOWED (422) - update the counterparty with the missing field and retry.

Add an external account

Registers a bank account for a counterparty. Requires an Idempotency-Key header. The example below is a US ACH account; other rails require different fields (e.g. iban + swiftCode for SEPA, pixKey for PIX). Request

curl -X POST https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-accounts \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "transferType": "WIRE",
    "currency": "USD",
    "accountNumber": "000123456789",
    "routingNumber": "021000021",
    "accountType": "CHECKING",
    "bankName": "Chase"
  }'

Response

{
    "id": "extacct_UFvAKwZc530MxRZXnk1vF",
    "userId": "usr_x1y2z3",
    "counterPartyId": "cpty_a1b2c3",
    "accountNumber": "****6789",
    "routingNumber": "021000021",
    "accountType": "CHECKING",
    "iban": null,
    "swiftCode": null,
    "sortCode": null,
    "pixKey": null,
    "phoneNumber": null,
    "bankName": "Chase",
    "bankAddress": null,
    "currency": "USD",
    "transferType": "WIRE",
    "fpsId": null,
    "clabe": null,
    "status": "ACTIVE",
    "createdAt": "2026-07-25T19:34:48.798Z",
    "updatedAt": "2026-07-25T19:34:48.798Z"
}

Sensitive fields (accountNumber, iban, pixKey, etc.) are returned masked to the last 4 characters on every read after creation.

Deactivate an external account

Revokes a previously-added bank account. A deactivated account can no longer be used as an offramp destination or onramp source, but its record and history are preserved. Request

curl -X DELETE https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-accounts/extacct_QW1e2r3t4y \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "id": "extacct_UFvAKwZc530MxRZXnk1vF",
    "userId": "usr_x1y2z3",
    "counterPartyId": "cpty_a1b2c3",
    "accountNumber": "****6789",
    "routingNumber": "021000021",
    "accountType": "CHECKING",
    "iban": null,
    "swiftCode": null,
    "sortCode": null,
    "pixKey": null,
    "phoneNumber": null,
    "bankName": "Chase",
    "bankAddress": null,
    "currency": "USD",
    "transferType": "WIRE",
    "fpsId": null,
    "clabe": null,
    "status": "INACTIVE",
    "createdAt": "2026-07-25T19:34:48.798Z",
    "updatedAt": "2026-07-25T19:34:48.798Z"
}

Retrieve a counterparty’s external accounts

List a counterparty’s registered bank accounts, optionally filtered by status, transferType, or currency. Request

curl https://sandbox.hifi.com/v3/users/usr_x1y2z3/counter-parties/cpty_a1b2c3/external-accounts?limit=10&transferType=WIRE&currency=USD \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "data": [
        {
            "id": "extacct_UFvAKwZc530MxRZXnk1vF",
            "userId": "usr_x1y2z3",
            "counterPartyId": "cpty_a1b2c3",
            "accountNumber": "****6789",
            "routingNumber": "021000021",
            "accountType": "CHECKING",
            "iban": null,
            "swiftCode": null,
            "sortCode": null,
            "pixKey": null,
            "phoneNumber": null,
            "bankName": "Chase",
            "bankAddress": null,
            "currency": "USD",
            "transferType": "WIRE",
            "fpsId": null,
            "clabe": null,
            "status": "INACTIVE",
            "createdAt": "2026-07-25T19:34:48.798Z",
            "updatedAt": "2026-07-25T19:34:48.798Z"
        }
    ],
    "pagination": {
        "hasMore": false,
        "startCursor": "extacct_UFvAKwZc530MxRZXnk1vF",
        "endCursor": "extacct_UFvAKwZc530MxRZXnk1vF"
    }
}

Using an external account as an onramp source

Instead of a user sending fiat in directly, an onramp can be funded by pulling from a counterparty’s external account - pass source.externalAccountId instead of source.userId when creating the onramp. See Onramp for the full request shape.

ACH-pull funding only works with transferType: "ACH" accounts, and the onramp’s source.currency must match the external account’s currency.

ACH-pull is only available to a restricted set of customers - contact HIFI support for more information.

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Counterparty Overview - Counterparty resources
Counter Party - Create and manage recipients/payers
External Card - Cards for a counterparty

Introduction

Core concepts

Features

Compliance

Payments

References

External Account

Counterparty requirements

Add an external account

Deactivate an external account

Retrieve a counterparty’s external accounts

Using an external account as an onramp source

Getting Help

​Counterparty requirements

​Add an external account

​Deactivate an external account

​Retrieve a counterparty’s external accounts

​Using an external account as an onramp source

​Getting Help

​Related Resources

Counterparty requirements

Add an external account

Deactivate an external account

Retrieve a counterparty’s external accounts

Using an external account as an onramp source

Getting Help

Related Resources