Request a payment

POST /api/v1/payments

Permission: payments:create.

Authorization: Bearer YOUR_APPLICATION_TOKEN
Idempotency-Key: order-1042-collection
Content-Type: application/json

{
  "reference": "order-1042",
  "method": "ecocash",
  "amount_minor": 100,
  "currency": "USD",
  "customer": { "phone": "CUSTOMER_PHONE" },
  "description": "Order 1042"
}

Field	Requirement
reference	Your order reference, up to 100 letters, digits or ._:-
method	ecocash
amount_minor	Positive integer USD cents, within the application's configured limit
currency	USD
customer.phone	Econet number starting with 077, 078 or its international equivalent
description	Optional, up to 140 characters
Idempotency-Key header	Stable key between 8 and 150 characters

The response is HTTP 202 with a data object containing id, reference, status, amount_minor, currency, customer.phone, receipt, last_verified_at, created_at, next_action, refund and links.

Keep the reference and key with your order. The same request returns the original payment. A changed phone, amount or description with the same reference or key returns HTTP 409.

The customer enters their wallet PIN on their phone. The API rejects a pin field.

List payments

GET /api/v1/payments?status=pending&per_page=25

Permission: payments:read. The response includes data, pagination links and metadata. per_page can be 1 to 100.