Transfer Status - Carbn Connect

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:

Initiation

Transfer is created and awaiting funds or processing

Processing

Funds are being moved through the payment system

Completion

Transfer reaches final state (success, failure, or requires action)

Transfer States

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

awaiting_funds

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.

{
  "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
  "status": "awaiting_funds",
  "created_at": "2024-01-01T10:00:00Z",
  "source_currency": "eur",
  "amount": 100
}

funds_received

Description: Carbn has received the funds and is preparing to move them on the user’s behalf.Duration: Usually seconds to a few minutesWhat’s happening: Internal processing, validation, and preparation for onward transfer.

{
  "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
  "status": "funds_received",
  "updated_at": "2024-01-01T10:05:00Z",
  "source_currency": "eur",
  "amount": 100
}

in_review

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.

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

payment_submitted

Description: Carbn has initiated the payment and is awaiting confirmation.Duration varies by payment rail:

Crypto: Minutes
Wires: Hours
ACH: Days

{
  "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"
}

payment_processed

Description: The transfer is complete and funds have been successfully delivered to the destination.Final State: This is a successful completion state.

{
  "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
  "status": "payment_processed",
  "completed_at": "2024-01-01T10:12:00Z",
  "final_amount": 95.50,
  "destination_confirmed": true
}

Exception States

undeliverable

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.

returned

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.

refunded

Description: The transfer was refunded back to the original sender.Final State: This is a completion state where funds are returned.

canceled

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.

Transfers can only be canceled while in awaiting_funds status. Once funds are received, cancellation is no longer possible.

error

Description: A problem occurred that blocked processing. This typically requires manual review or developer action.Action Required: Contact support with transfer details for investigation.

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

PAYMENT_STATUS_INPUT_NEEDED

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 limitUser Action Required: User needs to click the Open Banking link and begin authorization with their bank.

{
  "transaction_id": "d5c48677-b85d-4de5-a685-196d0e6596f7",
  "payment_status": "PAYMENT_STATUS_INPUT_NEEDED",
  "created_at": "2024-01-01T10:00:00Z",
  "payment_method": "open_banking"
}

PAYMENT_STATUS_AUTHORISING

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 authorizationNext Steps: Wait for user to complete authorization or abandon the process.

PAYMENT_STATUS_INITIATED

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 bankPossible Outcomes: Can progress to EXECUTED, FAILED, BLOCKED, or REJECTED

PAYMENT_STATUS_EXECUTED

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)

Open Banking Exception States

PAYMENT_STATUS_FAILED

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.

This is a retryable error. The payment can be attempted again with a fresh Open Banking link.

PAYMENT_STATUS_BLOCKED

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.

This is rare but can happen due to risk assessment algorithms. Usually resolves with a new attempt.

PAYMENT_STATUS_REJECTED

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.

PAYMENT_STATUS_CANCELLED

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.

Open Banking Status Transitions

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)

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:

curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/status/{transaction_id}' \
--header 'x-api-key: <your-api-key>'

Bulk Transfer Monitoring

Get status for multiple transfers by user:

curl --location --request GET 'https://api.carbnconnect.com/payment/api/v1/onramp-audit/{wallet_id}' \
--header 'x-api-key: <your-api-key>'

State Progression Rules

Important: Transfers always progress forward through states and never go backwards:awaiting_funds → funds_received → payment_submitted → payment_processed