Payments

Track payment status for orders. HanDl integrates with payment providers like Paystack to handle collection — the Payments API gives you visibility and control.

ℹ️

HanDl does not process payments directly. We generate payment links via your connected provider (e.g., Paystack) and track status automatically through webhooks.

Retrieve a Payment

GET/v1/payments/:id

curl

curl https://api.handl-ng.com/v1/payments/pay_abc123 \
  -H "Authorization: Bearer sk_live_..."

Response

json

{
  "id": "pay_abc123",
  "object": "payment",
  "order_id": "ord_1042",
  "amount": 850000,
  "formatted_amount": "₦8,500",
  "currency": "NGN",
  "status": "paid",
  "provider": "paystack",
  "provider_reference": "PSK_txn_1234567",
  "payment_url": "https://paystack.com/pay/abc123",
  "paid_at": "2025-06-15T14:35:00Z",
  "created_at": "2025-06-15T14:30:00Z"
}

List Payments

GET/v1/payments

Parameter	Type	Description
order_id Optional	string	Filter by order.
status Optional	string	'pending', 'paid', 'failed', 'refunded'.
created_after Optional	string	ISO 8601 timestamp.
limit Optional	integer	Number of results (1–100). Default 25.

curl

curl "https://api.handl-ng.com/v1/payments?status=paid&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Create a Payment Link

POST/v1/payments

Generate a payment link for an order. The link is sent to the customer via their conversation channel.

Parameter	Type	Description
order_id Required	string	The order to create a payment link for.
send_to_customer Optional	boolean	Automatically send the link in the conversation. Default true.

curl

curl -X POST https://api.handl-ng.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_1042",
    "send_to_customer": true
  }'

javascript

const payment = await fetch('https://api.handl-ng.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 'ord_1042',
    send_to_customer: true,
  }),
}).then(r => r.json());

console.log(payment.payment_url);
// "https://paystack.com/pay/abc123"

Refund a Payment

POST/v1/payments/:id/refund

Parameter	Type	Description
amount Optional	integer	Partial refund amount in smallest unit. Omit for full refund.
reason Optional	string	Reason for the refund (for your records).

curl

curl -X POST https://api.handl-ng.com/v1/payments/pay_abc123/refund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

⚠️

Refunds are processed through your payment provider. Processing time depends on the provider and the customer's bank (usually 1–5 business days).

Payment Statuses

pendingPayment link generated, awaiting customer payment

paidPayment confirmed by the provider

failedPayment attempt failed (expired, declined, etc.)

refundedPayment has been fully refunded

partially_refundedA partial amount has been refunded