---
title: "Remit funds to a recipient"
description: "Add an external recipient and transfer funds to them."
---

# Remit funds to a recipient

This recipe creates an external recipient, waits until the recipient is active, and transfers funds from a funded Gravv account.

Before you start, you need the sender's funded internal account ID and the recipient's Gravv customer ID. Both `POST` requests in this recipe require an `Idempotency-Key`. Use a new key for each operation and reuse it only when retrying the same operation with the same payload.

## Flow overview

```mermaid
sequenceDiagram
    autonumber
    actor Client
    participant API as Gravv API
    participant Rail as Payment rail

    Client->>API: Create external recipient
    API->>Rail: Set up recipient
    alt Recipient is immediately active
        API-->>Client: active
    else Setup is asynchronous
        API-->>Client: pending
        loop Until terminal status
            Client->>API: Retrieve external recipient
            API-->>Client: pending, active, or failed
        end
    end
    Client->>API: Transfer to active recipient
    API->>Rail: Submit payout
    API-->>Client: pending or completed
    opt Transfer is asynchronous
        Client->>API: Retrieve transfer status
        API-->>Client: completed or failed
    end
```

<Steps>
<Step title="Add the recipient">

Create an external account for the recipient. This example adds a US bank account; use the recipient type and fields required for your transfer corridor.

<RequestExample>
```bash title="Request"
curl --request POST \
  --url https://api.gravv.xyz/v1/external-accounts \
  --header 'Api-Key: <API_KEY>' \
  --header 'Idempotency-Key: recipient-<UUID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "payee_type": "ach_wire",
    "account_number": "000123456789",
    "account_name": "Amina Bello",
    "bank_name": "Example Community Bank",
    "currency": "USD",
    "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
    "routing_number": "000000000",
    "account_owner_type": "individual",
    "account_type": "savings",
    "address": {
      "address_line1": "1800 N Pole St",
      "city": "Orlando",
      "state": "US-FL",
      "postal_code": "32801",
      "country": "US"
    }
  }'
```
</RequestExample>

<ResponseExample>
```json title="Response"
{
  "data": {
    "id": "e0c0d076-fd86-4739-b26d-527ab83ab033",
    "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
    "account_name": "Amina Bello",
    "currency": "USD",
    "payee_type": "ach_wire",
    "status": "pending"
  },
  "error": null
}
```
</ResponseExample>

Save `data.id` as the external account ID. A `200` response can return `status: active`; a `202` response returns `status: pending` while setup continues.

</Step>

<Step title="Wait for the recipient to become active">

If setup is pending, retrieve the external account until its status becomes `active`. You can also subscribe to `payee.setup.*` webhook events.

<RequestExample>
```bash title="Request"
curl --request GET \
  --url https://api.gravv.xyz/v1/external-accounts/e0c0d076-fd86-4739-b26d-527ab83ab033 \
  --header 'Api-Key: <API_KEY>'
```
</RequestExample>

<ResponseExample>
```json title="Response"
{
  "data": {
    "id": "e0c0d076-fd86-4739-b26d-527ab83ab033",
    "status": "active"
  },
  "error": null
}
```
</ResponseExample>

</Step>

<Step title="Transfer funds to the recipient">

Use the active external account ID as the transfer destination.

<RequestExample>
```bash title="Request"
curl --request POST \
  --url https://api.gravv.xyz/v1/transfer \
  --header 'Api-Key: <API_KEY>' \
  --header 'Idempotency-Key: remittance-<UUID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": {
      "source_type": "internal_account",
      "id": "b9c2cb0d-e09a-496f-8655-d8c4b7aaf2f8"
    },
    "destination": {
      "destination_type": "external_account",
      "id": "e0c0d076-fd86-4739-b26d-527ab83ab033",
      "rail": "wire"
    },
    "amount": 150,
    "client_reference": "remittance-2026-001",
    "description": "Supplier payment",
    "customer_id": "bb6c6022-f1d8-492f-80f0-7547134bb42f"
  }'
```
</RequestExample>

<ResponseExample>
```json title="Response"
{
  "data": {
    "amount": "150",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "date_created": "2026-07-10T10:30:00Z",
    "transfer_status": "pending",
    "transaction_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "local_amount": null,
    "local_currency": null
  },
  "error": null
}
```
</ResponseExample>

Store the transfer reference and transaction ID for reconciliation. Track the final status through transfer webhooks or transaction retrieval.

</Step>
</Steps>

See [External Accounts](/platform/external-accounts/overview) for other recipient types and [Transfers](/platform/transfers/overview) for corridor-specific requirements.