Payments API

Base URL

https://api.xtopay.co/v1

POST /payments

Create a new payment.

Request body

Field	Type	Required	Description
`amount`	integer	yes	Amount in smallest currency unit
`currency`	string	yes	ISO 4217 currency code
`customer`	object	yes	Customer details
`customer.email`	string	yes	Customer email
`customer.name`	string	no	Customer full name
`customer.phone`	string	no	E.164 phone (required for mobile money)
`customer_id`	string	no	Existing customer ID (overrides `customer`)
`redirect_url`	string	yes	URL to redirect after payment
`cancel_url`	string	no	URL to redirect on cancellation
`checkout`	object	no	Checkout customisation
`metadata`	object	no	Key-value pairs stored on the payment

curl https://api.xtopay.co/v1/payments \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "GHS",
    "customer": { "email": "ama@example.com", "name": "Ama Owusu" },
    "redirect_url": "https://yourapp.com/success"
  }'

Response 201

{
  "id": "pay_a1b2c3",
  "amount": 5000,
  "currency": "GHS",
  "status": "created",
  "checkout_url": "https://checkout.xtopay.co/pay/tok_xyz",
  "created_at": "2026-05-24T10:00:00Z"
}

GET /payments/:id

Retrieve a payment by ID.

curl https://api.xtopay.co/v1/payments/pay_a1b2c3 \
  -u "$CLIENT_ID:$CLIENT_SECRET"

GET /payments

List payments with optional filters.

Query parameters

Parameter	Type	Description
`limit`	integer	1–100, default 20
`after`	string	Cursor for next page
`status`	string	Filter by status
`currency`	string	Filter by currency
`customer_id`	string	Filter by customer
`created_after`	ISO 8601	Filter by creation date
`created_before`	ISO 8601	Filter by creation date

POST /refunds

Issue a refund on a succeeded payment.

Request body

Field	Type	Required	Description
`payment_id`	string	yes	ID of the payment to refund
`amount`	integer	no	Partial refund amount. Omit for full refund.
`reason`	string	no	`customer_request` \| `duplicate` \| `fraudulent` \| `other`

curl https://api.xtopay.co/v1/refunds \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "payment_id": "pay_a1b2c3", "reason": "customer_request" }'

GET /refunds/:id

Retrieve a refund.

GET /refunds

List refunds. Supports same filters as /payments.