Create Transfer Recipient

Create a transfer recipient to enable money transfers to bank accounts, mobile money wallets, or other supported channels. Recipients must be created before initiating transfers.

All transfer recipients are verified against the recipient’s bank or mobile money provider to ensure valid account details before creation.

Endpoint

POST /transfer/recipient

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer token with your secret API key
`Content-Type`	string	Required	Must be `application/json`
`Idempotency-Key`	string	Optional	Unique key to prevent duplicate recipients

Request Body

type

string

required

Type of recipient accountAvailable types:

nuban - Nigerian bank account (NUBAN)
mobile_money - Mobile money account
ghana_mobile_money - Ghana mobile money
kenya_mobile_money - Kenya mobile money
bvn - Bank Verification Number (Nigeria)

name

string

required

Full name of the recipient as registered with their bank or mobile money provider

Name must match the account holder’s registered name exactly

account_number

string

required

Account number, phone number, or identifier based on recipient typeFormat by type:

nuban: 10-digit Nigerian bank account number
mobile_money: Phone number in international format (e.g., +2348012345678)
bvn: 11-digit Bank Verification Number

bank_code

string

Bank or provider code (required for nuban and some mobile money types)

Use the List Banks endpoint to get valid bank codes

currency

string

default:"NGN"

Currency for transfers to this recipientSupported currencies: NGN, GHS, KES, USD, GBP, EUR

string

Recipient’s email address for transfer notifications (optional but recommended)

phone

string

Recipient’s phone number for SMS notifications (required for mobile money)

metadata

object

Additional information about the recipient in key-value pairs

{
  "notes": "Monthly salary recipient",
  "employee_id": "EMP001",
  "department": "Engineering"
}

Example Request

curl -X POST https://api.payvessel.com/transfer/recipient \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recipient_2024_001" \
  -d '{
    "type": "nuban",
    "name": "John Doe",
    "account_number": "0123456789",
    "bank_code": "058",
    "currency": "NGN",
    "email": "[email protected]",
    "metadata": {
      "notes": "Salary recipient",
      "employee_id": "EMP001"
    }
  }'

Response

status

string

Request status indicator - "success" or "error"

message

string

Human-readable message describing the result

data

object

Created recipient data object

Show Data Object

data.id

integer

Unique recipient ID

data.recipient_code

string

Unique recipient code for use in transfers

data.type

string

Recipient account type

data.name

string

Recipient’s full name

data.account_number

string

Recipient’s account number or phone number

data.bank_code

string

Bank or provider code

data.bank_name

string

Full name of the bank or mobile money provider

data.currency

string

Transfer currency for this recipient

data.email

string

Recipient’s email address

data.phone

string

Recipient’s phone number

data.active

boolean

Whether the recipient is active and can receive transfers

data.verified

boolean

Whether the recipient’s account details have been verified

data.verification_status

string

Account verification status - verified, pending, failed

data.metadata

object

Custom metadata attached to the recipient

data.created_at

string

ISO 8601 timestamp when recipient was created

data.updated_at

string

ISO 8601 timestamp when recipient was last updated

Example Response

