Status Codes Reference

This reference provides detailed information about all withdrawal status codes, their meanings, and valid transitions.

​

Status Code Overview

Withdrawal statuses represent the current state of a withdrawal request as it progresses through the system. Each status indicates a specific stage in the processing lifecycle.

​

Status Codes

​

PENDING

Description: Initial state after request creation. Meaning: The withdrawal request has been received and is queued for processing. It may require approval before proceeding. Possible Transitions:

• → PROCESSING (when approved and processing begins)
• → REJECTED (if validation fails or manually rejected)

Typical Duration: Seconds to minutes, depending on approval requirements.

​

PROCESSING

Description: Approved and in progress. Meaning: The withdrawal has been approved and is currently being processed by Tonder’s systems. Validation and preparation are underway. Possible Transitions:

• → SENT_TO_PROVIDER (when ready to send to payment provider)
• → REJECTED (if processing fails)

Typical Duration: Minutes to hours, depending on transfer method and provider.

​

SENT_TO_PROVIDER

Description: Request sent to the external payment provider. Meaning: The withdrawal request has been successfully sent to the payment provider (bank, card network, etc.). The provider is now processing the transfer. Possible Transitions:

• → PAID_FULL (when transfer completes successfully)

Typical Duration:

• SPEI: Same business day during banking hours
• Debit Card: 5-15 minutes

​

PAID_FULL

Description: Withdrawal fully paid successfully. Meaning: The withdrawal has been completed and funds have been successfully transferred to the beneficiary account. This is a terminal success state. Possible Transitions: None (terminal state) Typical Duration: N/A (final state)

​

REJECTED

Description: Withdrawal rejected (by system or action). Meaning: The withdrawal has been rejected and will not be processed. This can occur at any stage due to validation failures, compliance issues, or manual rejection. Possible Transitions: None (terminal state) Rejection Reasons:

• Invalid beneficiary account information
• Insufficient funds
• Compliance or fraud check failures
• Invalid or missing required data
• Manual rejection by merchant or system

Typical Duration: N/A (final state)

​

Status Flow Diagram

​

Status Transition Rules

​

Valid Transitions

​

Invalid Transitions

The following transitions are not possible:

• PAID_FULL → Any other status
• REJECTED → Any other status
• SENT_TO_PROVIDER → PROCESSING or PENDING
• PROCESSING → PENDING

​

Status Monitoring

​

Webhooks

Status changes are automatically sent via webhooks. Each webhook includes:

• Current status
• Previous status (in status_changes array)
• Timestamp of the change
• Reason for the change (if applicable)

​

Status Polling

You can also check status by querying the withdrawal using its ID. However, webhooks are recommended for real-time updates.

​

Handling Different Statuses

​

Success Path

Monitor for the progression: PENDING → PROCESSING → SENT_TO_PROVIDER → PAID_FULL When PAID_FULL is received:

• Mark withdrawal as complete in your system
• Notify the user/beneficiary
• Update accounting records
• Archive the transaction

​

Failure Path

Monitor for transitions to REJECTED from any status. When REJECTED is received:

• Check the rejection reason in the webhook
• Notify the user/beneficiary
• Log the rejection for analysis
• Determine if a new withdrawal request is needed

​

Status Timestamps

Each status change includes an ISO 8601 timestamp. Use these to:

• Calculate processing times
• Identify delays or issues
• Generate reports
• Debug problems

​

Best Practices

1. Handle all statuses: Implement handlers for every possible status
2. Monitor transitions: Track status changes, not just current status
3. Log status history: Keep a complete audit trail
4. Set timeouts: Implement appropriate timeouts for each status
5. Handle rejections: Always handle REJECTED status gracefully

​

Next Steps

• Review withdrawal workflows for process details
• Learn about webhook payloads to receive status updates
• Check HTTP response codes for API error handling