Skip to main content

​
Overview

Kotani Pay uses a comprehensive set of status codes to track the lifecycle of different transaction types. Understanding these statuses is crucial for building robust integrations and handling transaction states correctly.

​
Status Categories

​
Terminal Statuses

Terminal statuses indicate that a transaction has reached its final state and will not change further. You should stop polling for updates once a transaction reaches a terminal status. Terminal statuses include:
  • SUCCESSFUL / SUCCESS
  • FAILED
  • CANCELLED
  • EXPIRED
  • DECLINED
  • PERMANENTLY_FAILED
  • REVERSED

​
Intermediate Statuses

Intermediate statuses indicate that a transaction is still being processed. You should continue polling or wait for webhooks when a transaction is in an intermediate status. Intermediate statuses include:
  • PENDING
  • INITIATED
  • IN_PROGRESS
  • PROCESSING
  • RETRY

​
Special Statuses

Special statuses are used for specific scenarios:
  • DUPLICATE - Transaction is a duplicate of an existing one
  • ERROR_OCCURRED - An error occurred during processing
  • REQUIRE_REVIEW - Transaction requires manual review
  • NOT_INITIATED - Transaction has not been initiated yet

​
Deposit Transaction Statuses

Used for mobile money deposits, bank deposits, and card deposits.
​
string
Initial status. Payment request has been created but not yet sent to the provider.
​
string
Payment request has been sent to the provider and is awaiting customer action.
​
string
Customer has initiated payment and it’s being processed by the provider.
​
string
Terminal Status - Payment completed successfully. Funds have been credited to your fiat wallet.
​
string
Terminal Status - Alternative success status used by some providers.
​
string
Terminal Status - Payment failed. Common reasons include insufficient funds, network errors, or provider issues.
​
string
Terminal Status - Payment request expired before customer completed payment (typically 30 minutes timeout).
​
string
Terminal Status - Payment was cancelled by customer or system.
​
string
Terminal Status - Payment was declined by the provider or payment network.
​
string
Terminal Status - Payment was reversed/refunded.
​
string
Duplicate transaction detected (same reference ID already exists).
​
string
An unexpected error occurred during processing.
​
string
Transaction flagged for manual review.
​
string
Transaction is being retried after a temporary failure.
​
string
Terminal Status - Transaction failed permanently after all retry attempts exhausted.

​
Withdrawal Transaction Statuses

Used for mobile money withdrawals and bank withdrawals.
​
string
Withdrawal request created but not yet sent to provider.
​
string
Withdrawal request queued for processing.
​
string
Withdrawal request sent to provider.
​
string
Provider has initiated the withdrawal transaction.
​
string
Withdrawal is being processed by the provider.
​
string
Terminal Status - Withdrawal completed successfully. Funds have been sent to the recipient.
​
string
Terminal Status - Withdrawal failed.
​
string
Terminal Status - Withdrawal was cancelled.
​
string
Terminal Status - Withdrawal was declined by provider.
​
string
Terminal Status - Withdrawal request expired.
​
string
Terminal Status - Withdrawal was reversed.
​
string
An error occurred during withdrawal processing.
​
string
Withdrawal requires manual review.
​
string
Withdrawal is being retried.
​
string
Provider is retrying the withdrawal transaction.
​
string
Terminal Status - Retry attempt was successful.
​
string
Terminal Status - Retry attempt failed.

​
Onramp Transaction Statuses

Onramp transactions use two separate status fields:

​
depositStatus

Tracks the fiat payment status (mobile money/bank deposit). Uses the same statuses as Deposit Transaction Statuses.

​
onchainStatus

Tracks the crypto transfer status (sending crypto to external wallet).
​
string
Crypto transfer is pending. Waiting for deposit to complete first.
​
string
Crypto transfer is being processed on the blockchain.
​
string
Terminal Status - Crypto successfully sent to recipient address. Transaction hash available.
​
string
Terminal Status - Crypto transfer failed.
​
string
Terminal Status - Crypto transfer cancelled (usually because deposit failed).
Used for payment link transactions.
​
string
Payment link created but no payment attempted yet.
​
string
Customer is completing the payment.
​
string
Terminal Status - Payment completed successfully.
​
string
Terminal Status - Payment failed.
​
string
Terminal Status - Payment cancelled by customer or expired.
​
string
Terminal Status - Payment link expired before payment was completed.

​
Callback Statuses

Internal statuses tracking callback delivery to your webhook URL.
​
number
default:"0"
Callback delivered successfully to your webhook.
​
number
default:"1"
Callback waiting to be sent.
​
number
default:"2"
Callback is being sent.
​
number
default:"-1"
Callback delivery failed (will retry).
​
number
default:"-2"
Callback delivery permanently failed after all retries.

​
Best Practices

Stop polling when a transaction reaches any terminal status:
  • SUCCESSFUL / SUCCESS
  • FAILED
  • CANCELLED
  • EXPIRED
  • DECLINED
  • PERMANENTLY_FAILED
  • REVERSED
Different failure statuses indicate different scenarios:
  • FAILED - Temporary failure, user can retry creating a new transaction
  • DECLINED - Provider declined the transaction (insufficient funds, limits, etc.)
  • EXPIRED - Timeout, user can create a new transaction
  • CANCELLED - User or system cancelled, no action needed
  • PERMANENTLY_FAILED - Unrecoverable failure, investigate the error
Recommended: Use webhooks for real-time status updates instead of polling.Configure webhook URLs in your integration to receive automatic notifications when transaction statuses change.See Webhooks documentation for setup instructions.
For onramp transactions, monitor BOTH statuses:
  1. depositStatus - Tracks if customer paid (mobile money/bank)
  2. onchainStatus - Tracks if crypto was sent
Success criteria: BOTH must be SUCCESSFULCommon flow:
When you receive ERROR_OCCURRED or REQUIRE_REVIEW:
  1. Check the error or errorMessage field in the response for details
  2. Log the full transaction details for support
  3. Contact support if the issue persists
  4. Do not retry automatically - these statuses often require manual intervention

​
Common Status Flows

​
Successful Deposit Flow

​
Failed Deposit Flow

​
Expired Deposit Flow

​
Successful Withdrawal Flow

​
Successful Onramp Flow

​
Failed Onramp Flow (Deposit Fails)

​
Failed Onramp Flow (Crypto Transfer Fails)

Note: If deposit succeeds but crypto transfer fails, your fiat wallet is still credited. The crypto transfer will be automatically retried or can be manually retried via support.