Create a cash deposit request to enable a nominated identity to subsequently deposit cash at a specified retailer.

This endpoint triggers a workflow which orchestrates the deposit of funds at a nominated retailer. To initiate the workflow this endpoint requires:

• retailerId of the retailer where the deposit will be made.
• identityId of the end user making the deposit.
• A wallet specifying the blockchain address where deposited funds will be transferred.
• A deviceLocation with the user's latitude and longitude coordinates.

Optionally, an amount (source currency) or amountOut (target currency) can be specified to lock the deposit to a specific value. If neither is provided, the POS will accept any amount. Only one of amount or amountOut may be specified.

The endpoint will return generated deposit request details with a barcodeNumber which can then be rendered and presented by the user at the retailer. This barcode will allow the retailer to correlate the user's visit with the registered cash deposit. When notification of a successful payment arrives from the retailer, a Deposit entry is created within our systems.

Concurrent barcodes

Creating a request can retire an existing one. The retailer network caps how many barcodes one identity may hold at once. When a create would exceed that cap, the network retires the identity's oldest live barcode and this endpoint returns 200 for the new one — the retired barcode moves to CANCELLED and will not scan.

The cap is the network's, not ours: it is not configurable here, no error is returned, and nothing in this response names the barcode that was retired. So do not treat a barcode as live because Create once returned it. Re-read status with Get before presenting one, and prefer reusing an outstanding barcode over creating another for the same identity.

Idempotency

Send an Idempotency-Key header. Within 24 hours, a repeat of the same key with an identical body replays the original response without re-running the request, so no second barcode is generated. The key is scoped to your customer account, the HTTP method and the request path, and the request body is hashed into it.

• 409 IDEMPOTENCY_IN_PROGRESS — the first request is still executing. Back off and retry the same request unchanged.
• 422 IDEMPOTENCY_KEY_REUSED — the key was sent with a different body. Do not retry; correct the key derivation.

If the response is lost, retry the same POST with the same key and the same body rather than querying first. Reusing a reference with a new Idempotency-Key does not deduplicate — only the key does.