Merchant API and payment partner integrations
Status: Proposed interface contract. Endpoint naming and provider capabilities may change.
Merchant API
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /v1/bills | Create a bill with idempotency key |
| GET | /v1/bills/{id} | Retrieve bill and collection status |
| POST | /v1/bills/{id}/cancel | Request cancellation if eligible |
| GET | /v1/payments/{id} | Retrieve payment and attempts |
| GET | /v1/payouts | List payouts and reconciliation references |
| GET | /v1/payouts/{id} | Retrieve allocations |
| GET | /v1/merchant-customers/{id} | View merchant-specific consumer linkage |
Authentication: merchant-scoped credentials, short-lived tokens where feasible, least privilege, key rotation and revocation. Require Idempotency-Key for financial writes and define replay windows. Responses must distinguish accepted, pending, final success and failure.
Webhooks to merchants
Events may include bill.scheduled, collection.pending, collection.succeeded, collection.failed, payout.initiated, payout.completed, payout.failed, refund.completed and dispute.opened. Use versioned schemas, signed payloads, event IDs, retry with backoff, dead-letter recovery and merchant replay tools. Delivery order is not guaranteed; consumers must deduplicate events.
Payment partner adapter
Encapsulate provider-specific APIs behind an internal adapter supporting: tokenised payment methods, card and bank debit initiation, mandates/consent references, idempotent attempts, event retrieval, settlement reporting, safeguarded funds information, payouts, reversals, refunds and disputes.
Do not assume a single provider supports every function. Validate account ownership, merchant-of-record treatment, card network obligations, bank debit return windows and payout eligibility.
API design standards
- Version external APIs; publish OpenAPI specifications.
- Use structured error codes, request IDs and correlation IDs.
- Rate-limit per merchant, user and credential.
- Validate webhook signatures and timestamp windows before processing.
- Do not log card data, raw bank credentials, sensitive tokens or unnecessary personal information.
- Support sandbox credentials, test scenarios and integration certification.