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

# Transfer Status

> Monitor and track transfer states throughout the complete payment lifecycle

Understanding transfer statuses is crucial for providing users with accurate information about their payments and handling edge cases appropriately. This guide covers all possible transfer states and how to monitor them effectively.

## Transfer Lifecycle

All transfers in Carbn Connect follow a predictable lifecycle with specific states that indicate the current stage of processing:

<Steps>
  <Step title="Initiation">
    Transfer is created and awaiting funds or processing
  </Step>

  <Step title="Processing">
    Funds are being moved through the payment system
  </Step>

  <Step title="Completion">
    Transfer reaches final state (success, failure, or requires action)
  </Step>
</Steps>

***

## Transfer States

The transfer status indicates the current state of a transfer. Here are all possible states:

<AccordionGroup>
  <Accordion title="awaiting_funds" icon="clock" defaultOpen>
    **Description**: Carbn is waiting to receive funds from the user before processing the transfer.

    **Applies to**:

    * SEPA Payments
    * Wire transfers
    * ACH pushes
    * Virtual account transfers

    **Next Steps**: Wait for user to send funds or complete payment flow.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "awaiting_funds",
        "created_at": "2024-01-01T10:00:00Z",
        "source_currency": "eur",
        "amount": 100
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="funds_received" icon="circle-check">
    **Description**: Carbn has received the funds and is preparing to move them on the user's behalf.

    **Duration**: Usually seconds to a few minutes

    **What's happening**: Internal processing, validation, and preparation for onward transfer.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "funds_received",
        "updated_at": "2024-01-01T10:05:00Z",
        "source_currency": "eur",
        "amount": 100
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="in_review" icon="clock">
    **Description**: A temporary state triggered when transfer data needs further confirmation.

    **Duration**: Typically resolves in seconds; otherwise, Carbn will reach out within 24 hours.

    **Action Required**: Wait for automatic resolution or contact support if extended.

    <Warning>
      This is a rare state that usually resolves automatically. If a transfer remains in this state for more than 24 hours, contact support.
    </Warning>
  </Accordion>

  <Accordion title="payment_submitted" icon="arrow-right">
    **Description**: Carbn has initiated the payment and is awaiting confirmation.

    **Duration varies by payment rail**:

    * **Crypto**: Minutes
    * **Wires**: Hours
    * **ACH**: Days

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "payment_submitted",
        "updated_at": "2024-01-01T10:06:00Z",
        "payment_rail": "crypto",
        "estimated_completion": "2024-01-01T10:15:00Z"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="payment_processed" icon="circle-check-big">
    **Description**: The transfer is complete and funds have been successfully delivered to the destination.

    **Final State**: This is a successful completion state.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "status": "payment_processed",
        "completed_at": "2024-01-01T10:12:00Z",
        "final_amount": 95.50,
        "destination_confirmed": true
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Exception States

<AccordionGroup>
  <Accordion title="undeliverable" icon="circle-x">
    **Description**: Carbn was unable to deliver funds due to an issue like an invalid account or unsupported asset at the destination.

    **Common Causes**:

    * Invalid destination wallet address
    * Unsupported asset at destination
    * Destination account closed or frozen

    **Action Required**: Check destination details and retry with correct information.
  </Accordion>

  <Accordion title="returned" icon="arrow-left">
    **Description**: The payment was sent but failed. Funds have returned to Carbn and a refund to the sender is underway.

    **What happens next**: Automatic refund process initiated to original sender.
  </Accordion>

  <Accordion title="refunded" icon="arrow-left-right">
    **Description**: The transfer was refunded back to the original sender.

    **Final State**: This is a completion state where funds are returned.
  </Accordion>

  <Accordion title="canceled" icon="ban">
    **Description**: The transfer was canceled. This can only happen from the `awaiting_funds` state.

    **How to cancel**: Contact support to cancel a transfer in `awaiting_funds` status.

    <Note>
      Transfers can only be canceled while in `awaiting_funds` status. Once funds are received, cancellation is no longer possible.
    </Note>
  </Accordion>

  <Accordion title="error" icon="triangle-alert">
    **Description**: A problem occurred that blocked processing. This typically requires manual review or developer action.

    **Action Required**: Contact support with transfer details for investigation.
  </Accordion>
</AccordionGroup>

***

## Open Banking Payment Status

When using Open Banking for fund collection, the standard `awaiting_funds` status is replaced by specific Open Banking payment statuses. These statuses track the payment authorization and execution process through the banking system.

### Open Banking Flow

Open Banking payments follow this progression:

```
PAYMENT_STATUS_INPUT_NEEDED → PAYMENT_STATUS_AUTHORISING → PAYMENT_STATUS_INITIATED → PAYMENT_STATUS_EXECUTED → funds_received
```

