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 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

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)