Add an external account

post

https://api.gravv.xyz/v1/external-accounts

Adds a new external account for transfers to accounts that are not created with Gravv.

Async setup contract

Registering an external account with our payment partners runs asynchronously. The response status code tells you the outcome:

200 OK: The external account is fully registered with at least one
partner. The status field is active. You can initiate transfers immediately.
202 Accepted: the external account record is created and a background
worker calls our partners. The status field is pending.
To learn when it changes to active, either check the status by calling
GET /v1/external-accounts/{external_account_id} until it is active, or
subscribe to the payee.setup.* webhook events.
400 Bad Request: Input validation failed. Fix the input and retry.

A duplicate POST with the same account_number (or iban), currency, and
payee_type for the same customer is idempotent and returns the existing
record.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

payee_type

string

enum

required

Type of payee

Allowed:

account_number

string

required

length ≤ 50

Bank account number

bank_name

string

length ≤ 100

Name of the bank

routing_number

string

required

length ≤ 20

9-digit ABA routing number

account_owner_type

string

enum

required

Type of account owner

Allowed:

account_type

string

enum

required

Type of bank account

Allowed:

currency

string

enum

required

Currency code

Allowed:

address

object

required

account_name

string

required

length ≤ 100

Name of the account holder.

customer_id

uuid

required

ID of the customer who owns the external account.

payment_rail

string | null

enum

Optional. US payment rail to use when payee_type is ach_wire. Accepted values: ach (ACH transfer) or wire (domestic wire). Defaults to wire when omitted.

Allowed:

Headers

x-tenant-id

string

required

Business/tenant identifier for authorization

Idempotency-Key

string

A unique key to prevent duplicate requests.

Responses

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The external account is fully registered with our payment partners. The status field is active.

400Validation failed.