Skip to Content
OpenRoam Docs
Wallets

Transfer between wallets

Moves funds from one of the partner's wallets to another, converting between their currencies.

POST
/v1/wallets/transfer

Moves funds from one of the partner's wallets to another, converting between their currencies.

amount is in the source wallet's currency and has at most that currency's ISO 4217 decimals (none in KRW or JPY, three in KWD, two in most); more decimals return 400 with code 10001 and INVALID_VALUE at amount, whose message names the decimals allowed, such as An amount in JPY cannot have decimals. The destination receives the amount converted at the current rate, rounded to its own currency's decimals. Returns the transferId, the sent and received amounts and currencies, the conversionRate and the transferDate. Both wallets record an exchange transaction.

The two wallets must differ, and the amount must be above zero; otherwise the call returns 400 with code 10001. An unknown wallet returns 404 with code 10004. A source wallet that cannot pay the amount now returns 409 with code 10005 (CONFLICT) and details[0] = { path: "fromWalletId", reason }: INSUFFICIENT_BALANCE when its balance is too low, WALLET_BLOCKED while its spending is blocked. The same request can succeed once that changes.

Requires an Idempotency-Key header (a UUID). Repeating a completed transfer with the same key and body returns 200 with that transfer, the same transferId and amounts, and moves no money again. One still running returns 409 with code 12002 (IDEMPOTENCY_KEY_IN_PROGRESS) and a Retry-After header, and a different body with the same key 409 with code 12001. A request that ended in an error can be sent again with the same key and body.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

The source wallet, destination wallet and amount.

  1. body

A transfer between two of the partner's wallets.

fromWalletId*string

Required. The wallet the funds leave.

Formatuuid
toWalletId*string

Required. The wallet the funds arrive in; it must differ from the source.

Formatuuid
amount*number

Required. Amount above zero, in the source wallet's currency, rounded to two decimals.

Formatdecimal

Response Body

OK

  1. response

A completed transfer between two wallets.

transferId*string

Transfer id.

Formatuuid
sentAmount*number

The amount taken from the source wallet.

Formatdecimal
sentCurrency*string

The source wallet's currency.

receivedAmount*number

The amount added to the destination wallet.

Formatdecimal
receivedCurrency*string

The destination wallet's currency.

conversionRate?|

Destination currency units per source currency unit.

Formatdecimal
transferDate*string

When the transfer was made (UTC).

Formatdate-time
Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/wallets/transfer' \  -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \  -H 'Content-Type: application/json' \  -d '{  "fromWalletId": "fb1c4c02-71ca-4085-863d-084ecf5628ac",  "toWalletId": "afdf8623-df8b-4b07-8ef1-eb7d6dd819ad",  "amount": 0}'
Example Response
{  "transferId": "e240f72a-b0bc-4f57-ab86-5b78f1d8ea9b",  "sentAmount": 0,  "sentCurrency": "string",  "receivedAmount": 0,  "receivedCurrency": "string",  "conversionRate": 0,  "transferDate": "2019-08-24T14:15:22Z"}