Recipients API

Recipients allow you to save external account details (mobile money wallets or bank accounts) for future payouts. This is useful for recurring payments to the same accounts.

Recipients are optional. You can also send payouts directly by specifying the destination details inline. See the Payouts API for direct transfers.

The Recipient Object

{
  "id": "rcp_abc123def456",
  "object": "recipient",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "0241234567",
  "description": "Employee - Marketing",
  "account": {
    "type": "mobile_money",
    "number": "024****567",
    "name": "John Doe",
    "provider": "mtn"
  },
  "status": "active",
  "is_verified": false,
  "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
`email`	string	Recipient's email
`phone`	string	Recipient's phone number
`description`	string	Description or notes
`account`	object	Account details
`account.type`	string	`mobile_money` or `bank_transfer`
`account.number`	string	Masked account/phone number
`account.name`	string	Account holder name
`account.provider`	string	Provider (mobile money)
`account.bank_code`	string	Bank code (bank transfer)
`status`	string	`active`, `inactive`
`is_verified`	boolean	Whether account is verified
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Recipient

Creates a new saved recipient.

POST /v1/recipients

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Recipient's name
`email`	string	No	Recipient's email
`phone`	string	No	Recipient's phone number
`description`	string	No	Description or notes
`account`	object	Yes	Account details
`account.type`	string	Yes	`mobile_money` or `bank_transfer`
`account.phone_number`	string	Yes*	Phone number (mobile money)
`account.provider`	string	No	Provider code (auto-detected)
`account.account_number`	string	Yes*	Account number (bank transfer)
`account.bank_code`	string	Yes*	Bank code (bank transfer)
`account.account_name`	string	No	Account holder name
`metadata`	object	No	Custom metadata

Mobile Money Recipient

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

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

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

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

Bank Account Recipient

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

const recipient = await shikacreators.recipients.create({
  name: 'John Doe',
  account: {
    type: 'bank_transfer',
    bank_code: '030100',
    account_number: '1234567890',
    account_name: 'John Doe'
  },
  email: 'john@example.com'
})

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

Supported Providers

Mobile Money

Provider	Code	Phone Prefixes
MTN Mobile Money	`mtn`	024, 025, 053, 054, 055, 059
Telecel Cash	`telecel`	020, 050
AirtelTigo Money	`airteltigo`	026, 027, 056, 057

Banks

Fetch the bank list with GET /v1/lookup/banks and use the bank_code it returns.

curl https://api.shikacreators.com/v1/lookup/banks \
  -H "Authorization: Bearer sk_live_..."

Do not hardcode bank codes. Your account is routed to one of several banking partners, and each partner identifies banks with its own codes. GET /v1/lookup/banks always returns the codes valid for your account. A code from anywhere else is rejected, so cache the list rather than copying values into your source.

Retrieve a Recipient

Retrieves a recipient by ID.

GET /v1/recipients/:id

curl https://api.shikacreators.com/v1/recipients/rcp_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

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

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

Update a Recipient

Updates a recipient's details.

PATCH /v1/recipients/:id

Request Body

Parameter	Type	Description
`name`	string	Recipient's name
`email`	string	Recipient's email
`phone`	string	Recipient's phone
`description`	string	Description or notes
`account`	object	Account details (can update)
`metadata`	object	Custom metadata

curl -X PATCH https://api.shikacreators.com/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 shikacreators.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.shikacreators.com/v1/recipients/rcp_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

await shikacreators.recipients.delete('rcp_abc123def456')

client.recipients.delete('rcp_abc123def456')

Response

{
  "id": "rcp_abc123def456",
  "object": "recipient",
  "deleted": true
}

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
`status`	string	Filter by status (`active`, `inactive`)

curl "https://api.shikacreators.com/v1/recipients?limit=10" \
  -H "Authorization: Bearer sk_test_..."

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

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "rcp_abc123def456",
      "object": "recipient",
      "name": "John Doe",
      ...
    }
  ],
  "has_more": true,
  "url": "/v1/recipients"
}

Use Case: Recurring Payouts

Recipients are ideal for recurring payments like salaries or vendor payments:

// 1. Create recipients once
const employee = await shikacreators.recipients.create({
  name: 'John Doe',
  account: {
    type: 'mobile_money',
    phone_number: '0241234567'
  },
  metadata: { employee_id: 'EMP001' }
})

// 2. Get recipient details when sending payout
const recipient = await shikacreators.recipients.retrieve(employee.id)

// 3. Send payout using the saved details
// Note: Currently, payouts require inline destination details
const payout = await shikacreators.payouts.create({
  amount: 500,
  destination: {
    type: 'mobile_money',
    phone_number: '0241234567', // Use from recipient.account
    account_name: 'John Doe'
  },
  otp_code: '123456',
  description: 'Monthly salary',
  metadata: { recipient_id: employee.id }
})

Recipients

On this page