> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycashq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Codes Reference

> Complete reference for CashQ transfer status codes

## Overview

This page provides a complete reference of all transfer status codes returned by the CashQ API. Use these codes to understand the current state of a money transfer.

## Status Code Structure

Each transfer status consists of three components:

<CardGroup cols={3}>
  <Card title="State" icon="1">
    Primary status indicator showing the general transfer state
  </Card>

  <Card title="Substate" icon="2">
    Additional detail about the current state
  </Card>

  <Card title="Final" icon="flag">
    Indicates if the status is terminal (0 = in progress, 1 = complete)
  </Card>
</CardGroup>

## Quick Reference

### Key States

| State  | Description | Final | Action Required           |
| ------ | ----------- | ----- | ------------------------- |
| **60** | Success     | Yes   | None - transfer completed |
| **80** | Error       | Yes   | Check error details       |
| **40** | Processing  | No    | Wait for completion       |
| **0**  | New         | No    | Transfer just created     |
| **-2** | Not Found   | Yes   | Verify transfer ID        |

## Complete Status Table

| State  | Substate   | Final   | Description                              |
| ------ | ---------- | ------- | ---------------------------------------- |
| **0**  | 0, 1, 2    | No      | **New** - Transfer created               |
| **0**  | 9          | No      | **Awaiting confirmation**                |
| **20** | 1          | No      | **Ready to debit**                       |
| **20** | 2, 3       | No      | **Debiting account**                     |
| **20** | 4          | No      | **Not enough funds in account**          |
| **30** | -          | No      | **Verify**                               |
| **30** | 1          | No      | **Ready to verify**                      |
| **30** | 2          | No      | **Verify, in process**                   |
| **30** | 3          | No      | **Verify, unknown**                      |
| **40** | -          | No      | **Processing**                           |
| **40** | 1          | No      | **Ready to process**                     |
| **40** | 2, 3       | No      | **In process**                           |
| **40** | 4, 5, 6, 7 | No      | **Processing error**                     |
| **60** | -          | **Yes** | **✅ Success (final)**                    |
| **80** | -          | **Yes** | **❌ Error (final)**                      |
| **80** | 1, 2, 3    | No      | **Cancelled by support**                 |
| **80** | 4          | No      | **Not enough funds**                     |
| **80** | 5          | No      | **Processing error**                     |
| **80** | 6          | No      | **Another error**                        |
| **-1** | 0          | No      | **Database insertion error (not final)** |
| **-2** | 0          | **Yes** | **Payment not found (final)**            |

## Status Categories

### Success States

