Payment processor guide

As a payment processor you take payment from a customer and tell UniPay which bill it pays. One integration covers every service provider connected to UniPay. Your part of the payment lifecycle:

1. Get a token with your client credentials — Authentication.
2. Find the bill by bill number or by account, and show the customer what they owe — Look up a bill.
3. Take the customer’s payment in your own system.
4. Report the payment to UniPay with your unique reference for it — Pay a bill.

If you pay service providers directly, also report each day’s transfer so it can be reconciled — Day settlements. Optionally, list the service providers customers can pay — Service provider directory. To see all of it working at once, start with the Quick start.

A payment you’ve reported can’t be withdrawn through the API; if one shouldn’t stand, Axis can reverse it.

Handling one payment

flowchart TD
    A[Customer wants to pay] --> B[Look up the bill]
    B --> C{successful and<br/>status Owing?}
    C -- No --> D[Show the message.<br/>Don't take payment.]
    C -- Yes --> E[Show payableNow<br/>in the bill's currency]
    E --> F{Customer confirms?}
    F -- No --> Z[Stop]
    F -- Yes --> G[Debit the customer]
    G --> H[Report the payment<br/>with a new rrn]
    H --> I{Response?}
    I -- "successful: true" --> J[Receipt to customer]
    I -- "successful: false" --> K[Refused: reverse your debit<br/>and show the message]
    I -- "timeout, 429, 5xx" --> L[Wait, then retry<br/>with the same rrn]
    L --> H

A refusal (successful: false) means UniPay recorded nothing — reverse the customer’s debit on your side. A timeout or server error means the outcome is unknown: never reverse the debit then; retry with the same rrn until you get a definite answer. See Idempotency and retries.

What you can call

Everything lives under /api/app/payment-processor/ and /api/app/directory/:

Endpoint	Scope	Reference
POST /api/app/payment-processor/lookup	unipay:bills	lookup
POST /api/app/payment-processor/payment-details	unipay:bills	pay
POST /api/app/payment-processor/settle-day	unipay:bills	settleDay
GET /api/app/payment-processor/{id}/day-settlement	unipay:bills	getDaySettlement
GET /api/app/payment-processor/day-settlements	unipay:bills	listDaySettlements
GET /api/app/directory/service-providers	unipay:directory	listServiceProviders
GET /api/app/tenant-config	any	tenantConfig

GET …/bill and GET …/latest-bill-by-account still work for existing integrations; new integrations should use lookup, which does both. The Payment Processor API reference lists every endpoint and field.