Authenticate
Use partner-scoped OAuth 2.0 client credentials and the negotiated transport/signature profile.
WALLET PARTNER · GIFT CARDS
Reserve first. Confirm once. Deliver one card.
A provider-neutral API for KPay, Wave Pay and future digital wallets. Partner float is reserved before customer debit; confirmation generates one active Gift Card and returns the same encrypted credential on safe retry.
CONTRACT REVIEW
Sandbox/test profile only
Production enablement: OFF
01
Quick start
Production and sandbox identities, keys and balances are always separate.
SANDBOX BASE URL
https://sandbox-api.autotaxi.example/partner/v1Import
Download OpenAPI and Postman files, then verify catalog, reserve and confirm test scenarios.
Certify
Prove JWE decryption, idempotent retries, expiry/refund handling and settlement controls.
Every financial POST requires an Idempotency-Key.
Reusing the same key with a different canonical request returns a conflict and never creates a new financial effect.
02
Endpoint groups
Complete contract lives in the downloadable OpenAPI 3.1 file.
POST /oauth2/tokenGET /gift-card-productsPOST /gift-card-ordersGET /gift-card-orders/{orderId}GET /gift-card-orders/by-partner-reference/{partnerOrderId}POST /gift-card-orders/{orderId}/confirmPOST /gift-card-orders/{orderId}/cancelPOST /gift-card-orders/{orderId}/delivery-confirmationsPOST /gift-card-orders/{orderId}/refund-confirmationsGET /gift-card-issuancesGET /funding-accountGET /funding-transactionsPOST /funding-remittance-noticesGET /settlementsPOST /settlements/{settlementId}/disputes03
Reserve and confirm lifecycle
Reservation protects AutoTaxi and the partner before customer payment.
- Fetch productPartner displays only the active server-authoritative denomination, payable amount, fees and terms version.
- Reserve orderAutoTaxi reserves partner float and returns order ID, authoritative price and confirm-by time.
- Debit customerThe partner collects payment only while the reservation is valid under the agreed race policy.
- Confirm oncePartner supplies its unique payment reference and customer-paid time.
- Deliver securelyAutoTaxi activates one card and returns a JWE encrypted to the partner's registered public key.
RESERVED→CONFIRMING→COMPLETED
RESERVATION_EXPIRED: no card; reserved float released.
UNCERTAIN: query the same order; do not create or charge again.
REFUND_REQUIRED: partner follows the signed refund-confirmation workflow.
04
Gift Card credential delivery
The redeemable secret never appears in ordinary logs, admin tables or support exports.
- Encrypted to partner's registered JWK and
kid - Response marked
Cache-Control: no-store - Exact encrypted envelope retained for authorized retry
- Key rotation keeps agreed old-key recovery window
- No plaintext PIN at rest
- No card secret in webhook
- No second card on duplicate confirm
- No shared inventory with offline CSV cards
05
Funding and settlement
The first production release is prefunded and fails closed.
- Partner available float checked atomically
- Reserve, capture and release are immutable
- Remittance notice is evidence, not money
- Float increases only after bank match and approval
- One settlement line per financial effect
- Disputes never edit completed journals
- Cross-partner access is impossible
- Zero unexplained settlement difference
06
Wallet-partner review files
Use partner-specific sandbox credentials delivered through a separate secure channel.