Understanding the transaction lifecycle is essential for building robust integrations with Gnosis Pay. This guide explains the detailed flow from card usage to final settlement.

​
Overview

Card transactions follow a two-phase process:
  1. Authorization Phase: Real-time approval/decline of the transaction
  2. Clearing Phase: Final settlement and fund transfer (usually 24-48 hours later)
Different transaction kinds have different behaviors in each phase.

​
Authorization Phase

​
Payment Authorization

When a customer uses their Gnosis Pay card:
1

Card Presentation

Customer presents card at merchant (physical swipe/insert or online entry)
2

Authorization Request

Merchant’s payment processor sends authorization request to Gnosis Pay
3

Real-time Validation

Gnosis Pay performs multiple checks:
  • Available balance verification
  • Card status (active, not frozen)
  • Spending limits compliance
  • Anti-fraud analysis
  • AML screening
4

Authorization Response

Gnosis Pay responds with approval or decline
5

Fund Deduction

If approved, money is immediately deducted from user account and moved to hold account on chain
6

API Visibility

Transaction appears immediately in /api/v1/cards/transactions with:
  • kind: "Payment"
  • isPending: true
  • clearedAt: null
  • status: "Approved" (or decline reason)

​
Refund Authorization

Refunds have a different authorization flow:
1

Merchant Initiation

Merchant initiates refund (product return, service cancellation)
2

Refund Authorization

Merchant sends refund authorization request
3

Authorization Processing

Gnosis Pay validates the refund request
4

No Immediate API Visibility

Important: Refund does NOT appear in API yet - requires clearing

​
Reversal Authorization

Reversals can happen at the authorization level:
1

Error Detection

System or merchant detects transaction error
2

Reversal Request

Immediate reversal request sent
3

Authorization Reversal

Original authorization is reversed
4

API Visibility

May appear immediately as reversal or update original payment status

​
Clearing Phase

The clearing phase typically occurs 24-48 hours after authorization, but timing varies by merchant type.

​
Standard Clearing Timeline

  • Most merchants: 24-48 hours
  • Hotels: Can be up to 30 days (for incidentals)
  • Car rentals: Up to 30 days
  • Airlines: Usually 24-48 hours
  • Gas stations: Often same day

​
Payment Clearing

1

Clearing Initiation

Merchant submits clearing record (usually batch processed overnight)
2

Amount Reconciliation

Clearing amount may differ from authorization:
  • Exact match: Most common scenario
  • Partial capture: Lower amount (unused authorization released)
  • Over capture: Higher amount (allowed for specific MCCs like hotels)
3

Final Settlement

Money is transferred from hold account on chain to merchant
4

API Update

Transaction updates in API:
  • isPending: false
  • clearedAt: "2024-01-15T02:30:00Z"
  • Amounts may be updated if different from authorization

​
Refund Clearing

Refunds require both authorization AND clearing to appear:
1

Credit Voucher Processing

Merchant submits credit voucher (BaseII transaction code “06”)
2

Refund Validation

System validates refund against original transaction
3

Fund Credit

Funds are credited back to cardholder account
4

API Appearance

Refund now appears in API:
  • kind: "Refund"
  • isPending: false (usually)
  • clearedAt: "2024-01-15T08:20:00Z"
  • refundAmount and refundCurrency fields

​
Edge Cases and Special Scenarios

​
Partial Authorizations and Captures

Some merchants may:
  • Partial capture: Capture less than authorized amount
  • Multi capture: Multiple captures on single authorization
  • Incremental authorization: Additional authorizations (hotels for incidentals)

​
Force Captures

Rare but possible scenarios:
  • Offline transactions: POS terminals without internet (airlines)
  • Force capture: Capture on previously declined authorization

​
Authorization Expiry

If not captured within time limits:
  • Authorization expires (typically 7-30 days)
  • Money is returned from hold account back to user account on chain
  • Transaction may disappear from API or show as expired

​
Webhook Integration

For real-time updates, consider implementing webhooks to be notified when:
  • Pending payments are settled
  • Refunds are processed
  • Reversals occur

​
Troubleshooting Common Issues

​
Missing Transactions

  • Payments not appearing: Check authorization was approved
  • Refunds not appearing: Ensure both authorization and clearing completed
  • Delayed settlements: Some MCCs have extended clearing times

​
Status Confusion

  • isPending behavior: Different meanings for different transaction kinds
  • Timing expectations: Clearing can take hours to days depending on merchant

​
Next Steps