curl --request POST \
  --url https://api.sand.etherfuse.com/organization/{organizationId}/payment_account \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "bank",
  "label": "Operating account",
  "country": "MX",
  "currency": "MXN",
  "accountDetails": {
    "kind": "clabe",
    "clabe": "012180000000000002"
  },
  "registrationInfo": {
    "accountHolderName": "Ejemplo Comercial SA de CV",
    "taxId": "XAXX010101000"
  }
}
'

{
  "id": "3f9a2c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "status": "pending",
  "label": "Operating account",
  "rails": {
    "spei": {
      "currency": "MXN",
      "source": {
        "isDefault": true,
        "status": "ready"
      },
      "destination": {
        "isDefault": true,
        "status": "pending"
      }
    }
  },
  "createdAt": "2026-09-28T17:04:11.482Z"
}

{
  "id": "3f9a2c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "status": "pending",
  "label": "Operating account",
  "rails": {
    "spei": {
      "currency": "MXN",
      "source": {
        "isDefault": true,
        "status": "ready"
      },
      "destination": {
        "isDefault": true,
        "status": "pending"
      }
    }
  },
  "createdAt": "2026-09-28T17:04:11.482Z"
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

Payment Accounts

Register payment account

Registers a bank account or wallet for the organization in the route and returns it with its per-rail readiness.

State where the account lives in one of two ways:

Bank account: set kind to bank, send country and currency (for example MX and MXN), and describe the account in accountDetails (for example a clabe).
Wallet: set kind to wallet and send accountDetails of kind address with its chain. Do not send country or currency for a wallet. A wallet requires no registrationInfo, and we ignore any you send.

Registering does not prove that the customer owns the account.

Registration info. A bank account route requires holder fields such as accountHolderName and taxId. We fill each one from the organization’s verified identity when we hold it. When a required field is still missing, the request fails with 422 registration-info-required, and the problem lists every required field in required and the ones still needed in missing, as JSON Pointers into the request (for example #/registrationInfo/taxId). Send the missing fields in registrationInfo and retry. A supplied taxId must match the verified one (422 holder-tax-id-mismatch).

You can send any registration field, including ones this route does not require; we check each value’s format and ignore the fields the route does not use. A name that is not a registration field returns 400 validation-error.

Readiness. A new account starts pending, and so does each rail direction. We register it with the payment provider, then move each direction to ready or rejected. Subscribe to paymentAccountUpdated, or read the account again, and quote a direction once it is ready.

Registering an account again. If the organization already holds the account, you get it back with 200. When a direction was rejected, we register the account with the provider again using the registrationInfo you send, and those directions go back to pending. Otherwise we change nothing. If another organization holds it, the request fails with 409 payment-account-unavailable.

POST

organization

{organizationId}

payment_account

curl --request POST \
  --url https://api.sand.etherfuse.com/organization/{organizationId}/payment_account \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "bank",
  "label": "Operating account",
  "country": "MX",
  "currency": "MXN",
  "accountDetails": {
    "kind": "clabe",
    "clabe": "012180000000000002"
  },
  "registrationInfo": {
    "accountHolderName": "Ejemplo Comercial SA de CV",
    "taxId": "XAXX010101000"
  }
}
'

{
  "id": "3f9a2c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "status": "pending",
  "label": "Operating account",
  "rails": {
    "spei": {
      "currency": "MXN",
      "source": {
        "isDefault": true,
        "status": "ready"
      },
      "destination": {
        "isDefault": true,
        "status": "pending"
      }
    }
  },
  "createdAt": "2026-09-28T17:04:11.482Z"
}

{
  "id": "3f9a2c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "status": "pending",
  "label": "Operating account",
  "rails": {
    "spei": {
      "currency": "MXN",
      "source": {
        "isDefault": true,
        "status": "ready"
      },
      "destination": {
        "isDefault": true,
        "status": "pending"
      }
    }
  },
  "createdAt": "2026-09-28T17:04:11.482Z"
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

{
  "type": "https://docs.etherfuse.com/ramp/v2/errors/quote-expired",
  "title": "Quote expired",
  "status": 400,
  "detail": "quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist",
  "instance": "tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "errors": [
    {
      "pointer": "#/accountDetails/clabe",
      "detail": "This field is required."
    }
  ],
  "required": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

API key sent in the Authorization header, with no Bearer prefix.

Path Parameters

organizationId

string<uuid>

required

The organization this call acts for: your API key's organization or one of its customer organizations. Any other id returns 404 not-found.

Body

application/json

kind

enum<string>

required

The kind of account. embeddedWallet is a wallet we create on a chain; see Embedded wallets. debitCard and cash return 422 unsupported.

Available options:

bank,

wallet,

embeddedWallet,

debitCard,

cash

label

string

required

Your organization's name for the account. Must not be blank. We trim it. A label that contains <, >, ;, {, }, a backtick, |, \, $(, ../ or a control character returns 400.

Example:

"Operating account"

accountDetails

clabe · object

required

The identifier that names the account, tagged by kind. The kind decides the field set: send exactly the fields your kind declares. A missing field or a field the kind does not declare returns 400 validation-error with a pointer per field.

clabe
pixKey
address
signerPublicKey

Show child attributes

country

string

Two-letter country code of the account's market. Send with currency for a bank account. Omit for a wallet.

Example:

"MX"

currency

string

Three-letter currency code of the account's market. Send with country for a bank account. Omit for a wallet.

Example:

"MXN"

registrationInfo

object

Account holder information a bank account route requires. The route and the organization's account type (personal or business) decide which fields are required: accountHolderName and taxId for bank accounts, plus the personal or business fields on routes that need them. We fill a field from the organization's verified identity when we hold it, so you only need to send the fields a registration-info-required problem lists in missing. You may send other registration fields too: we check their format and ignore the ones the route does not use. A name that is not listed here returns 400 validation-error. A text value that contains <, >, ;, {, }, a backtick, |, \, $(, ../ or a control character returns 400 invalid-request. Wallets require no fields.

Show child attributes

Response

The organization already holds this account. Returns it. A rejected direction is registered again and returns as pending.

string<uuid>

required

status

enum<string>

required

The account as a whole. ready when any rail direction is ready. rejected when every rail direction is rejected; register the account again with corrected registrationInfo to retry. disabled when we turned the account off; it cannot be registered or quoted. Otherwise pending. Readiness per rail and direction is in rails.

Available options:

pending,

ready,

rejected,

disabled

label

string

required

Your organization's name for the account.

rails

object

required

The rails this account can move money on, keyed by rail name (a PaymentRail value such as spei or stellar). A rail the account cannot move money on is absent. The account identifier you registered is not returned.

Show child attributes

createdAt

string<date-time>

required

User Authentication

Payment Accounts

Quotes

Orders

Webhook Subscriptions

Webhook Events

Organizations

Members

KYC

KYB

Assets

Statements

Sandbox

Lookup API

Register payment account

Authorizations

Path Parameters

Body

Response