Disbursements

After your underwriting model approves a loan, you call this endpoint to disburse the funds. We coordinate the OPay payout to the user’s wallet or directly to their bank.

Create a disbursement

POST /partner/v1/disbursements

Body

string

required

The user receiving the disbursement.

string

required

Amount in kobo. String-encoded BigInt to preserve precision.

string

required

One of:

WALLET — Land in the user’s Guild wallet. They can then withdraw or use it directly.
BANK_DIRECT — Land directly in the user’s verified payout bank account. Skips the wallet.

string

required

Your internal loan/credit reference. We include it in the audit row and the webhook.

string

Free-text purpose tag for your internal tracking. Optional. Examples: tool_equipment_loan, inventory_advance, working_capital.

object

Optional. Arbitrary key-value pairs for your records.

Required headers

string

required

Bearer <api_key> with write:disbursements scope.

string

required

Required for disbursements (write operations). Use a fresh UUID per logical disbursement; same UUID per retry of that disbursement.

Example

curl -X POST https://api.guild.com.ng/partner/v1/disbursements \
  -H "Authorization: Bearer gld_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f5g4h3j-2k1l-2m3n-4o5p-6q7r8s9t0u1v" \
  -d '{
    "userId": "usr_01HMFB7ZQK2X8YN4P5R6S7T8V9",
    "amountKobo": "20000000",
    "destination": "WALLET",
    "loanReference": "LN-2026-A0042",
    "purpose": "tool_equipment_loan"
  }'

Response 201

string

ULID prefixed dis_.

string

One of PENDING, DELIVERED, FAILED.

string

User receiving.

string

As requested.

string

As requested.

string

Your reference.

string

As supplied.

string

ISO-8601.

object

As supplied.

{
  "id": "dis_01HMFD4PQ9Z3K7T8V9X2Y1B5C6",
  "status": "PENDING",
  "userId": "usr_01HMFB7ZQK2X8YN4P5R6S7T8V9",
  "amountKobo": "20000000",
  "destination": "WALLET",
  "loanReference": "LN-2026-A0042",
  "purpose": "tool_equipment_loan",
  "createdAt": "2026-08-14T11:15:42Z",
  "metadata": null
}

For WALLET destination, the response is typically DELIVERED synchronously — the wallet credit is internal. For BANK_DIRECT destination, the response is typically PENDING and resolves to DELIVERED (or FAILED) via webhook once OPay’s payout completes.

Error cases

HTTP	Code	When
400	`invalid_amount`	Amount is below minimum (₦100), above your account limit, or zero
422	`user_no_payout_destination`	`destination=BANK_DIRECT` and the user has no verified payout account
422	`user_not_eligible`	User has not consented to receive disbursements from your organisation
409	`idempotency_conflict`	Same Idempotency-Key was used with a different body
429	`rate_limited`	Per-key disbursement rate exceeded

Get a disbursement

GET /partner/v1/disbursements/{disbursementId}

Response 200

Same shape as the creation response, with the current status. For a settled disbursement, additional fields appear:

string

ISO-8601 of when the funds landed.

string

The OPay transaction reference (audit trail).

string

If FAILED, the reason.

List disbursements

GET /partner/v1/disbursements

Query parameters

string

Filter to one user.

string

Filter by status.

string

ISO-8601 inclusive lower bound on createdAt.

string

ISO-8601 exclusive upper bound on createdAt.

integer

default:"50"

Max 200.

string

For pagination.

Response 200

Cursor-paginated list.

Lifecycle webhooks

Subscribe to disbursement.delivered and disbursement.failed events to receive push notifications when status changes. See Webhooks.

Settlement timing

Destination	Typical settlement time
`WALLET`	Synchronous; status `DELIVERED` in the response
`BANK_DIRECT`	7-15 seconds for a healthy NIBSS day; up to a few minutes on slower receiving banks

A disbursement that’s been PENDING for over 5 minutes is unusual. We surface it in the dashboard and you can also poll the GET endpoint.

Webhooks

Push notifications for delivery and failure.

Repayments

How repayments come back to you via direct debit.

Get Started

Partner API

Webhooks

Disbursements

Create a disbursement

Body

Required headers

Example

Response 201

Error cases

Get a disbursement

Response 200

List disbursements

Query parameters

Response 200

Lifecycle webhooks

Settlement timing

What to read next

Webhooks

Repayments

​Create a disbursement

​Body

​Required headers

​Example

​Response 201

​Error cases

​Get a disbursement

​Response 200

​List disbursements

​Query parameters

​Response 200

​Lifecycle webhooks

​Settlement timing

​What to read next

Webhooks

Repayments

Create a disbursement

Body

Required headers

Example

Response 201

Error cases

Get a disbursement

Response 200

List disbursements

Query parameters

Response 200

Lifecycle webhooks

Settlement timing

What to read next