AutoTaxiDEVELOPERSFinancial integrationsIntegration pack
Menu

BANK INTEGRATION · MMQR

Dynamic MMQR, without guessed bank behavior.

AutoTaxi publishes the callback semantics and the capabilities it requires. The selected bank supplies the exact Create QR, inquiry, finality, reversal and settlement wire profile.

CONTRACT REVIEW

Sandbox/test profile only

Production enablement: OFF

01

Contract boundary

Two directions, two independently reviewable responsibilities.

AUTOTAXI EXPOSES

Authenticated payment callback

  • Bank-code-scoped callback URL
  • Durable receipt before acknowledgement
  • Duplicate-safe event processing
  • Mismatch quarantine and support reference
  • Asynchronous ledger posting
BANK SUPPLIES

Authoritative MMQR operations

  • Authentication or token API
  • Dynamic QR creation API
  • Status lookup by AutoTaxi reference
  • Late-payment and reversal information
  • Settlement reports and controls
02

Callback contract

The URL is stable; the bank-specific wire profile is versioned separately.

SANDBOX CALLBACKPOST https://sandbox-api.autotaxi.example/api/integrations/v1/{mmqrBankCode}/mmqr/callback
Authenticate first

Invalid authentication or replay never receives a success acknowledgement.

New durable receipt · HTTP 202

PROCESSING/EVENT_RECEIVED or QUARANTINED/EVENT_QUARANTINED; quarantine never moves money.

Identical duplicate · HTTP 200

Return the original ack_id and received_at with DUPLICATE/EVENT_DUPLICATE; no second credit.

Not durably stored · HTTP 409/429/503

Conflict escalates; throttling/outage retries the identical event. A receipt ACK never means final wallet credit.

Required canonical event meaning

spec_versionCanonical callback profile version; currently 1.0Required
event_id / event_typeUnique replay-safe event and MMQR_PAYMENT_STATUS_CHANGED or MMQR_PAYMENT_REVERSEDRequired
occurred_atAuthoritative UTC provider event timeRequired
platform_reference_noAutoTaxi reference created before the bank callRequired
qr_reference_no / merchant_idBank QR reference and expected merchant identityRequired
amount / currencyWhole-MMK amount and ISO currencyRequired
status / is_finalPENDING, SUCCEEDED, FAILED, EXPIRED, UNKNOWN or REVERSED with explicit finalityRequired
provider_status_codeString form preserves leading zeroesRequired
provider_transaction_idUnique provider financial transaction ID; mandatory for success/reversalConditional
original_provider_transaction_idOriginal payment transaction linked by a reversalConditional
03

APIs required from the selected bank

These are capability requirements, not invented bank endpoints.

  1. AuthenticateIssue or validate server-to-server access with documented expiry and rotation.
  2. Create dynamic QRAccept AutoTaxi's unique reference and return QR payload, provider reference and expiry.
  3. Query statusFind the original transaction by the same AutoTaxi reference after timeout or missing callback.
  4. Report finalityDefine success, failure, expiry, late payment, reversal and whether success can later reverse.
  5. Provide settlement truthExpose reports/API with transaction identifiers, gross/net value, fees, reversals and cutoff.
04

Canonical payment lifecycle

Bank success and wallet credit are separate durable states.

PAYMENT_INITIATED→QR_READY→PENDING→BANK_SUCCESS→CREDITED

QR_CREATION_UNKNOWN: query the original reference; never create a second QR blindly.

PAID_NOT_CREDITED: retain provider truth and retry the one permitted ledger posting.

REVERSAL: preserve the original journal and create one linked recovery journal.

UNMAPPED STATUS: quarantine; never guess it means success.

05

Security and delivery profile

Exact algorithm and certificate details are frozen bilaterally before UAT.

  • TLS 1.2+; mTLS where agreed
  • Source IP and egress allowlists
  • Timestamp, nonce and replay protection
  • Versioned signing-key rotation
  • Raw-body signature verification boundary
  • No QR payload or secrets in normal logs
  • At-least-once callback delivery
  • Status inquiry remains active during rail pause
06

MMQR review files

Import, review, annotate and return the mapping worksheet during onboarding.

Bank callbacks OpenAPI 3.1YAML · callback schemas and examplesBank events AsyncAPIYAML · event delivery contractBank capability requirementsMarkdown · APIs and evidence AutoTaxi needsBank mapping worksheetExcel · complete and return every applicable mappingBank callback Postman collectionJSON · sandbox callback examples