{
  "status": "success",
  "message": "Transfer recipient created successfully",
  "data": {
    "id": 98765,
    "recipient_code": "RCP_xyz789abc123",
    "type": "nuban",
    "name": "John Doe",
    "account_number": "0123456789",
    "bank_code": "058",
    "bank_name": "Guaranty Trust Bank",
    "currency": "NGN",
    "email": "[email protected]",
    "phone": null,
    "active": true,
    "verified": true,
    "verification_status": "verified",
    "metadata": {
      "notes": "Salary recipient",
      "employee_id": "EMP001"
    },
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

Recipient Types Guide

Nigerian Bank (NUBAN)
Mobile Money
International Bank

Requirements:

type: "nuban"
name: Exact account holder name
account_number: 10-digit account number
bank_code: Valid Nigerian bank code

Verification Process:

Account number validation with bank
Name verification against bank records
Real-time verification (usually instant)

{
  "type": "nuban",
  "name": "John Doe",
  "account_number": "0123456789",
  "bank_code": "058",
  "currency": "NGN"
}

Requirements:

type: "mobile_money"
name: Account holder name
account_number: Phone number in international format
phone: Same as account_number

Supported Providers:

Nigeria: Airtel Money, MTN MoMo
Ghana: MTN MoMo, Vodafone Cash, AirtelTigo Money
Kenya: M-Pesa, Airtel Money

{
  "type": "mobile_money",
  "name": "Jane Smith",
  "account_number": "+2348012345678",
  "phone": "+2348012345678",
  "currency": "NGN"
}

Requirements:

type: "nuban" (for supported countries)
name: Account holder name
account_number: Local account number format
bank_code: International bank code
currency: Target currency

Supported Countries:

Ghana: GHS transfers
Kenya: KES transfers
South Africa: ZAR transfers

{
  "type": "nuban",
  "name": "Kwame Asante",
  "account_number": "1234567890123",
  "bank_code": "GCB_BANK",
  "currency": "GHS"
}

Bank Codes Reference

Common Nigerian bank codes for reference:

Major Nigerian Banks

Bank Name	Code
Access Bank	`044`
Guaranty Trust Bank	`058`
United Bank for Africa	`033`
Zenith Bank	`057`
First Bank	`011`
Fidelity Bank	`070`
Union Bank	`032`
Sterling Bank	`232`
Stanbic IBTC	`221`
FCMB	`214`

Digital Banks

Bank Name	Code
Kuda Bank	`50211`
VFD Microfinance Bank	`566`
Rubies Bank	`125`
Carbon	`565`
ALAT by Wema	`035`

Get All Banks

Use the List Banks endpoint to get the complete, up-to-date list of supported banks and their codes.

curl -X GET https://api.payvessel.com/transfer/banks \
  -H "Authorization: Bearer sk_test_abc123..."

Verification Process

PayVessel performs real-time account verification during recipient creation:

Account Number Validation

Validates account number format and checks if it exists with the specified bank

Name Verification

Compares provided name against the account holder’s registered name

Account Status Check

Verifies the account is active and can receive transfers

Compliance Screening

Performs basic compliance checks against restricted account lists

Verification Failures: If verification fails, the recipient will not be created. Common failures include:

Invalid account number
Name mismatch
Inactive account
Invalid bank code

Integration Patterns

Bulk Payroll
Customer Payouts
Vendor Payments

// Create multiple recipients for payroll
const createPayrollRecipients = async (employees) => {
  const recipients = [];
  
  for (const employee of employees) {
    try {
      const recipient = await payvessel.transfer.recipient.create({
        type: 'nuban',
        name: employee.full_name,
        account_number: employee.account_number,
        bank_code: employee.bank_code,
        currency: 'NGN',
        email: employee.email,
        metadata: {
          employee_id: employee.id,
          department: employee.department,
          salary_grade: employee.grade
        }
      });
      
      recipients.push(recipient.data);
    } catch (error) {
      console.error(`Failed to create recipient for ${employee.full_name}:`, error);
    }
  }
  
  return recipients;
};

// Create recipient for customer payout
const createCustomerRecipient = async (customerId, bankDetails) => {
  const recipient = await payvessel.transfer.recipient.create({
    type: 'nuban',
    name: bankDetails.account_name,
    account_number: bankDetails.account_number,
    bank_code: bankDetails.bank_code,
    currency: 'NGN',
    email: bankDetails.email,
    metadata: {
      customer_id: customerId,
      payout_type: 'withdrawal',
      created_by: 'customer_request'
    }
  });
  
  // Store recipient code for future use
  await saveRecipientToCustomer(customerId, recipient.data.recipient_code);
  
  return recipient.data;
};

// Create recipient for vendor payment
const createVendorRecipient = async (vendorData) => {
  const recipient = await payvessel.transfer.recipient.create({
    type: 'nuban',
    name: vendorData.business_name,
    account_number: vendorData.account_number,
    bank_code: vendorData.bank_code,
    currency: vendorData.currency || 'NGN',
    email: vendorData.contact_email,
    metadata: {
      vendor_id: vendorData.id,
      business_type: vendorData.type,
      tax_id: vendorData.tax_identification
    }
  });
  
  return recipient.data;
};

Best Practices

Verify Before Transfer

Always create and verify recipients before initiating transfers to avoid failed transactions

Store Recipient Codes

Save the recipient_code for future transfers to avoid recreating recipients

Handle Verification Failures

Implement proper error handling for account verification failures

Use Metadata

Add relevant metadata to recipients for easier management and reporting

Next Steps

After creating a recipient:

Initiate Transfer

Send money to the created recipient

List Recipients

View all your transfer recipients

Update Recipient

Modify recipient details

Bulk Transfers

Send money to multiple recipients at once

Webhook Events

This endpoint triggers the following webhook events:

recipient.created - Recipient successfully created and verified
recipient.verification_failed - Recipient verification failed during creation

Pro Tip: Create recipients during off-peak hours when possible, as bank verification APIs may have slower response times during peak business hours.

Getting Started

Transactions

Transfers

Identity Verification

Wallets

Virtual Accounts

Webhook

Bill Payments

Card Management

Create Transfer Recipient

Create Transfer Recipient

Endpoint

Headers

Request Body

Example Request

Response

Example Response

Recipient Types Guide

Bank Codes Reference

Verification Process

Integration Patterns

Best Practices

Verify Before Transfer

Store Recipient Codes

Handle Verification Failures

Use Metadata

Next Steps

Initiate Transfer

List Recipients

Update Recipient

Bulk Transfers

Webhook Events

Getting Started

Transactions

Transfers

Identity Verification

Wallets

Virtual Accounts

Webhook

Bill Payments

Card Management

​Create Transfer Recipient

​Endpoint

​Headers

​Request Body

​Example Request

​Response

​Example Response

​Recipient Types Guide

​Bank Codes Reference

​Verification Process

​Integration Patterns

​Best Practices

Verify Before Transfer

Store Recipient Codes

Handle Verification Failures

Use Metadata

​Next Steps

Initiate Transfer

List Recipients

Update Recipient

Bulk Transfers

​Webhook Events

Create Transfer Recipient

Endpoint

Headers

Request Body

Example Request

Response

Example Response

Recipient Types Guide

Bank Codes Reference

Verification Process

Integration Patterns

Best Practices

Next Steps

Webhook Events