<AccordionGroup>
  <Accordion title="PAYMENT_STATUS_INPUT_NEEDED" icon="user-check" defaultOpen>
    **Description**: Awaiting user input to begin the payment authorization process.

    **What's happening**: User has received the Open Banking link but hasn't started the authorization flow yet.

    **Duration**: Depends on user action - no time limit

    **User Action Required**: User needs to click the Open Banking link and begin authorization with their bank.

    <CodeGroup>
      ```json Example Response theme={null}
      {
        "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
        "payment_status": "PAYMENT_STATUS_INPUT_NEEDED",
        "created_at": "2024-01-01T10:00:00Z",
        "payment_method": "open_banking"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_AUTHORISING" icon="shield-check">
    **Description**: User is in the process of authorizing the payment with their bank.

    **What's happening**: User has started the authorization flow and is providing credentials/consent to their bank.

    **Duration**: Typically a few minutes while user completes bank authorization

    **Next Steps**: Wait for user to complete authorization or abandon the process.
  </Accordion>

  <Accordion title="PAYMENT_STATUS_INITIATED" icon="arrow-right">
    **Description**: Payment has been authorized and is in transit through the banking system.

    **What's happening**: User successfully authorized the payment, and it's being processed by the bank.

    **Duration**: Usually minutes to hours depending on the bank

    **Possible Outcomes**: Can progress to `EXECUTED`, `FAILED`, `BLOCKED`, or `REJECTED`
  </Accordion>

  <Accordion title="PAYMENT_STATUS_EXECUTED" icon="circle-check-big">
    **Description**: Funds have successfully left the payer's account.

    **Final Success Status**: After this status, the transfer moves to `funds_received` and follows the standard transfer flow.

    **What's Next**: Transfer continues with normal processing (`funds_received` → `payment_submitted` → `payment_processed`)
  </Accordion>
</AccordionGroup>

### Open Banking Exception States

<AccordionGroup>
  <Accordion title="PAYMENT_STATUS_FAILED" icon="triangle-alert">
    **Description**: System error occurred during payment processing (retryable).

    **Common Causes**:

    * Bank system downtime
    * Temporary Open Banking service issues
    * Network connectivity problems

    **Action Required**: Create a new Open Banking link and retry the payment process.

    <Warning>
      This is a retryable error. The payment can be attempted again with a fresh Open Banking link.
    </Warning>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_BLOCKED" icon="ban">
    **Description**: Payment blocked by Plaid due to compliance or risk issues (rare, retryable).

    **What happened**: Plaid's risk management system flagged the payment for review.

    **Action Required**: Create a new Open Banking link and retry. If the issue persists, contact support.

    <Note>
      This is rare but can happen due to risk assessment algorithms. Usually resolves with a new attempt.
    </Note>
  </Accordion>

  <Accordion title="PAYMENT_STATUS_REJECTED" icon="circle-x">
    **Description**: Payment was rejected by the bank (terminal status).

    **What happened**: The bank declined the payment after initial authorization.

    **Important**: If funds were debited, the bank will automatically return them to the source account.

    **Final State**: This is a terminal status - the payment cannot be retried with the same link.
  </Accordion>

  <Accordion title="PAYMENT_STATUS_CANCELLED" icon="user-x">
    **Description**: The end user cancelled the payment during authorization (terminal status).

    **What happened**: User actively cancelled the payment process while authorizing with their bank.

    **User Action**: User chose to abandon the payment flow before completion.

    **Final State**: This is a terminal status - the payment cannot be retried with the same link.
  </Accordion>
</AccordionGroup>

### Open Banking Status Transitions

<Info>
  **Key Points**:

  * Open Banking statuses replace `awaiting_funds` in the standard flow
  * Only `PAYMENT_STATUS_EXECUTED` leads to `funds_received`
  * Failed, blocked, or rejected statuses require creating a new Open Banking link
  * The flow can move backwards (e.g., `INITIATED` → `FAILED`)
</Info>

**Complete Flow Diagram**:

```
PAYMENT_STATUS_INPUT_NEEDED
    ↓
PAYMENT_STATUS_AUTHORISING
    ↓
PAYMENT_STATUS_INITIATED → PAYMENT_STATUS_FAILED (retry needed)
    ↓                   → PAYMENT_STATUS_BLOCKED (retry needed)  
    ↓                   → PAYMENT_STATUS_REJECTED (terminal)
PAYMENT_STATUS_EXECUTED
    ↓
funds_received → payment_submitted → payment_processed
```

***

## Monitoring Transfer Status

### Check Individual Transfer Status

Monitor specific transfers using the status endpoints:

<CodeGroup>
  ```bash On-Ramp Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Onramp Transaction Status API Reference](/api-reference/audit-reporting/get-onramp-transaction-status)

  ```bash Off-Ramp Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/offramp-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Offramp Transaction Status API Reference](/api-reference/audit-reporting/get-offramp-transaction-status)

  ```bash FX Transfer Status theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/fx-audit/status/{transaction_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Transfer Transaction Status API Reference](/api-reference/audit-reporting/get-transfer-transaction-status)
</CodeGroup>

### Bulk Transfer Monitoring

Get status for multiple transfers by user:

<CodeGroup>
  ```bash User On-Ramp History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/{wallet_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Onramp Audit API Reference](/api-reference/audit-reporting/get-onramp-audit)

  ```bash User Off-Ramp History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/offramp-audit/{user_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Offramp Audit API Reference](/api-reference/audit-reporting/get-offramp-audit)

  ```bash User FX History theme={null}
  curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/fx-audit/{user_id}' \
  --header 'x-api-key: <api-key>'
  ```

  [Get Transfer Audit API Reference](/api-reference/audit-reporting/get-transfer-audit)
</CodeGroup>

***

## State Progression Rules

<Info>
  **Important**: Transfers always progress forward through states and never go backwards:

  `awaiting_funds` → `funds_received` → `payment_submitted` → `payment_processed`
</Info>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Configure Webhooks" icon="webhook" href="/documentation/getting-started/configure-webhook" arrow="true" horizontal>
    Set up real-time notifications for status changes
  </Card>

  <Card title="Webhook Verification" icon="shield-check" href="/documentation/developer-platform/monitoring/webhook-verification" arrow="true" horizontal>
    Learn how to verify webhook authenticity
  </Card>
</CardGroup>

## Getting Help

<Columns cols={1}>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz" arrow="true">
    When contacting support, please include:
    <Check>**Transaction ID** of the payment</Check>
    <Check>**Wallet ID** If transfer ID not available</Check>
    <Check>**Transfer type** (FX, on-ramp, off-ramp)</Check>
    <Check>**Error messages** or **status codes** </Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>