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

Request Body

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)

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

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

string

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

Use the List Banks endpoint to get valid bank codes

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)

string

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

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 "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -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": "john.doe@example.com",
    "metadata": {
      "notes": "Salary recipient",
      "employee_id": "EMP001"
    }
  }'

curl -X POST https://api.payvessel.com/transfer/recipient \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_money",
    "name": "Jane Smith",
    "account_number": "+2348012345678",
    "phone": "+2348012345678",
    "currency": "NGN",
    "email": "jane.smith@example.com"
  }'

const payvessel = require('payvessel')(process.env.PAYVESSEL_SECRET_KEY);

// Create bank account recipient
const bankRecipient = await payvessel.transfer.recipient.create({
  type: 'nuban',
  name: 'John Doe',
  account_number: '0123456789',
  bank_code: '058',
  currency: 'NGN',
  email: 'john.doe@example.com',
  metadata: {
    notes: 'Salary recipient',
    employee_id: 'EMP001'
  }
});

// Create mobile money recipient
const mobileRecipient = await payvessel.transfer.recipient.create({
  type: 'mobile_money',
  name: 'Jane Smith',
  account_number: '+2348012345678',
  phone: '+2348012345678',
  currency: 'NGN',
  email: 'jane.smith@example.com'
});

<?php
$payvessel = new \Payvessel\Payvessel(getenv('PAYVESSEL_SECRET_KEY'));

// Create bank account recipient
$bankRecipient = $payvessel->transfer->recipient->create([
  'type' => 'nuban',
  'name' => 'John Doe',
  'account_number' => '0123456789',
  'bank_code' => '058',
  'currency' => 'NGN',
  'email' => 'john.doe@example.com',
  'metadata' => [
    'notes' => 'Salary recipient',
    'employee_id' => 'EMP001'
  ]
]);
?>

import payvessel

payvessel.api_key = os.environ['PAYVESSEL_SECRET_KEY']

# Create bank account recipient
bank_recipient = payvessel.Transfer.Recipient.create(
    type='nuban',
    name='John Doe',
    account_number='0123456789',
    bank_code='058',
    currency='NGN',
    email='john.doe@example.com',
    metadata={
        'notes': 'Salary recipient',
        'employee_id': 'EMP001'
    }
)

Response

string

Request status indicator - "success" or "error"

string

Human-readable message describing the result

object

Created recipient data object

Show Data Object

integer

Unique recipient ID

string

Unique recipient code for use in transfers

string

Recipient account type

string

Recipient’s full name

string

Recipient’s account number or phone number

string

Bank or provider code

string

Full name of the bank or mobile money provider

string

Transfer currency for this recipient

string

Recipient’s email address

string

Recipient’s phone number

boolean

Whether the recipient is active and can receive transfers

boolean

Whether the recipient’s account details have been verified

string

Account verification status - verified, pending, failed

object

Custom metadata attached to the recipient

string

ISO 8601 timestamp when recipient was created

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": "john.doe@example.com",
    "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"
  }
}

{
  "status": "success",
  "message": "Transfer recipient created successfully",
  "data": {
    "id": 98766,
    "recipient_code": "RCP_abc123xyz789",
    "type": "mobile_money",
    "name": "Jane Smith",
    "account_number": "+2348012345678",
    "bank_code": "MOBILE_MONEY",
    "bank_name": "Mobile Money Provider",
    "currency": "NGN",
    "email": "jane.smith@example.com",
    "phone": "+2348012345678",
    "active": true,
    "verified": true,
    "verification_status": "verified",
    "metadata": {},
    "created_at": "2024-01-15T14:35:00Z",
    "updated_at": "2024-01-15T14:35:00Z"
  }
}

{
  "status": "error",
  "message": "Account verification failed",
  "errors": {
    "account_number": ["Account number does not exist with the specified bank"],
    "name": ["Account name does not match the provided name"]
  }
}

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "name": ["The name field is required"],
    "account_number": ["The account number must be exactly 10 digits"],
    "bank_code": ["The selected bank code is invalid"]
  }
}

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 "api-key: YOUR_API_KEY" \
-H "api-secret: YOUR_SECRET"

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 Transfers
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 transfer
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,
      transfer_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

Virtual Accounts

Issuing

Transfer

Wallets

Identity Verification

Value Added Services

Webhook

Create Transfer Recipient

Endpoint

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

​Endpoint

​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

Endpoint

Request Body

Example Request

Response

Example Response

Recipient Types Guide

Bank Codes Reference

Verification Process

Integration Patterns

Best Practices

Next Steps

Webhook Events