Recipient Management

Overview

Recipients represent destination accounts where funds can be sent. Each recipient is linked to a specific user and contains the bank account or wallet information needed to process payouts.

Create a Recipient

Endpoint

POST /v1/recipients

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token from authentication
`x-api-key`	Yes	Your API key
`Content-Type`	Yes	Must be `application/json`
`idempotency-key`	Yes	UUID to prevent duplicate creation

Request Body

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+12025551234",
  "address": "123 Main St, San Francisco, CA 94105",
  "account": {
    "account_type": "ACH",
    "routing_number": "021000021",
    "account_number": "123456789",
    "type": "checking",
    "bank_name": "JPMorgan Chase",
    "bank_address": "383 Madison Ave, New York, NY 10179",
    "doc_type": "passport",
    "doc_number": "AB1234567"
  }
}

Base Request Fields

Field	Type	Required	Description
`user_id`	string (UUID)	Yes	The user who owns this recipient
`type`	string	No	`"individual"` or `"business"`. Defaults to `"individual"`
`first_name`	string	Conditional	Required for individual recipients
`middle_name`	string	No	Optional middle name
`last_name`	string	Conditional	Required for individual recipients
`company_name`	string	Conditional	Required for business recipients
`email`	string	Conditional	Required for ACH, WIRE, SWIFT accounts
`phone`	string	Conditional	Required for SWIFT accounts (max 16 chars)
`address`	string	Conditional	Required for ACH, WIRE, SWIFT accounts
`account`	object	Yes	Account details (varies by type)

Recipient Type Rules

Individual (default):

Requires first_name AND last_name
type defaults to "individual"

Business:

Set type: "business" explicitly, OR
Provide company_name field, OR
Use business document type (e.g., doc_type: "nit" for PSE)

Response

{
  "recipient_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+12025551234",
  "address": "123 Main St, San Francisco, CA 94105",
  "account_type": "ACH",
  "account_details": {
    "routing_number": "021000021",
    "account_number": "123456789",
    "type": "checking",
    "bank_name": "JPMorgan Chase",
    "bank_address": "383 Madison Ave, New York, NY 10179",
    "doc_type": "passport",
    "doc_number": "AB1234567"
  },
  "created_ts": "2024-01-15T10:30:00Z",
  "updated_ts": "2024-01-15T10:30:00Z"
}

Response Fields

Field	Description
`recipient_id`	Unique identifier for the recipient
`type`	`"individual"` or `"business"`
`account_type`	The type of account (ACH, SPEI, etc.)
`account_details`	Account-specific information
`created_ts`	Creation timestamp (ISO 8601)
`updated_ts`	Last update timestamp (ISO 8601)

HTTP Status Codes

Status	Description
`201 Created`	New recipient was created
`202 Accepted`	Recipient already exists (same account info)
`400 Bad Request`	Validation error
`401 Unauthorized`	Missing/invalid authentication
`404 Not Found`	User not found
`409 Conflict`	Idempotency key conflict

Get Recipients by User

Retrieve all recipients for a specific user.

Endpoint

GET /v1/recipients?user_id={userId}

Query Parameters

Parameter	Required	Description
`user_id`	Yes	UUID of the user

Example Request

curl -X GET "https://api.balampay.com/v1/recipients?user_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "recipients": [
    {
      "recipient_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "individual",
      "first_name": "John",
      "last_name": "Doe",
      "account_type": "ACH",
      "account_details": {
        "routing_number": "021000021",
        "account_number": "123456789",
        "type": "checking"
      },
      "created_ts": "2024-01-15T10:30:00Z",
      "updated_ts": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Get Recipient by ID

Retrieve a specific recipient's details.

Endpoint

GET /v1/recipients/{recipientId}

Path Parameters

Parameter	Description
`recipientId`	UUID of the recipient

Example Request

curl -X GET "https://api.balampay.com/v1/recipients/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "recipient_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "account_type": "ACH",
  "account_details": {
    "routing_number": "021000021",
    "account_number": "123456789",
    "type": "checking",
    "bank_name": "JPMorgan Chase",
    "bank_address": "383 Madison Ave, New York, NY 10179"
  },
  "created_ts": "2024-01-15T10:30:00Z",
  "updated_ts": "2024-01-15T10:30:00Z"
}

Account Type Examples

SPEI (Mexico)

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Juan",
  "last_name": "García",
  "account": {
    "account_type": "SPEI",
    "clabe": "012345678901234567",
    "doc_type": "rfc",
    "doc_number": "GARC850101XXX"
  }
}

ACH (USA)

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "address": "123 Main St, San Francisco, CA 94105",
  "account": {
    "account_type": "ACH",
    "routing_number": "021000021",
    "account_number": "123456789",
    "type": "checking",
    "bank_name": "JPMorgan Chase",
    "bank_address": "383 Madison Ave, New York, NY 10179",
    "doc_type": "passport",
    "doc_number": "AB1234567"
  }
}

WALLET (Crypto)

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "account": {
    "account_type": "WALLET",
    "token": "USDC",
    "network": "polygon",
    "address": "0x1234567890123456789012345678901234567890"
  }
}

PSE (Colombia) - Business

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "business",
  "company_name": "Empresa ABC S.A.S.",
  "account": {
    "account_type": "PSE",
    "account_number": "1234567890",
    "bank_code": "007",
    "type": "checking",
    "doc_type": "nit",
    "doc_number": "900123456",
    "doc_country_code": "CO"
  }
}

BRL (Brazil) - PIX

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "João",
  "last_name": "Silva",
  "account": {
    "account_type": "BRL",
    "account_number": "12345678901",
    "pix_key_type": "code_cpf",
    "city": "São Paulo",
    "doc_type": "cpf",
    "doc_number": "12345678901",
    "doc_country_code": "BR"
  }
}

Error Responses

Validation Error

Status: 400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "CLABE must be exactly 18 digits",
    "details": {}
  }
}

User Not Found

Status: 404 Not Found

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 550e8400-e29b-41d4-a716-446655440000 not found or does not belong to this client",
    "details": {
      "user_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Idempotency Conflict

Status: 409 Conflict

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency key has already been used with a different request",
    "details": {}
  }
}

Unauthorized

Status: 401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": {}
  }
}

Duplicate Detection

The system automatically detects duplicate recipients based on:

Account identifier (CLABE for SPEI, account_number for others)
User ID

Behavior:

New recipient: Returns 201 Created
Duplicate detected: Returns 202 Accepted with existing recipient data

This prevents creating multiple recipients for the same bank account.

Idempotency

The idempotency-key header is required for recipient creation and must be a valid UUID.

Same key + same request: Returns cached response
Same key + different request: Returns 409 Conflict

# Generate a unique idempotency key
curl -X POST https://api.balampay.com/v1/recipients \
  -H "idempotency-key: $(uuidgen)" \
  ...

Best Practices

Always use unique idempotency keys - Generate a new UUID for each request
Validate account details - Verify routing numbers and CLABEs before submitting
Store recipient IDs - Save returned recipient IDs for future payout requests
Handle duplicates gracefully - Check for 202 status to detect existing recipients
Use the correct account type - Each region/currency has specific requirements

Next Steps

After creating recipients:

Create payouts to send funds to recipients
Set up webhooks to track payout status

Support

Email: [email protected]
Account Types Reference: account-types.md
Payouts Guide: payouts.md