Get Transfer Status Guide

CROSSFX API · TRANSFER STATUS

See the entire transaction state in one call.

Retrieve the transfer together with its deposit, payout and refund legs to see exactly where the transaction has reached.

Use the same cbtx_tracking_id issued when the quote was generated. Webhooks remain the primary state signal; this endpoint gives you the current state on demand.

Transfer statusDepositPayoutRefundRead-only

What the endpoint returns

The Transfer Status API returns the parent Transfer and the transaction legs associated with it.

TRANSFER

Current transaction state

cbtx_tracking_id

↓

FUNDING LEG

Deposit

Funding state and deposit details.

DISBURSEMENT LEG

Payout

Payout state and disbursement details.

WHEN APPLICABLE

Refund

Refund state and return-of-funds details.

Whole transaction

One call, full context

Read the transfer status together with the nested `deposit`, `payout` and `refund` resources.

Tracking ID lookup

Use the transfer identifier

The path uses the same `cbtx_tracking_id` created when the quote was generated.

Safe to repeat

Read-only operation

This endpoint has no side effects and can be called repeatedly when you need the current state.

When to use Transfer Status

Webhooks should drive your normal asynchronous transaction handling. Use this endpoint when your application needs the current state immediately.

Customer status

Show current progress

Retrieve the transfer when your application needs to display where the transaction has reached.

Webhook recovery

Recover missed state

Read the transfer after a webhook was missed, delayed or not processed by your application.

Support investigation

Inspect the whole transaction

Give support or operations a single view of the transfer and every leg created against it.

STATE MANAGEMENT

Do not use Transfer Status as your primary polling loop.

Webhooks are the primary transaction-state signal. Use this endpoint on demand, after a missed delivery, or when a user or support workflow explicitly needs the current state.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Tracking ID

Use the quote-issued value

You need the exact `cbtx_tracking_id` returned by the [Generate Quote Guide](/generate-quote-guide-2167570m0).

Get transfer status

Get Transfer Status

Retrieve the transfer and its legs

`GET /api/v1/transfers/{cbtx_tracking_id}`

Open the API Reference for the full response schema and an interactive console.

REQUEST & RESPONSE

Send cbtx_tracking_id in the path.

The response returns the transfer together with its nested deposit, payout and refund resources.

Legs appear as they are created

A nested leg being null means that resource does not exist yet. It does not mean that the leg failed.

TRANSFER CREATED

pending_deposit

deposit = null

→

DEPOSIT CREATED

Funding leg exists

deposit ≠ null

→

PAYOUT CREATED

Disbursement leg exists

payout ≠ null

→

IF REQUIRED

Refund leg exists

refund ≠ null

NULL MEANS NOT CREATED

For example, payout = null means that no payout has been initiated yet. Do not interpret a null leg as a failed payout.

Transfer status vs leg status

The parent transfer and its individual legs use different status vocabularies.

TRANSFER STATUS

pending_deposit · pending_payout
pending_reconcile · completed
failed · refunding · refunded
refund_failed · cancelled

LEG STATUS

pending
processing
succeeded
failed

DO NOT INTERCHANGE THEM

Transfer state and leg state describe different things.

Always read transfer.status for the overall transaction lifecycle and the nested leg's own status when investigating a deposit, payout or refund.

Typical transfer progression

The normal transfer lifecycle moves through the states below as funding and payout complete.

pending_deposit

Await funding

The transfer has been created and needs funding.

→

pending_payout

Ready for payout

Funding has progressed and payout can be initiated.

→

pending_reconcile

Reconciliation

The transaction is being reconciled.

→

completed

Complete

The beneficiary was paid.

This is the normal progression only. Always handle the exact transfer status returned by the API, including failure, cancellation and refund states.

Business rules

SIGNAL

Webhooks first

Use webhooks as the primary state mechanism and this endpoint when you need to recover or read state on demand.

NULL LEGS

Not created yet

A null deposit, payout or refund means that leg does not yet exist. It is not a failure state.

STATUS

Separate vocabularies

The parent transfer and its individual transaction legs use different sets of status values.

REPEATABILITY

Safe to read again

The endpoint has no side effects and can be safely called whenever the latest stored state is required.

Errors

Every error below returns the CrossFX platform error envelope, with error first and error_id last.

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support and include the cbtx_tracking_id for the transfer being investigated.

HTTP	`code`	Trigger	What you do
404	`NOT_FOUND`	No transfer matches the `cbtx_tracking_id`	Use the exact value returned when the quote was generated.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Webhooks Guide

Receive state automatically

Use webhook events as the primary signal when a transfer or transaction leg changes.

CrossFX API Documentation

Understand the lifecycle

See the complete transfer, deposit, payout and refund model together with the full status progression.

What the endpoint returns#

When to use Transfer Status#

Before you start#

Get transfer status#

Legs appear as they are created#

Transfer status vs leg status#

Typical transfer progression#

Business rules#

Errors#

Related#