Recipients

Overview

Recipients represent the destination accounts where funds can be sent. Before making a payout to a user, you must create a recipient that links the user to a specific bank account, wallet, or payment method.

Prerequisites

• ✅ You have authenticated and obtained an access token (Getting Started)
• ✅ You have created a verified user (User Management)
• ✅ You have your API credentials ready

Recipient Lifecycle

graph LR
    A[User Verified] --> B[Create Recipient]
    B --> C[Recipient Active]
    C --> D[Ready for Payouts]

Guides in This Section

1. Recipient Management

📖 Recipient Management Guide

Learn how to:

• Create recipients for different account types
• Retrieve recipient information
• List all recipients for a user

Key endpoints:

• POST /v1/recipients - Create recipient
• GET /v1/recipients - List recipients by user
• GET /v1/recipients/{recipientId} - Get recipient details

2. Account Types Reference

📖 Account Types Reference

Detailed documentation for each supported account type:

• USD: ACH, WIRE, SWIFT
• Mexico: SPEI
• Colombia: PSE
• Crypto: WALLET (USDC, USDT)
• LATAM: ARS, BRL, CLP, PEN, UYU, and more

Supported Account Types

See the Account Types Reference for the complete list and requirements.

Quick Example

Create a SPEI Recipient (Mexico)

curl -X POST https://api.balampay.com/v1/recipients \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Juan",
    "last_name": "García",
    "account": {
      "account_type": "SPEI",
      "clabe": "012345678901234567"
    }
  }'

Create an ACH Recipient (USA)

curl -X POST https://api.balampay.com/v1/recipients \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "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"
    }
  }'

Recipient Types

Individual Recipients

For payments to individual persons.

Required fields:

• first_name
• last_name
• Account-specific fields

Business Recipients

For payments to companies and organizations.

Required fields:

• company_name
• Account-specific fields

Automatic inference:

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

HTTP Status Codes

Next Steps

After creating recipients:

1. Create Payouts - Send funds to recipients
2. Set up Webhooks - Get real-time notifications

Support

• Email: [email protected]
• Full Recipient Guide: recipients.md
• Account Types: account-types.md