Beneficiary Management

Beneficiaries are saved payment destinations that make it easier to send funds without having to enter addresses or payment details every time. The system supports two types of beneficiaries: onchain (blockchain addresses) and offchain (PIX keys). This guide covers how to create, retrieve, update, and delete beneficiaries.

Overview

The beneficiary system allows you to save frequently used payment destinations:

Onchain Beneficiaries - Blockchain wallet addresses (EVM or BTC networks)
Offchain Beneficiaries - PIX payment keys (email, phone, CPF, CNPJ, or random key)
CRUD Operations - Full create, read, update, and delete functionality
Multiple Beneficiaries - Save as many beneficiaries as you need

Prerequisites

Before managing beneficiaries, ensure you have:

Completed authentication and have a valid access token
Created a wallet (may be required for certain operations)

Onchain Beneficiaries

Onchain beneficiaries are blockchain wallet addresses that can receive cryptocurrency transfers.

Get Onchain Beneficiaries

Retrieve all your saved onchain beneficiaries.

Get onchain beneficiaries

curl -X GET https://api.example.com/api/beneficiary/onchain \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Onchain beneficiaries fetched successfully",
  "data": {
    "beneficiaries": [
      {
        "id": "beneficiary-id",
        "client_id": "client-id",
        "address": "0x1234567890123456789012345678901234567890",
        "network": "EVM",
        "name": "My Wallet",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

Create Onchain Beneficiary

Create a new onchain beneficiary by providing a wallet address, network type, and a name.

Create onchain beneficiary

curl -X POST https://api.example.com/api/beneficiary/onchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "address": "0x1234567890123456789012345678901234567890",
    "network": "EVM",
    "name": "My Wallet"
  }'

Required Fields:

address - Wallet address (must be valid for the specified network)
network - Network type: "EVM" or "BTC"
name - A friendly name to identify this beneficiary

Response:

{
  "status": 201,
  "message": "Onchain beneficiary created successfully",
  "data": {
    "beneficiary": {
      "id": "beneficiary-id",
      "client_id": "client-id",
      "address": "0x1234567890123456789012345678901234567890",
      "network": "EVM",
      "name": "My Wallet",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  }
}

Update Onchain Beneficiary

Update an existing onchain beneficiary.

Update onchain beneficiary

curl -X PUT https://api.example.com/api/beneficiary/onchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "address": "0x9876543210987654321098765432109876543210",
    "network": "EVM",
    "name": "Updated Wallet Name"
  }'

Required Fields:

address - Updated wallet address (must be valid for the specified network)
network - Network type: "EVM" or "BTC"
name - Updated friendly name

Response:

{
  "status": 200,
  "message": "Onchain beneficiary updated successfully",
  "data": {
    "beneficiary": {
      "id": "beneficiary-id",
      "client_id": "client-id",
      "address": "0x9876543210987654321098765432109876543210",
      "network": "EVM",
      "name": "Updated Wallet Name",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-02T00:00:00.000Z"
    }
  }
}

Delete Onchain Beneficiary

Delete an onchain beneficiary by its ID.

Delete onchain beneficiary

curl -X DELETE https://api.example.com/api/beneficiary/onchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 202,
  "message": "Onchain beneficiary deleted successfully"
}

Offchain Beneficiaries

Offchain beneficiaries are PIX payment keys used for Brazilian instant payments.

Get Offchain Beneficiaries

Retrieve all your saved offchain (PIX) beneficiaries.

Get offchain beneficiaries

curl -X GET https://api.example.com/api/beneficiary/offchain \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Offchain beneficiaries fetched successfully",
  "data": {
    "beneficiaries": [
      {
        "id": "beneficiary-id",
        "client_id": "client-id",
        "pix_type": "EMAIL",
        "pix_key": "user@example.com",
        "name": "John Doe",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

Create Offchain Beneficiary

Create a new offchain (PIX) beneficiary.

Create offchain beneficiary

curl -X POST https://api.example.com/api/beneficiary/offchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "pixType": "EMAIL",
    "pixKey": "user@example.com",
    "name": "John Doe"
  }'

Required Fields:

pixType - Type of PIX key: "EMAIL", "PHONE", "CPF", "CNPJ", or "EVP"
pixKey - The PIX key value (must match the type)
name - A friendly name to identify this beneficiary

PIX Key Types:

EMAIL - Email address (e.g., user@example.com)
PHONE - Phone number with country code (e.g., +5511999999999)
CPF - Brazilian tax ID (11 digits, e.g., 12345678900)
CNPJ - Brazilian company tax ID (14 digits, e.g., 12345678000190)
EVP - Random key (UUID format, e.g., 123e4567-e89b-12d3-a456-426614174000)

Response:

{
  "status": 201,
  "message": "Offchain beneficiary created successfully",
  "data": {
    "beneficiary": {
      "id": "beneficiary-id",
      "client_id": "client-id",
      "pix_type": "EMAIL",
      "pix_key": "user@example.com",
      "name": "John Doe",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  }
}

Update Offchain Beneficiary

Update an existing offchain beneficiary.

Update offchain beneficiary

curl -X PUT https://api.example.com/api/beneficiary/offchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "pixType": "PHONE",
    "pixKey": "+5511999999999",
    "name": "Updated Name"
  }'

Required Fields:

pixType - Updated type of PIX key
pixKey - Updated PIX key value
name - Updated friendly name

Response:

{
  "status": 200,
  "message": "Offchain beneficiary updated successfully",
  "data": {
    "beneficiary": {
      "id": "beneficiary-id",
      "client_id": "client-id",
      "pix_type": "PHONE",
      "pix_key": "+5511999999999",
      "name": "Updated Name",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-02T00:00:00.000Z"
    }
  }
}

Delete Offchain Beneficiary

Delete an offchain beneficiary by its ID.

Delete offchain beneficiary

curl -X DELETE https://api.example.com/api/beneficiary/offchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 202,
  "message": "Offchain beneficiary deleted successfully"
}

Network Types (Onchain)

EVM Networks

EVM (Ethereum Virtual Machine) networks include:

Ethereum
Polygon
BSC (Binance Smart Chain)
Arbitrum
Optimism
And other EVM-compatible chains

Address Format: 0x followed by 40 hexadecimal characters (42 characters total)

Example: 0x1234567890123456789012345678901234567890

BTC Network

Bitcoin network addresses can be:

Legacy addresses (starting with 1)
SegWit addresses (starting with 3)
Bech32 addresses (starting with bc1)

Examples:

Legacy: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
SegWit: 3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy
Bech32: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4

PIX Key Types (Offchain)

EMAIL

Format: Valid email address
Example: user@example.com
Validation: Standard email format

PHONE

Format: Phone number with country code
Example: +5511999999999 (Brazil)
Validation: Must include country code

CPF

Format: 11 digits (Brazilian individual tax ID)
Example: 12345678900
Validation: Must be exactly 11 digits

CNPJ

Format: 14 digits (Brazilian company tax ID)
Example: 12345678000190
Validation: Must be exactly 14 digits

EVP (Random Key)

Format: UUID format
Example: 123e4567-e89b-12d3-a456-426614174000
Validation: Standard UUID format

Error Handling

Invalid Wallet Type

{
  "status": 400,
  "message": "Invalid wallet type"
}

This error occurs when the network type is not "EVM" or "BTC".

Invalid Wallet Address

{
  "status": 400,
  "message": "EVM wallet address is invalid"
}

{
  "status": 400,
  "message": "BTC wallet address is invalid"
}

This error occurs when the wallet address format is invalid for the specified network.

Invalid PIX Key Type

{
  "status": 400,
  "message": "Invalid pix key type"
}

This error occurs when the PIX key type is not one of the allowed values: "EMAIL", "PHONE", "CPF", "CNPJ", or "EVP".

Complete Flow Example

Here's a complete example of managing beneficiaries:

# 1. Create onchain beneficiary (EVM)
curl -X POST https://api.example.com/api/beneficiary/onchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "address": "0x1234567890123456789012345678901234567890",
    "network": "EVM",
    "name": "My Ethereum Wallet"
  }'

# 2. Create onchain beneficiary (BTC)
curl -X POST https://api.example.com/api/beneficiary/onchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "BTC",
    "name": "My Bitcoin Wallet"
  }'

