← Payments documentation

Payment & transfer tests

1. Collect payment (loan / bill — Paystack Checkout)

Customer pays in KES (e.g. clear a loan). You get authorization_url, complete card / bank / mobile money on Paystack, then return here to verify.

Uses POST /api/payments/initialize then redirects to Paystack. After payment you return to /payments/test/pay-return and we verify the transaction. Bearer key only if PAYMENTS_REQUIRE_BEARER=true.

2. Disburse to M-Pesa (under 2000 KES auto path)

Default: 200 KES to 0711164069 (auto transfer — under the 2000 KES approval threshold).

200 KES is below 2000 KES → immediate transfer path. The server uses PAYSTACK_SECRET_KEY from Vercel automatically. Bearer key below is only needed if you set PAYMENTS_REQUIRE_BEARER=true in Vercel.

Initialize (set host and optional Bearer key):

curl -sS -X POST 'https://pewang.company/api/payments/initialize' \
  -H 'Content-Type: application/json' \
  -d '{"email":"borrower@example.com","amount_kes":100,"callback_url":"https://pewang.company/payments/test/pay-return","metadata":{"purpose":"loan_repayment","loan_reference":"LOAN-001"}}'
# Add only if PAYMENTS_REQUIRE_BEARER=true:
#   -H 'Authorization: Bearer YOUR_INTEGRATION_KEY'

Disburse (same as before):

curl -sS -X POST 'https://pewang.company/api/payments/disburse' \
  -H 'Content-Type: application/json' \
  -d '{"amount_kes":200,"recipient_phone":"0711164069","recipient_name":"Test","reason":"200 KES test"}'
# Add only if PAYMENTS_REQUIRE_BEARER=true in Vercel:
#   -H 'Authorization: Bearer YOUR_INTEGRATION_KEY'