AutoTaxiDEVELOPERSFinancial integrationsIntegration pack
Menu

BANK INTEGRATION · PAYOUT

One verified destination. One payout reference.

Drivers and Rider Group owners withdraw to their own verified account at the single configured bank. AutoTaxi never accepts a destination in the withdrawal request and never resubmits an unknown payout blindly.

CONTRACT REVIEW

Sandbox/test profile only

Production enablement: OFF

01

Payout model

Destination ownership is established before money is held.

1

Verify

Inquiry result is matched to the wallet owner and stored as a masked, versioned beneficiary.

2

Hold

The server resolves that verified account and atomically holds the requested available balance.

3

Submit once

One AutoTaxi reference is sent through an outbox and recovered by status inquiry after uncertainty.

Customer request contains amount only.

The app cannot select a bank, enter a destination, change a beneficiary or compute fees during withdrawal.

02

Payout callback contract

Receipt is durable, processing is asynchronous and duplicates are harmless.

SANDBOX CALLBACKPOST https://sandbox-api.autotaxi.example/api/integrations/v1/{payoutBankCode}/withdrawals/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 changes a hold or wallet.

Identical duplicate · HTTP 200

Return the original ack_id and received_at with DUPLICATE/EVENT_DUPLICATE; no second capture or release.

Not durably stored · HTTP 409/429/503

Conflict escalates; throttling/outage retries the identical event. A receipt ACK never means payout success.

spec_versionCanonical callback profile version; currently 1.0Required
event_id / event_typeUnique event and PAYOUT_STATUS_CHANGED, PAYOUT_RETURNED or PAYOUT_REVERSEDRequired
occurred_atAuthoritative UTC provider event timeRequired
withdrawal_referenceOriginal immutable AutoTaxi payout referenceRequired
provider_payout_referenceStable bank payout reference used for inquiryRequired
beneficiary_referenceOpaque verified-beneficiary reference; never a full account numberRequired
status / is_finalACCEPTED, PENDING, PROCESSING, UNKNOWN, SUCCEEDED, FAILED_FINAL, RETURNED or REVERSED with explicit finalityRequired
amount / currencyWhole-MMK amount and ISO currencyRequired
provider_status_codeProvider-native status retained as a stringRequired
provider_transaction_idProvider financial transaction ID for success/return/reversalConditional
original_provider_transaction_idOriginal payout transaction linked by return/reversalConditional
03

APIs required from the payout bank

Exact paths and schemas are supplied and signed by the selected bank.

ACCOUNT INQUIRY
  • Validate account existence and status
  • Return normalized owner name
  • Support identity/ownership proof
  • Return stable bank/account fingerprint inputs
  • Document pending, mismatch and closed states
PAYOUT
  • Accept AutoTaxi idempotency/reference
  • Query the original payout after timeout
  • Deliver final failure/success callbacks
  • Report returns and reversals
  • Provide settlement and liquidity truth
04

Canonical payout lifecycle

An uncertain result retains the hold and the original external reference.

HOLD_PLACED→SUBMISSION_PENDING→PROCESSING→SUCCEEDED

UNKNOWN: keep the hold, query the same provider reference and do not create a second payout.

FAILED_FINAL: release the exact hold through one idempotent transition.

SUCCEEDED: debit held cash once and attach bank/provider settlement evidence.

RETURNED / REVERSED: create a linked compensating journal; never edit the original payout.

05

Non-negotiable controls

Required before any customer-facing withdrawal.

  • Owner-bound verified beneficiary
  • One active account fingerprint per owner
  • Group-owner-only payout authority
  • Available-balance check and atomic hold
  • Provider idempotency/reference proof
  • Unknown-state status recovery
  • Liquidity and cutoff monitoring
  • Settlement-to-hold-to-journal match
06

Payout review files

Use the same bank event contract with the payout capability section.

Bank callbacks OpenAPI 3.1YAML · MMQR and payout callback schemasBank events AsyncAPIYAML · delivery and retry semanticsBank capability requirementsMarkdown · inquiry, payout and settlement needsBank mapping worksheetExcel · complete fields, statuses, ACKs and controlsBank callback Postman collectionJSON · payout callback examples