Manage Recipients

Before You Start

Read the following guides before proceeding:

Update Recipient Personal Info

Update a recipient's personal information (name, business status, nickname).

Endpoint

PUT /api/v1/recipients/{recipient_id}

Path Parameters

Request

{
  "first_name": "Alex",
  "last_name": "Smith",
  "is_business": false,
  "nick_name": "Alex's Card"
}

*Provide either first_name + last_name for personal recipients, or company_name for business recipients.

Response

{
  "id": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35",
  "personal_info": {
    "first_name": "Alex",
    "last_name": "Smith",
    "is_business": false,
    "nick_name": "Alex's Card"
  },
  "payment_details": [...]
}

Update Recipient and Payment Details (v2)

Replaces both the personal info and one payment detail in a single call. The v1 endpoint above
updates personal info only; v2 avoids the two-call sequence when a recipient's bank details change
alongside their name.

Endpoint

PUT /api/v2/recipients/{recipient_id}

Path Parameters

Request

{
  "first_name": "Alex",
  "last_name": "Grey",
  "is_business": false,
  "nick_name": "My Crypto Wallet",
  "type": "Crypto",
  "currencies": ["EUR", "USDT"],
  "crypto": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "network": "Base"
  }
}

The type-specific object is not optional despite the omitempty shape — omitting the one that
matches type fails with {type}: {type} is required for selected type and an issue detail of
missing_for_type.

Response

Returns the full recipient, same shape as the v1 update response.

Update Payment Details

Update a specific payment detail on a recipient.

Endpoint

PUT /api/v1/recipients/{recipient_id}/payment_details/{payment_details_id}

Path Parameters

Request

The request body depends on the payment type. Include only the fields to update.

Update SEPA Details

{
  "type": "Sepa",
  "currencies": ["EUR"],
  "sepa": {
    "iban": "DE89370400440532013001",
    "bic": "COBADEFFXXX"
  }
}

Update ACH Details

{
  "type": "Ach",
  "currencies": ["USD"],
  "ach": {
    "routing_number": "021000021",
    "account_number": "987654321",
    "bank_name": "Bank of America",
    "legal_address": {
      "country": "US",
      "city": "Los Angeles",
      "zip_code": "90001",
      "line1": "456 Oak Avenue",
      "state": "CA"
    }
  }
}

Response

{
  "id": "c34908da-d980-4a9c-9b39-4dabd6f6144e"
}

Delete Payment Details

Remove a specific payment detail from a recipient.

Endpoint

DELETE /api/v1/recipients/{recipient_id}/payment_details/{payment_details_id}

Path Parameters

Response

204 No Content

Delete Recipient

Remove a recipient and all its payment details.

Endpoint

DELETE /api/v1/recipients/{recipient_id}

Path Parameters

Response

204 No Content

Browse Recipients by Catalog Index

Returns recipients whose full name begins with a given letter — a phone-book index rather than a
search. For free-text matching use the recipients list endpoint's filters.

Endpoint

GET /api/v1/recipients/filter/catalog

Query Parameters

Sorting by usage surfaces the recipients the user actually pays — see
Record Recipient Usage for how that counter is maintained.

Record Recipient Usage

Increments a recipient's usage counter. The counter drives recipient ordering when sort=usage is
requested.

Endpoint

POST /api/v1/recipients/{recipient_id}/usage

Path Parameters

No request body. The counter is not incremented automatically when you send a transfer — call
this endpoint yourself at the point the user selects a recipient, or usage-sorted lists stay flat.

Recipient Webhook

When a recipient is created, updated, or deleted, a webhook is delivered.

Endpoint: POST {base_url}/v2/webhooks/recipients

Recipient Created/Updated

{
  "id": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35",
  "personal_info": {
    "first_name": "Alex",
    "last_name": "Grey",
    "is_business": false
  },
  "payment_details": [
    {
      "id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
      "type": "Card",
      "currencies": ["EUR", "USD"],
      "card": {
        "card_id": "tok_a1b2c3d4e5f6789012345678",
        "card_pan_last": "4242"
      }
    }
  ]
}

Error Handling

Every operation on this page is scoped to the caller identified by X-User-Wallet. A recipient belonging
to another user is not distinguishable from one that does not exist — both return the recipient
not-found error below. There is no separate authorization error and no 403.

These endpoints never return 404.

Path Parameter Errors (400)

Raised before the recipient is looked up.

{
  "error_reason": "ErrorInvalidField",
  "error_description": "recipient id must be a valid UUID",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "recipient_id" },
    { "key": "issue", "details": "invalid_uuid" },
    { "key": "recipient_id", "details": "recipient id must be a valid UUID" }
  ]
}

Recipient Not Found (400)

The recipient does not exist, or is not owned by the caller. Returned by all four operations.

{
  "error_reason": "ErrorNotFound",
  "error_description": "Entity not found",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "recipient" }
  ]
}

Payment Details Not Found (500)

The recipient exists, but it has no payment details with the given payment_details_id.

This case is returned as a 500 under CategoryInternalFailure, not a 400, even though the reason
is ErrorNotFound. Branch on error_reason, not on the status code — a 500 here does not mean the
request should be retried.

PUT .../payment_details/{payment_details_id}:

{
  "error_reason": "ErrorNotFound",
  "error_description": "Failed to update recipient details",
  "error_category": {
    "category": "CategoryInternalFailure",
    "http_status_code": 500
  },
  "error_details": [
    { "key": "requested_id", "details": "c56428d0-e1ce-4c4e-a9ca-63bb0f668d00" }
  ]
}

DELETE .../payment_details/{payment_details_id} returns the same category and reason with the
description Requested details not found and no error_details.

Validation Errors (400)

Payment details submitted on update are validated per type. A malformed field returns ErrorGeneral with
Request failed validation and the offending field in error_details. See
Create Recipients for the per-type field rules.

Server Errors (500)