Retrieve a payment
GET /collections/:id or /disbursements/:id: read the current payment status.
Endpoints
| Endpoint | Scope |
|---|---|
GET /api/v1/collections/:id | collections:read |
GET /api/v1/disbursements/:id | disbursements:read |
id is the 24-character hexadecimal payment ID returned by a create request. Requests are bound to the authenticated merchant and payment kind.
Request
curl --fail-with-body "$DERIPAY_API_BASE_URL/disbursements/$PAYMENT_ID" \
-H "X-API-Key: $DERIPAY_API_KEY"Payment object
A successful read returns 200 OK with {"data": payment}.
| Field | Description |
|---|---|
id | Payment identifier |
kind | collection or disbursement |
method | stk or b2c |
status | Payment state |
amount_minor | Requested amount in KES cents |
currency | KES |
fee_minor | Deposit fee, or retained withdrawal fee after provider cost |
provider_fee_minor | Amount-based M-PESA B2C charge recorded for the payment |
phone | Normalized recipient or payer phone, when present |
reference | Your reference, when present |
account_reference | Collection account reference, when present |
shortcode | Shortcode associated with the payment |
receipt | Provider receipt, when present |
created_at | Creation timestamp |
updated_at | Last update timestamp |
Internal provider request identifiers, secrets, and idempotency fingerprints are not returned. Optional fields may be omitted entirely. Timestamps use RFC 3339 and may include fractional seconds.
There is currently no public field for a provider failure code or detailed failure reason. Do not invent one from a missing receipt. Use the payment status and contact support with the payment ID when investigation is needed.
The public API has no payment-list, reference-search, cancellation, refund, or reversal endpoint. Use the dashboard for transaction history and store IDs in your own integration.
Not found
A missing payment, malformed ID, another merchant's payment, or a payment queried through the wrong kind endpoint returns 404. A collection ID cannot be read through the disbursement endpoint.
Polling
Use a reasonable interval with backoff and stop polling after a final state. All keys and portal activity share the merchant's request limit. A signed webhook is usually a better way to receive terminal results at scale.