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": {
    "street_name": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "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 SWIFT accounts
`phone`	string	Conditional	Required for SWIFT accounts (max 16 chars)
`address`	object	Conditional	Required for ACH, WIRE, SWIFT accounts. Object with `street_name`, `city`, `state`, `postal_code`, `country` (2-char ISO code)
`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": {
    "street_name": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "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]",
  "address": {
    "street_name": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "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

ACH (USA)

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "address": {
    "street_name": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "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"
  }
}

WIRE

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

SWIFT (International)

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Maria",
  "last_name": "Schmidt",
  "email": "[email protected]",
  "phone": "+4915112345678",
  "address": {
    "street_name": "Berliner Str. 45",
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10115",
    "country": "DE"
  },
  "account": {
    "account_type": "SWIFT",
    "account_number": "DE89370400440532013000",
    "swift_code": "COBADEFFXXX",
    "bank_name": "Commerzbank AG",
    "bank_address": {
      "street_name": "Kaiserplatz 1",
      "city": "Frankfurt",
      "state": "Hessen",
      "postal_code": "60311",
      "country": "DE"
    }
  }
}

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