Skip to main content

Overview

This page is the overview for the public PayWise Bill Payments API for version=2026-07-01.

1. Overview

Bill Payments is a public, institution-scoped payment flow for approved integrators. The public edge validates the caller, normalizes the request, and returns only PayWise public fields.

The public client does not receive provider tokens, IP headers, encrypted IDs, raw provider payloads, or internal provider references by default.

2. Target clients

  • Virtual Agent
  • Credit unions
  • Third-party integrators

3. Public route summary

Canonical public routes:

  • POST /bill_payments/pay?version=2026-07-01
  • GET /bill_payments/status?version=2026-07-01&transaction_id=...
  • GET /bill_payments/receipt?version=2026-07-01&transaction_id=...

Compatibility aliases may continue to exist for older integrations, but they are not the recommended public integration target.

Do not document kiosk/internal /api/billpay/* routes as public partner routes.

4. Versioning

The public Bill Payments API uses query parameter versioning only:

- ?version=2026-07-01

Do not introduce a version header for this contract.

5. Headers

Required and recommended public headers:

  • PW-subscription-key
  • PW-origin-country
  • PW-request-date
  • PW-ip-address
  • User-Agent
  • Idempotency-Key
  • X-Request-Id

Notes:

  • Idempotency-Key is required for POST /bill_payments/pay.
  • X-Request-Id is recommended for traceability.
  • Do not expose legacy provider headers in the public contract.
  • Public docs must not include ip or token provider headers.

6. Identifier rules

transaction_id      = PayWise transaction tracking ID
receipt_id          = PayWise-generated bill payment receipt/reference
external_reference  = client or partner order or correlation reference
client_receipt_id   = client or partner receipt/reference for its own funds collection

7. Receipt format

PayWise bill payment receipt format:

PWBP-<8 uppercase alphanumeric characters>

Example:

PWBP-9C11D5BC

This keeps bill payments distinct from other receipt families while preserving a short human-readable format.

8. Status model

Public statuses are terminal-only:

  • SUCCESS
  • FAILED

9. Idempotency

  • Idempotency-Key is required for POST /bill_payments/pay.
  • The same key plus the same payload returns the stored result.
  • The same key plus a different payload returns a conflict.

10. Public client funding model

Third-party clients such as credit unions may collect funds from their customer or member before calling PayWise Bill Payments. In that case, the client may send client_receipt_id and/or external_reference for reconciliation.

PayWise still generates its own receipt_id for the PayWise bill payment execution. Settlement between the client and PayWise is governed separately and is not represented by provider credentials in this API.

11. Endpoint pages

Billers are intentionally omitted from this public docs set for now.