Beneficiaries API

The Beneficiaries API allows you to create and manage payment recipients. Beneficiaries are required for withdrawals, transfers, and exchanges where funds need to be sent to external accounts.

Create Beneficiary

Create a new beneficiary for receiving payments. The required fields vary depending on the currency and country.

Endpoint

POST /api/v1/client/beneficiaries

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <RFC3339-timestamp>
x-signature: <HMAC-signature>

Request Body

Field	Type	Required	Description	Example
`first_name`	string	Yes	Beneficiary's first name	`"John"`
`last_name`	string	Yes	Beneficiary's last name	`"Doe"`
`email`	string	Yes	Beneficiary's email address	`"john.doe@example.com"`
`phone`	string	Yes	Beneficiary's phone number	`"+1234567890"`
`bank_name`	string	Yes	Name of the bank	`"Access Bank"`
`account_number`	string	Conditional	Bank account number (required for NGN)	`"0123456789"`
`bank_code`	string	No	Bank code (from banks API)	`"044"`
`country_code`	string	Yes	ISO 3166-1 alpha-2 country code	`"NG"`, `"US"`, `"CA"`
`currency_code`	string	Yes	Currency code for the beneficiary	`"NGN"`, `"USD"`, `"CAD"`
`account_name`	string	No	Account holder name (auto-generated if not provided)	`"John Doe"`
`iban`	string	No	IBAN for SEPA transfers	`"GB82WEST12345698765432"`
`bic_swift_code`	string	No	BIC/SWIFT code for international transfers	`"CHASUS33"`
`recipient_address`	string	No	Physical address of the recipient	`"123 Main St, Lagos"`
`notes`	string	No	Additional notes about the beneficiary	`"Monthly salary payment"`
`routing_number`	string	No	Routing number (US/Canada)	`"021000021"`
`account_type`	string	No	Account type	`"Checking"`, `"Savings"`
`payment_method`	string	No	Payment method/rail	`"ACH"`, `"Wire"`, `"Sepa"`
`address`	object	No	Structured address object	See Address Object below

Address Object (Optional)

{
  "street": "123 Main Street",
  "city": "Lagos",
  "state": "Lagos State",
  "postal_code": "100001",
  "country": "NG"
}

Currency-Specific Requirements

NGN (Nigerian Naira)

account_number is required
bank_code is recommended (use from Banks API)
bank_name is required

USD (US Dollar)

payment_method is required (ACH, Wire, or Sepa)
For ACH: routing_number and account_number are required
For Wire: routing_number, account_number, and bic_swift_code are required
account_type is recommended (Checking or Savings)

Other Currencies

Requirements vary by country
Check specific country requirements in the Banks API documentation

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "bank_name": "Access Bank",
  "account_number": "0123456789",
  "bank_code": "044",
  "country_code": "NG",
  "currency_code": "NGN",
  "status": "pending",
  "is_verified": false,
  "account_name": "John Doe",
  "is_internal": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Error Responses

Status Code	Description
`400`	Bad Request - Missing required fields, invalid data, or validation errors
`401`	Unauthorized - Invalid or missing API credentials
`409`	Conflict - Beneficiary already exists
`500`	Internal Server Error

Example Request

curl -X POST https://api.transfaar.com/api/v1/client/beneficiaries \
  -H "Content-Type: application/json" \
  -H "x-api-key: tf_test_biz_your_api_key" \
  -H "x-timestamp: 2024-01-15T10:30:00Z" \
  -H "x-signature: your_hmac_signature" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+2348012345678",
    "bank_name": "Access Bank",
    "account_number": "0123456789",
    "bank_code": "044",
    "country_code": "NG",
    "currency_code": "NGN"
  }'

Example: JavaScript/Node.js

const crypto = require('crypto');
 
async function createBeneficiary(apiKey, secretKey, beneficiaryData) {
  const timestamp = new Date().toISOString();
  const body = JSON.stringify(beneficiaryData);
  const dataToSign = body + '|' + timestamp;
  
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(dataToSign)
    .digest('hex');
 
  const response = await fetch('https://api.transfaar.com/api/v1/client/beneficiaries', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'x-timestamp': timestamp,
      'x-signature': signature
    },
    body: body
  });
 
  return await response.json();
}
 
// Usage
const beneficiary = await createBeneficiary(
  'your-api-key',
  'your-secret-key',
  {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    phone: '+2348012345678',
    bank_name: 'Access Bank',
    account_number: '0123456789',
    bank_code: '044',
    country_code: 'NG',
    currency_code: 'NGN'
  }
);

List Beneficiaries

Retrieve a paginated list of beneficiaries for the authenticated business.

Endpoint

GET /api/v1/client/beneficiaries

Query Parameters

Parameter	Type	Description	Example
`page_id`	integer	Page number (default: 1)	`1`
`page_size`	integer	Number of items per page (default: 10)	`20`
`currency`	string	Filter by currency code	`"NGN"`, `"USD"`
`country`	string	Filter by country code	`"NG"`, `"US"`
`name`	string	Search by beneficiary name	`"John"`
`use_tag`	boolean	Filter for internal tag beneficiaries	`true`, `false`

Success Response (200 OK)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "bank_name": "Access Bank",
      "country_code": "NG",
      "currency_code": "NGN",
      "status": "verified",
      "is_verified": true
    }
  ],
  "pagination": {
    "page_id": 1,
    "page_size": 10,
    "total": 25,
    "total_pages": 3
  }
}

Get Beneficiary

Retrieve details of a specific beneficiary by ID.

Endpoint

GET /api/v1/client/beneficiaries/{id}

Path Parameters

Parameter	Type	Description
`id`	UUID	Beneficiary ID

Success Response (200 OK)

Returns the full beneficiary object with all details.

Update Beneficiary

Update an existing beneficiary's information.

Endpoint

PATCH /api/v1/client/beneficiaries/{id}

Request Body

Same structure as create beneficiary, but all fields are optional. Only provided fields will be updated.

Delete Beneficiary

Delete a beneficiary. Beneficiaries that are associated with active transactions cannot be deleted.

Endpoint

DELETE /api/v1/client/beneficiaries/{id}

Success Response (200 OK)

{
  "message": "Beneficiary deleted successfully"
}

Related Endpoints

Banks API - Get list of banks for a country
Banks API - Get list of banks and verify account information
Transactions API - View transactions using beneficiaries

Best Practices

Use Bank IDs - When creating beneficiaries, use the bank_code from the Banks API for better reliability
Validate Accounts - Use the account lookup endpoint to verify account numbers before creating beneficiaries
Handle Verification - Beneficiaries start with status: "pending" and may require verification depending on currency and amount
Store Beneficiary IDs - Save the beneficiary id returned from create for use in quote/transaction requests

🏦 Banks 💳 Cards