# 3. Create offchain beneficiary (PIX Email)
curl -X POST https://api.example.com/api/beneficiary/offchain \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "pixType": "EMAIL",
    "pixKey": "user@example.com",
    "name": "John Doe"
  }'

# 4. Get all onchain beneficiaries
curl -X GET https://api.example.com/api/beneficiary/onchain \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 5. Get all offchain beneficiaries
curl -X GET https://api.example.com/api/beneficiary/offchain \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 6. Update onchain beneficiary
curl -X PUT https://api.example.com/api/beneficiary/onchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "address": "0x9876543210987654321098765432109876543210",
    "network": "EVM",
    "name": "Updated Wallet Name"
  }'

# 7. Delete beneficiary
curl -X DELETE https://api.example.com/api/beneficiary/onchain/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Important Notes

Address Validation: All wallet addresses are validated before being saved. Invalid addresses will be rejected.
Network Types: Onchain beneficiaries support two network types: "EVM" (for Ethereum and compatible chains) and "BTC" (for Bitcoin).
PIX Key Validation: PIX keys are validated according to their type. Make sure the key format matches the selected type.
Multiple Beneficiaries: You can create as many beneficiaries as needed. There's no limit on the number of beneficiaries.
Name Field: The name field is for your convenience only. It helps you identify beneficiaries but doesn't affect validation.
Ownership: Beneficiaries are tied to your account. You can only manage your own beneficiaries.
Update vs Create: Use PUT to update existing beneficiaries and POST to create new ones. The ID in the URL identifies which beneficiary to update.
Deletion: Deleting a beneficiary is permanent. Make sure you want to remove it before deleting.
Use Cases: Beneficiaries are typically used when making transfers to avoid entering addresses or PIX keys repeatedly.
Security: Always verify beneficiary addresses and PIX keys before using them for transfers. The system validates format but doesn't verify ownership.