Initiate Deposit Guide

CROSSFX API · DEPOSITS

Report how the transfer is being funded.

Create the funding leg for a transfer by reporting an on-chain transaction or the fiat account providing the funds.

CrossFX verifies the reported funding before the transfer becomes payable. A successful 201 means the deposit was recorded, not that settlement has completed.

CRYPTOFIATTransfer-scopedFunding verification

How funding is reported

A deposit is always created against an existing transfer. The method determines which funding details CrossFX expects.

01

Confirmed transfer

pending_deposit

→

02

Choose method

CRYPTO or FIAT

→

03

Create deposit

Funding reported

→

04

Verify funding

Watch deposit status

Crypto or fiat

Two funding methods

`CRYPTO` reports an existing on-chain transaction. `FIAT` reports the client account supplying the funds.

Transfer-scoped

Always tied to one transfer

`cbtx_tracking_id` is part of the path, so every deposit belongs to a specific transfer.

Verified funding

Reporting is not enough

CrossFX verifies the funding before the transfer becomes ready for payout.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Confirmed transfer

Transfer must accept funding

The transfer must have been created through the Confirm Transfer Guide and be in pending_deposit.

Funding details

Have the method-specific data ready

For `CRYPTO`, you need the transaction hash and chain.

For `FIAT`, you need your client identifier for the prefunded account.

Initiate a deposit

Initiate Deposit

Create the funding leg

`POST /api/v1/payments/{cbtx_tracking_id}/deposits`

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

REQUEST & RESPONSE

Send cbtx_tracking_id in the path and method plus the fields required by that method in the request body.

You can also include an optional reference. A successful request returns the created deposit record.

CRYPTO vs FIAT

The method value changes the shape of the funding request.

METHOD = CRYPTO

Report an on-chain transaction

REQUIRED

details.transaction_hash
details.chain

The transaction must already exist on-chain before you report it.

METHOD = FIAT

Report the funding account

REQUIRED

client_identifier

Use the client identifier for the prefunded fiat account supplying the transfer.

METHOD CONTROLS THE BODY

Send only the fields required by the selected funding method.

CRYPTO requires details. FIAT requires client_identifier. Missing the method-specific field returns 422 VALIDATION_FAILED.

Crypto funding flow

For crypto funding, the blockchain transaction exists before the deposit is reported to CrossFX.

01 · ADDRESS

Get deposit address

→

02 · CHAIN

Send stablecoins

→

03 · REPORT

Initiate deposit

→

04 · VERIFY

Watch deposit status

CHAIN MUST MATCH

Report the blockchain network you actually used.

details.chain is case-sensitive and must match the chain on which the transaction was sent.

Crypto `details`

Inside the details object, send only:

transaction_hash

Blockchain transaction

The transaction hash for the stablecoin transfer you have already sent.

chain

Blockchain network

The exact, case-sensitive chain on which that transaction was sent.

Do not send additional keys inside details. Any other field is rejected with 422 VALIDATION_FAILED and identified under error.json.details.

Funding source compatibility

Not every transfer accepts every deposit method.

CLIENT-FUNDED TRANSFERS

funding_source = client_funds → use FIAT

A CRYPTO deposit cannot be reported against a client-funded transfer. Attempting it returns 400 BAD_REQUEST.

Transfer state requirement

A deposit can only be created while the transfer is waiting for funding.

TRANSFER→pending_deposit→Initiate Deposit allowed

If the transfer is in any other state, the request returns 400 BAD_REQUEST.

When you are unsure whether the transfer can accept a deposit, read its current state using the Get Transfer Status Guide.

A 201 is not settlement

A successful deposit request creates the funding record. Verification can still be in progress.

HTTP 201

Deposit recorded

CrossFX accepted the deposit declaration and created the deposit resource.

DEPOSIT SUCCEEDED

Funding verified

Watch the deposit's status or process the deposit.succeeded webhook before treating funding as settled.

Get Transfer Status Guide

Read the current deposit state

Retrieve the transfer and its nested deposit record on demand.

Webhooks Guide

Receive deposit events

Handle `deposit.succeeded` and `deposit.failed` asynchronously.

Your deposit reference

reference is optional and lets you attach your own identifier to the deposit.

reference

Your own deposit identifier

Send a string or omit the field. CrossFX stores it against the deposit but does not return it in the response, so retain your own copy if you need it for reconciliation. A non-string value is rejected with Not a valid string.

Business rules

METHOD

CRYPTO or FIAT

The selected method determines which additional funding fields are required.

CRYPTO

Send first, report second

Initiate Deposit declares an on-chain transaction that already exists.

STATE

pending_deposit only

Deposits are rejected when the parent transfer is in any other state.

SUCCESS

201 = recorded

Do not treat creation of the deposit resource as proof that funding has settled.

Currency resolution

currency_code is not restricted to an enum at request-validation time.

An unrecognised currency therefore returns 404 NOT_FOUND rather than a 422 enum-validation error.

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. Include the cbtx_tracking_id of the transfer and any relevant deposit reference.

HTTP	`code`	Trigger	What you do
422	`VALIDATION_FAILED`	A required field is missing or the wrong type, or `method` or `details.chain` is not an allowed value	Read `error.json` for the field.
422	`VALIDATION_FAILED`	The body carries a field the endpoint does not accept	Read `error.json` for the field name and remove it.
422	`VALIDATION_FAILED`	`details` is absent on a `CRYPTO` deposit, or `client_identifier` is absent on a `FIAT` one	Send the field required by the chosen `method`.
404	`NOT_FOUND`	No transfer matches the `cbtx_tracking_id`	Use the exact value returned by the quote.
400	`BAD_REQUEST`	The transfer is not in a state that can accept deposits	Read the transfer status. Only `pending_deposit` accepts a deposit.
400	`BAD_REQUEST`	A `CRYPTO` deposit was reported on a client-funded transfer	Fund it with `FIAT`.
404	`NOT_FOUND`	`currency_code` is not a currency the platform knows	Use a supported currency.
500	`INTERNAL_ERROR`	An unexpected internal error	Retry with backoff.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Get Transfer Status Guide

Track the deposit leg

Read the transfer and its nested deposit record while funding is being verified.

Webhooks Guide

Receive funding outcomes

Handle the `deposit.succeeded` and `deposit.failed` events.

Crypto Deposit Address Guide

Get a crypto funding address

Retrieve the address for the supported stablecoin and chain before sending the transaction.

How funding is reported#

Before you start#

Initiate a deposit#

CRYPTO vs FIAT#

Crypto funding flow#

Crypto details#

Funding source compatibility#

Transfer state requirement#

A 201 is not settlement#

Your deposit reference#

Business rules#

Currency resolution#

Errors#

Related#