Transfers

Levl's Transfer API endpoint enables you to transfer funds on behalf of your customers to their beneficiaries. Once your wallet has been funded you are ready to start raising transfer requests. A transfer request specifies who you are sending funds on behalf of, the intended recipient of those funds, the source wallet to be used for funding the transfer, the amount of funds to be transferred and the currency (transfer currency) that the funds should be received in.

Idempotency

The transfer creation endpoint supports idempotency through the Idempotency-Key header. When you send a request with the same idempotency key multiple times, the system will return the same response and won't create duplicate transfers.

The response includes an Idempotency-Replayed header that indicates whether the response was served from cache (true) or a new transfer was created (false).

Important:

  • The idempotency key must be a valid UUID and is required for all transfer creation requests.
  • Idempotency keys are cached for 24 hours (TTL). After this period, the same key can be reused for a new transfer request.

Source Amount vs Transfer Amount

The Levl Transfer API enables you to express whether you want to send a specific amount of the source currency (currency associated with the funding wallet) or if you want the beneficiary to receive a specific amount of a given target (transfer) currency. The flexible model accommodates both remittance and bill payment transfer scenarios.

Remittance

As an example of a remittance-type scenario, if your intention was to use 100 USDT to fund the transfer and for the beneficiary to receive GBP (amount dictated by the prevailing interbank FX rate and your pre-agreed fee schedule) then in your transfer request you would specify source.amount of 100 and leave destination.amount blank; the system will calculate destination.amount to be received.

Bill Payment

As an example of a bill payment-type scenario, if your intention is for the beneficiary to receive a specific amount of a target currency, for example £1000 GBP for payment of an invoice, you would specify destination.amount of 1000 and leave source.amount blank; the system will calculate source.amount of the source currency required to facilitate the transfer.


Transfer Statuses

The current state of a transfer is given by its status value. Possible states include:

  • SCHEDULED – Payment authorized, ready for payout
  • PROCESSING – Evaluating transfer requirements, authorizing payment
  • SENT – Money being sent, transfer in transit
  • PAID – Money delivered, transfer completed
  • FAILED – Transfer failed; an error occurred during processing