<AccordionGroup>
  <Accordion title="State 60 - Success" icon="check">
    **Description:** Transfer completed successfully

    **Final:** Yes

    **Action:** No action required. Transfer is complete.

    **Example Response:**

    ```json theme={null}
    {
      "status": {
        "result": {
          "state": 60,
          "substate": 0,
          "final": 1,
          "id": "123456789"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### In-Progress States

<AccordionGroup>
  <Accordion title="State 0 - New" icon="sparkles">
    **Description:** Transfer has been created and is being initialized

    **Final:** No

    **Action:** Wait for processing to begin. Status will update automatically.

    **Substates:**

    * `0, 1, 2`: New transfer
    * `9`: Awaiting confirmation
  </Accordion>

  <Accordion title="State 20 - Debiting" icon="wallet">
    **Description:** Funds are being debited from merchant account

    **Final:** No

    **Action:** Wait for debit to complete.

    **Substates:**

    * `1`: Ready to debit
    * `2, 3`: Debiting in progress
    * `4`: Not enough funds (may become final error)
  </Accordion>

  <Accordion title="State 30 - Verification" icon="shield">
    **Description:** Transfer is being verified

    **Final:** No

    **Action:** Wait for verification to complete.

    **Substates:**

    * `1`: Ready to verify
    * `2`: Verification in process
    * `3`: Verification status unknown
  </Accordion>

  <Accordion title="State 40 - Processing" icon="gear">
    **Description:** Transfer is being processed by payment provider

    **Final:** No

    **Action:** Wait for processing to complete. This is the most common in-progress state.

    **Substates:**

    * `1`: Ready to process
    * `2, 3`: Processing in progress
    * `4, 5, 6, 7`: Processing error (may recover or become final error)
  </Accordion>
</AccordionGroup>

### Error States

<AccordionGroup>
  <Accordion title="State 80 - Error" icon="triangle-exclamation">
    **Description:** Transfer failed

    **Final:** Yes (when substate indicates final error)

    **Action:** Check error details in the `attribute` array. Transfer cannot be recovered.

    **Substates:**

    * `1, 2, 3`: Cancelled by support
    * `4`: Not enough funds
    * `5`: Processing error
    * `6`: Another error

    **Example with Error Details:**

    ```json theme={null}
    {
      "status": {
        "result": {
          "state": 80,
          "substate": 5,
          "final": 1,
          "attribute": [
            {
              "name": "provider-error-text",
              "value": "Recipient account closed"
            },
            {
              "name": "provider-error-code",
              "value": "100"
            }
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="State -1 - Database Error" icon="database">
    **Description:** Database insertion error occurred

    **Final:** No

    **Action:** This is typically a transient error. The system will retry automatically.
  </Accordion>

  <Accordion title="State -2 - Not Found" icon="magnifying-glass">
    **Description:** Transfer ID doesn't exist

    **Final:** Yes

    **Action:** Verify the transfer ID is correct. Check if transfer was created in the same environment (sandbox vs production).

    **Example Response:**

    ```json theme={null}
    {
      "payment_response": {
        "payment_id": null,
        "state": "-2",
        "substate": "0",
        "code": "0",
        "id": "123456789"
      },
      "error": "",
      "success": true
    }
    ```
  </Accordion>
</AccordionGroup>

## Understanding the Final Flag

The `final` field indicates whether a transfer has reached a terminal state:

### Final = 0 (In Progress)

* Transfer is still being processed
* Status may change
* Continue polling for updates
* Don't show final result to users yet

### Final = 1 (Complete)

* Transfer has reached a terminal state
* Status will not change
* Stop polling for updates
* Show final result to users (success or failure)

## Error Attributes

When a transfer fails (state 80), the `attribute` array may contain additional error information from the payment provider:

### Common Attributes

<ResponseField name="provider-error-text" type="string">
  Human-readable error message from the payment provider
</ResponseField>

<ResponseField name="provider-error-code" type="string">
  Error code from the payment provider
</ResponseField>

### Example

```json theme={null}
"attribute": [
  {
    "name": "provider-error-text",
    "value": "Insufficient funds"
  },
  {
    "name": "provider-error-code",
    "value": "100"
  }
]
```

## Handling Status Codes

### Basic Status Check

```javascript theme={null}
function interpretStatus(statusResult) {
  const { state, substate, final } = statusResult;
  
  // Check if complete
  if (final === 1) {
    if (state === 60) {
      return { status: 'success', message: 'Transfer completed' };
    } else if (state === 80) {
      const error = extractErrorFromAttributes(statusResult.attribute);
      return { status: 'failed', message: error || 'Transfer failed' };
    } else if (state === -2) {
      return { status: 'not_found', message: 'Transfer not found' };
    }
  }
  
  // In progress
  return { status: 'pending', message: getProgressMessage(state, substate) };
}

function getProgressMessage(state, substate) {
  if (state === 0) return 'Transfer initiated';
  if (state === 20) return 'Debiting account';
  if (state === 30) return 'Verifying transfer';
  if (state === 40) return 'Processing transfer';
  return 'Processing';
}

function extractErrorFromAttributes(attributes) {
  if (!attributes || attributes.length === 0) return null;
  
  const errorText = attributes.find(attr => attr.name === 'provider-error-text');
  return errorText?.value || null;
}
```

### Polling Strategy

```javascript theme={null}
async function pollUntilFinal(transferId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.cashqbot.com/api/status/${transferId}`,
      { headers: { 'API-KEY': apiKey } }
    );
    
    const data = await response.json();
    const result = data.status.result;
    
    // Check if final
    if (result.final === 1) {
      return interpretStatus(result);
    }
    
    // Log progress
    console.log(`Transfer ${transferId}: State ${result.state}, Substate ${result.substate}`);
    
    // Wait before next poll (exponential backoff)
    const delay = Math.min(1000 * Math.pow(1.5, i), 10000);
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Polling timeout - transfer still in progress');
}
```

### User-Friendly Messages

```javascript theme={null}
const statusMessages = {
  0: { text: 'Transfer initiated', color: 'blue', icon: 'clock' },
  20: { text: 'Processing payment', color: 'blue', icon: 'gear' },
  30: { text: 'Verifying details', color: 'blue', icon: 'shield' },
  40: { text: 'Transfer in progress', color: 'blue', icon: 'spinner' },
  60: { text: 'Transfer completed', color: 'green', icon: 'check' },
  80: { text: 'Transfer failed', color: 'red', icon: 'x' },
  '-2': { text: 'Transfer not found', color: 'gray', icon: 'question' }
};

function getUserMessage(state) {
  return statusMessages[state] || statusMessages[40];
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Check Final Flag" icon="flag">
    Always check the `final` field to know when to stop polling
  </Card>

  <Card title="Handle All States" icon="list">
    Account for all possible states in your code, not just success and error
  </Card>

  <Card title="Extract Error Details" icon="info">
    Parse the `attribute` array for detailed error information
  </Card>

  <Card title="Use Exponential Backoff" icon="clock">
    Increase polling intervals to reduce API calls
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Check Transfer Status" icon="clock" href="/api-reference/status">
    Use this endpoint to check transfer status
  </Card>

  <Card title="Money Transfer" icon="money-bill-transfer" href="/api-reference/transfer">
    Create a transfer to get a status
  </Card>
</CardGroup>