Recipients API

Recipients represent external accounts (mobile money wallets or bank accounts) that can receive payouts.

The Recipient Object

{
  "id": "rcp_abc123def456",
  "object": "recipient",
  "name": "John Doe",
  "account": {
    "type": "mobile_money",
    "phone": "024****567",
    "provider": "mtn"
  },
  "email": "john@example.com",
  "metadata": {
    "employee_id": "123"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"recipient"`
`name`	string	Recipient's name
`account`	object	Account details
`account.type`	string	`mobile_money` or `bank_account`
`account.phone`	string	Phone (mobile money)
`account.provider`	string	Provider (mobile money)
`account.bank_code`	string	Bank code (bank account)
`account.account_number`	string	Account number (bank account)
`email`	string	Recipient's email
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Recipient

Creates a new recipient.

POST /v1/recipients

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Recipient's name
`account`	object	Yes	Account details
`account.type`	string	Yes	`mobile_money` or `bank_account`
`account.phone`	string	*	Phone number (mobile money)
`account.provider`	string	*	Provider code (mobile money)
`account.bank_code`	string	*	Bank code (bank account)
`account.account_number`	string	*	Account number (bank account)
`email`	string	No	Recipient's email
`metadata`	object	No	Custom metadata

Mobile Money Recipient

curl -X POST https://api.44.200.142.19.nip.io/v1/recipients \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "account": {
      "type": "mobile_money",
      "phone": "0241234567",
      "provider": "mtn"
    },
    "email": "john@example.com",
    "metadata": {
      "employee_id": "123"
    }
  }'

const recipient = await paygate.recipients.create({
  name: 'John Doe',
  account: {
    type: 'mobile_money',
    phone: '0241234567',
    provider: 'mtn'
  },
  email: 'john@example.com',
  metadata: {
    employee_id: '123'
  }
})

recipient = client.recipients.create(
    name='John Doe',
    account={
        'type': 'mobile_money',
        'phone': '0241234567',
        'provider': 'mtn'
    },
    email='john@example.com',
    metadata={'employee_id': '123'}
)

$recipient = $paygate->recipients->create([
    'name' => 'John Doe',
    'account' => [
        'type' => 'mobile_money',
        'phone' => '0241234567',
        'provider' => 'mtn'
    ],
    'email' => 'john@example.com',
    'metadata' => ['employee_id' => '123']
]);

Bank Account Recipient

curl -X POST https://api.44.200.142.19.nip.io/v1/recipients \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "account": {
      "type": "bank_account",
      "bank_code": "GCB",
      "account_number": "1234567890"
    },
    "email": "john@example.com"
  }'

const recipient = await paygate.recipients.create({
  name: 'John Doe',
  account: {
    type: 'bank_account',
    bank_code: 'GCB',
    account_number: '1234567890'
  },
  email: 'john@example.com'
})

recipient = client.recipients.create(
    name='John Doe',
    account={
        'type': 'bank_account',
        'bank_code': 'GCB',
        'account_number': '1234567890'
    },
    email='john@example.com'
)

Supported Providers

Mobile Money

Provider	Code
MTN Mobile Money	`mtn`
Telecel Cash	`telecel`
AirtelTigo Money	`airteltigo`

Banks

Bank	Code
Ghana Commercial Bank	`GCB`
Ecobank Ghana	`ECO`
Stanbic Bank	`SBG`
Standard Chartered	`SCB`
Absa Bank	`ABSA`
Fidelity Bank	`FBN`
CalBank	`CAL`
Access Bank	`ABG`
UBA Ghana	`UBA`
Zenith Bank	`ZBG`

Contact support for the complete list of supported banks.

Retrieve a Recipient

Retrieves a recipient by ID.

GET /v1/recipients/:id

curl https://api.44.200.142.19.nip.io/v1/recipients/rcp_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const recipient = await paygate.recipients.retrieve('rcp_abc123def456')

recipient = client.recipients.retrieve('rcp_abc123def456')

Update a Recipient

Updates a recipient.

PATCH /v1/recipients/:id

Request Body

Parameter	Type	Description
`name`	string	Recipient's name
`email`	string	Recipient's email
`metadata`	object	Custom metadata

You cannot update the account details. To change the account, create a new recipient.

curl -X PATCH https://api.44.200.142.19.nip.io/v1/recipients/rcp_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "metadata": {
      "employee_id": "456"
    }
  }'

const recipient = await paygate.recipients.update('rcp_abc123def456', {
  name: 'Jane Doe',
  metadata: {
    employee_id: '456'
  }
})

recipient = client.recipients.update('rcp_abc123def456',
    name='Jane Doe',
    metadata={'employee_id': '456'}
)

Delete a Recipient

Deletes a recipient.

DELETE /v1/recipients/:id

curl -X DELETE https://api.44.200.142.19.nip.io/v1/recipients/rcp_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

await paygate.recipients.delete('rcp_abc123def456')

client.recipients.delete('rcp_abc123def456')

List Recipients

Returns a list of recipients.

GET /v1/recipients

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination

curl "https://api.44.200.142.19.nip.io/v1/recipients?limit=10" \
  -H "Authorization: Bearer sk_test_..."

const recipients = await paygate.recipients.list({
  limit: 10
})

recipients = client.recipients.list(limit=10)

Send a Payout to a Recipient

Once you've created a recipient, you can send payouts:

// Create recipient
const recipient = await paygate.recipients.create({
  name: 'John Doe',
  account: {
    type: 'mobile_money',
    phone: '0241234567',
    provider: 'mtn'
  }
})

// Send payout
const payout = await paygate.payouts.create({
  amount: 10000, // GHS 100.00
  recipient: recipient.id,
  description: 'Monthly salary'
})

Recipients

On this page