Payouts API

The Payouts API allows you to send money to mobile money wallets and bank accounts in Ghana.

The Payout Object

{
  "id": "po_abc123def456",
  "object": "payout",
  "amount": 10000,
  "currency": "GHS",
  "status": "pending",
  "recipient": "rcp_xyz789",
  "description": "Salary payment",
  "failure_code": null,
  "failure_message": null,
  "metadata": {
    "employee_id": "123"
  },
  "created_at": "2024-01-15T10:00:00Z",
  "completed_at": null
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"payout"`
`amount`	integer	Amount in pesewas
`currency`	string	Currency code (`GHS`)
`status`	string	`pending`, `processing`, `completed`, `failed`
`recipient`	string	Recipient ID
`description`	string	Payout description
`failure_code`	string	Error code if failed
`failure_message`	string	Error message if failed
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp
`completed_at`	string	Completion timestamp

Create a Payout

Sends money to a recipient.

POST /v1/payouts

Request Body

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in pesewas
`currency`	string	No	Currency (default: `GHS`)
`recipient`	string	Yes	Recipient ID
`description`	string	No	Description
`metadata`	object	No	Custom metadata

You must first create a recipient before sending a payout. See the Recipients API.

curl -X POST https://api.44.200.142.19.nip.io/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "GHS",
    "recipient": "rcp_xyz789",
    "description": "Salary payment",
    "metadata": {
      "employee_id": "123"
    }
  }'

const payout = await paygate.payouts.create({
  amount: 10000,
  currency: 'GHS',
  recipient: 'rcp_xyz789',
  description: 'Salary payment',
  metadata: {
    employee_id: '123'
  }
})

payout = client.payouts.create(
    amount=10000,
    currency='GHS',
    recipient='rcp_xyz789',
    description='Salary payment',
    metadata={'employee_id': '123'}
)

$payout = $paygate->payouts->create([
    'amount' => 10000,
    'currency' => 'GHS',
    'recipient' => 'rcp_xyz789',
    'description' => 'Salary payment',
    'metadata' => ['employee_id' => '123']
]);

Response

{
  "id": "po_abc123def456",
  "object": "payout",
  "amount": 10000,
  "currency": "GHS",
  "status": "pending",
  "recipient": "rcp_xyz789",
  "description": "Salary payment",
  "metadata": {
    "employee_id": "123"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Retrieve a Payout

Retrieves a payout by ID.

GET /v1/payouts/:id

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

const payout = await paygate.payouts.retrieve('po_abc123def456')

payout = client.payouts.retrieve('po_abc123def456')

Cancel a Payout

Cancels a pending payout.

POST /v1/payouts/:id/cancel

You can only cancel payouts that are in pending status. Once processing begins, the payout cannot be canceled.

curl -X POST https://api.44.200.142.19.nip.io/v1/payouts/po_abc123def456/cancel \
  -H "Authorization: Bearer sk_test_..."

const payout = await paygate.payouts.cancel('po_abc123def456')

payout = client.payouts.cancel('po_abc123def456')

List Payouts

Returns a list of payouts.

GET /v1/payouts

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`status`	string	Filter by status
`recipient`	string	Filter by recipient ID
`created[gte]`	string	Filter by creation date
`created[lte]`	string	Filter by creation date

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

const payouts = await paygate.payouts.list({
  status: 'completed',
  limit: 10
})

payouts = client.payouts.list(status='completed', limit=10)

Response

{
  "object": "list",
  "data": [
    {
      "id": "po_abc123def456",
      "object": "payout",
      "amount": 10000,
      "status": "completed",
      ...
    }
  ],
  "has_more": true,
  "url": "/v1/payouts"
}

Payout Statuses

Status	Description
`pending`	Payout is queued for processing
`processing`	Payout is being processed
`completed`	Payout was successful
`failed`	Payout failed
`canceled`	Payout was canceled

Error Codes

Code	Description
`insufficient_balance`	Not enough balance in your account
`invalid_recipient`	Recipient account is invalid
`recipient_unavailable`	Recipient's account is unavailable
`daily_limit_exceeded`	Daily payout limit exceeded
`amount_too_small`	Amount below minimum (GHS 1.00)
`amount_too_large`	Amount above maximum

Webhook Events

Event	Description
`payout.created`	Payout was created
`payout.processing`	Payout is being processed
`payout.completed`	Payout was successful
`payout.failed`	Payout failed
`payout.canceled`	Payout was canceled

app.post('/webhooks', (req, res) => {
  const event = Webhook.constructEvent(req.body, signature, secret)

  switch (event.type) {
    case 'payout.completed':
      const payout = event.data.object
      console.log(`Payout ${payout.id} completed!`)
      break
    case 'payout.failed':
      const failedPayout = event.data.object
      console.log(`Payout failed: ${failedPayout.failure_message}`)
      break
  }

  res.json({ received: true })
})

Payouts

On this page