Payout Recipients

Manage payout recipients for Wave B2P (Business-to-Person) transfers.

Create Payout Recipient

Create a new payout recipient.

Endpoint: POST /v1/payouts/recipients

Authentication: Required

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Recipient name
`payout_phone`	string	Yes	Phone number for receiving payouts (Wave, Afrimoney)
`email`	string	No	Recipient email address
`payout_method`	string	No	Payment method (`wave`, `afrimoney`)
`recipient_type`	string	No	Type of recipient
`internal_reference`	string	No	Internal reference for tracking
`notes`	string	No	Additional notes
`is_active`	boolean	No	Whether recipient is active (default: `true`)
`metadata`	object	No	Custom metadata

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "rcp_abc123",
    "organization_id": "org_xyz789",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "payout_method": "wave",
    "payout_phone": "+2207654321",
    "recipient_type": null,
    "internal_reference": null,
    "notes": null,
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Get Payout Recipient

Get details of a specific payout recipient.

Endpoint: GET /v1/payouts/recipients/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "rcp_abc123",
    "organization_id": "org_xyz789",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "payout_method": "wave",
    "payout_phone": "+2207654321",
    "recipient_type": null,
    "internal_reference": "EMP-001",
    "notes": "Monthly contractor",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

List Payout Recipients

Get a paginated list of payout recipients with optional search filters.

Endpoint: GET /v1/payouts/recipients

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`active_only`	boolean	No	Show only active recipients (default: `true`)
`payout_phone`	string	No	Filter by payout phone number (exact match)
`email`	string	No	Filter by email (exact match)
`query`	string	No	Search in name, email, and payout phone (partial match)
`recipient_type`	string	No	Filter by type (employee, contractor, member, vendor, other)
`internal_reference`	string	No	Filter by internal reference (exact match)

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "items": [
      {
        "id": "rcp_abc123",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "payout_phone": "+2207654321",
        "payout_method": "wave",
        "is_active": true,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}

Update Payout Recipient

Update an existing payout recipient.

Endpoint: PUT /v1/payouts/recipients/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`name`	string	No	Recipient name
`payout_phone`	string	No	Payout phone number
`email`	string	No	Recipient email
`payout_method`	string	No	Payment method
`internal_reference`	string	No	Internal reference
`notes`	string	No	Additional notes
`is_active`	boolean	No	Whether recipient is active
`metadata`	object	No	Custom metadata

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "rcp_abc123",
    "organization_id": "org_xyz789",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "payout_method": "wave",
    "payout_phone": "+2207654321",
    "recipient_type": null,
    "internal_reference": "EMP-001",
    "notes": "Updated contractor information",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Delete Payout Recipient

Delete a payout recipient.

Endpoint: DELETE /v1/payouts/recipients/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (204): No content

Send Payout to Recipient

Send a payout to a recipient. Authentication method determines if OTP is required.

Endpoint: POST /v1/payouts/recipients/send

Authentication: Required

Authentication Flows:

API Key Authentication - No OTP required

Session Authentication - Requires OTP verification

Request Body (API Key Auth):

Field	Type	Required	Description
`recipient_id`	string	Yes	ID of the recipient
`amount`	string	Yes	Payout amount (minimum: 100 GMD)
`description`	string	No	Optional payout description

Request Body (Session Auth):

Field	Type	Required	Description
`verification_id`	string	Yes	OTP verification ID from initiate endpoint
`otp`	string	Yes	6-digit OTP code

Example:

HTTP (API Key)

TypeScript (API Key)

Python (API Key)

Session Auth Flow

Success Response (201):

{
  "data": {
    "id": "rp_xyz789",
    "organization_id": "org_abc123",
    "recipient_id": "rcpt_abc123",
    "recipient_name": "Jane Doe",
    "recipient_payout_method": "wave",
    "recipient_payout_phone": "+2207654321",
    "amount": "500.00",
    "currency": "GMD",
    "mode": "live",
    "status": "verified",
    "description": "Monthly payment",
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

Error Responses:

400 Bad Request - Invalid amount, minimum 100 GMD, or insufficient balance

404 Not Found - Recipient not found

401 Unauthorized - Invalid authentication

Payout Recipients

Payout Recipients#

Create Payout Recipient#

Get Payout Recipient#

List Payout Recipients#

Update Payout Recipient#

Delete Payout Recipient#

Send Payout to Recipient#

Payout Recipients

Create Payout Recipient

Get Payout Recipient

List Payout Recipients

Update Payout Recipient

Delete Payout Recipient

Send Payout to Recipient