# VeloraPay Merchant API

VeloraPay helps merchants collect Ghana invoice payments through checkout
sessions, hosted payment methods, cash deposit slips, and signed webhooks.

Primary docs:
- Merchant guide: /
- API reference: /reference/
- OpenAPI JSON: /openapi.json
- Markdown guide: /merchant-api.md
- Staging collection: /sandbox.collection.json

Current public contract:
- 2026-06

Staging fixtures:
- API key: ak_test_example fixture; use the staging merchant API key issued to your account
- Invoice reference: EPA-2026-001
- Currency: GHS
- Webhook timestamp tolerance: 300 seconds
- Current staging supports test integrations and test API keys only; live key creation is not enabled yet.

Staging base URL:
- https://api.staging.velorapay.com

First-payment integration path:
1. Create or select a test integration in the VeloraPay Merchant Dashboard.
2. Create a test API key for that integration in the Merchant Dashboard and store the one-time key in your backend secret manager.
3. Add the webhook receiver URL in the Merchant Dashboard and store the one-time signing secret in your webhook verifier.
4. Record invoice lines with POST /api/v1/invoice-lines using the integration API key.
5. Create a checkout session with POST /api/v1/sessions, including customer as a nested object with name and email when available.
6. Send the payer to checkout_url for hosted checkout.
7. VeloraPay-hosted checkout handles payment-method selection, fee display, Mobile Money prompts, card entry, cash slip creation, and payment collection.
8. After checkout completes, VeloraPay can return the payer to callback_url. The return is not payment proof.
9. Verify signed webhooks before fulfilment.
10. Use GET /api/v1/sessions/{session_id} with the integration API key as the backend fallback confirmation path.
11. Confirm amount_minor, currency, invoice_ref, terminal status, and event id before releasing value.

Expected first-payment responses:
- POST /api/v1/invoice-lines returns object=invoice.line_items, ingested count, billed_minor, and errors.
- POST /api/v1/sessions returns id, status=open, amount_minor, currency, invoice_ref, checkout_url, and expires_at.
- GET /api/v1/sessions/{session_id} returns id, status, amount_minor, currency, invoice_ref, description, checkout_url, and expires_at.

Payment method rules:
- Standard merchant backends do not make payment-method calls after receiving checkout_url.
- Mobile Money, bank transfer, cash deposit slips, and card entry are handled by VeloraPay-hosted checkout.
- Payment-method endpoints are used by VeloraPay-hosted checkout or explicitly approved custom checkout clients.
- Merchants must not collect raw card numbers or security codes.

Security rules:
- Merchant API keys must stay on the server.
- API keys and webhooks are scoped to one merchant integration.
- Create integrations, API keys, and webhook endpoints in the Merchant Dashboard.
- Public browser docs and examples are staging-only.
- Do not collect raw card numbers or security codes in a merchant flow.
- Verify webhooks using the raw request body.
- Store X-VeloraPay-Event-Id and make handlers idempotent.

Staging cases to prove:
- successful checkout
- pending payment
- failure and expiry
- webhook replay
- invalid or stale signature
- idempotent retry

Versioning rules:
- Optional response fields can be added without notice.
- Required request fields, event names, webhook signature rules, and error-code meanings need a migration note before they change.

Webhook signature:
- Header: X-VeloraPay-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>
- Signed payload: <t>.<raw_request_body>
- Event types: checkout.session.completed, checkout.session.failed, checkout.session.expired