Skip to main content
POST
/
payments
/
recipients
Create Recipient
curl --request POST \
  --url https://api.usepooler.com/payments/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_number": "<string>",
  "account_name": "<string>",
  "account_type": "individual",
  "account_currency": "<string>",
  "account_country_code": "<string>",
  "account_bank_name": "<string>",
  "account_bank_code": "<string>",
  "amount_limit": 123,
  "identification": {
    "identification_type": "<string>",
    "identification_number": "<string>",
    "identification_image": "<string>"
  },
  "payment_details": {
    "account_number": "<string>",
    "bank_code": "<string>",
    "bank_name": "<string>",
    "routing_number": "<string>",
    "swift_code": "<string>",
    "payment_rails": "<string>"
  }
}
'
{
  "success": true,
  "message": "<string>",
  "stan": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "merchant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "account_number": "<string>",
    "account_name": "<string>",
    "account_type": "<string>",
    "is_internal_account": true,
    "account_currency": "<string>",
    "account_bank_name": "<string>",
    "account_bank_code": "<string>",
    "account_country_code": "<string>",
    "account_country": "<string>",
    "identification": {},
    "limit": "<string>",
    "payment_details": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}
Create a new payment recipient. Recipients are bank accounts or payment destinations that you can send payments to.

​
Overview

Recipients are saved payment destinations that you can reuse for multiple payments. Creating a recipient allows you to:
  • Store bank account details securely
  • Reuse payment destinations without re-entering details
  • Set payment limits per recipient
  • Add identification and verification information

​
Request Body

​
account_number
string
required
Bank account number
​
account_name
string
required
Account holder name
​
account_type
string
required
Type of account holder: “individual” or “business”
​
account_currency
string
required
Currency code (e.g., “NGN”, “USD”, “KES”)
​
account_country_code
string
Country code or country name
​
account_bank_name
string
Bank name
​
account_bank_code
string
Bank code or routing number
​
amount_limit
number
Maximum amount limit for payments to this recipient
​
identification
object
Identification information object:
  • identification_type: Type of ID (e.g., “passport”, “national_id”)
  • identification_number: ID number
  • identification_image: Base64 encoded image of ID
​
payment_details
object
Additional payment details object:
  • account_number: Payment account number
  • bank_code: Bank code
  • bank_name: Bank name
  • routing_number: Routing number
  • swift_code: SWIFT code
  • payment_rails: Payment rails identifier (e.g., “nip”)

​
Headers

​
Idempotency-Key
string
Optional idempotency key to prevent duplicate recipient creation

​
Response

​
data
object
Created recipient object including:
  • id: Recipient UUID (use this for payments)
  • merchant_id: Your merchant ID
  • account_number: Account number
  • account_name: Account holder name
  • account_type: Account type
  • account_currency: Currency code
  • account_bank_name: Bank name
  • account_bank_code: Bank code
  • account_country_code: Country code
  • limit: Payment limit
  • is_internal_account: Whether it’s an internal Pooler account
  • created_at: Creation timestamp
  • updated_at: Last update timestamp

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Include your API key in the Authorization header as: Bearer {your_api_key}

Body

application/json
​
account_number
string
required

Bank account number

​
account_name
string
required

Account holder name

​
account_type
enum<string>
required

Type of account holder

Available options:
individual,
business
​
account_currency
string
required

Currency code

​
account_country_code
string

Country code

​
account_bank_name
string

Bank name

​
account_bank_code
string

Bank code

​
amount_limit
number

Maximum amount limit for this recipient

​
identification
object
​
payment_details
object

Response

201 - application/json

Recipient created successfully

​
success
boolean
​
message
string
​
stan
string<uuid>
​
data
object