Manage Recipients

Before You Start

Read the following guides before proceeding:

Guide	Why
Getting Started	Platform overview and setup
Api Basics	Required headers and request configuration
Authentication	How to obtain access tokens
Onboarding	User and wallet registration

Update Recipient Personal Info

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

Endpoint

PUT /api/v1/recipients/{recipient_id}

Path Parameters

Parameter	Type	Required	Description
`recipient_id`	string (UUID)	Yes	Recipient identifier

Request

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

Field	Type	Required	Description
`first_name`	string	Yes*	First name (personal recipients)
`last_name`	string	Yes*	Last name (personal recipients)
`company_name`	string	Yes*	Company name (business recipients)
`is_business`	boolean	Yes	`false` for personal, `true` for business
`nick_name`	string	No	Optional display name

*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

Parameter	Type	Required	Description
`recipient_id`	string (UUID)	Yes	Recipient identifier
`payment_details_id`	string (UUID)	Yes	Payment details identifier

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

Parameter	Type	Required	Description
`recipient_id`	string (UUID)	Yes	Recipient identifier
`payment_details_id`	string (UUID)	Yes	Payment details identifier

Response

204 No Content

Delete Recipient

Remove a recipient and all its payment details.

Endpoint

DELETE /api/v1/recipients/{recipient_id}

Path Parameters

Parameter	Type	Required	Description
`recipient_id`	string (UUID)	Yes	Recipient identifier

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

Error Reason	Description
`ErrorNotFound`	Recipient or payment details not found
`ErrorInvalidField`	Invalid UUID format
`ErrorMissingField`	Required field not provided
`ErrorPermissionDenied`	Recipient not owned by user

Error Response Format

{
  "error_reason": "ErrorNotFound",
  "error_description": "Recipient not found",
  "error_category": {
    "category": "CategoryNotFound",
    "http_status_code": 404
  },
  "error_details": [
    {
      "key": "recipient_id",
      "details": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35"
    }
  ]
}