Currency Conversion

Create an Exchange Payment

This endpoint allows users to initiate a currency exchange between two accounts with different currencies. It initiates a currency exchange transaction that converts funds from one currency to another, debiting a source account and crediting a destination account.

This API allows you to convert funds between different currencies. The system will automatically calculate the exchange rate based on current market rates, apply applicable fees, and credit an existing destination account. An account in the destination currency must exist for exchanges occurring within your Institution accounts.

However, for cases where exchanges are placed against a future settlement (such as sub-account exchange booking), a virtual account is created in the destination currency for the sub-account customer.

Request Parameters

Parameter	Type	Required	Description
`amount`	`number`	Yes	The amount to be exchanged.
`source_account_id`	`uuid`	Yes	The ID of the source account for the exchange.
`fixed_side`	`string`	No	Specifies whether the source or destination is fixed.
`destination`	`object`	Yes	Where the converted funds should be go to. See Destination Type

Example Request

{
  source_account_id: "5e7dc45a-b1a2-4c3d-9876-f543ab21cd09",
  amount: 10000,
  fixed_side: "source",
  description: "Transfer funds to EUR account",
  client_reference: "client-ref-123456",
  destination: {
    type: "account",
    account_id: "f8c3de45-1a23-40b7-9c12-bd567e4a9f01"
  }
}

{
  source_account_id: "5e7dc45a-b1a2-4c3d-9876-f543ab21cd09",
  amount: 5000,
  fixed_side: "source",
  description: "Exchange USD to EUR via batch",
  client_reference: "batch-fx-789012",
  destination: {
    type: "fx_settlement_batch",
    currency: "EUR"
  }
}

Example Response

{
  "data": {
    "id": "019633b5-980b-7c1a-bb53-4fb154c2320f",
    "state": "COMPLETED",
    "created_date": "2025-04-14T09:51:01.131Z",
    "updated_date": "2025-04-14T09:51:04.886Z",
    "source": {
      "id": "019633b4-ef1e-73c4-b99c-fa857b2a2683",
      "type": "Account"
    },
    "destination": {
      "id": "019633b4-ef71-786d-8141-184ba45e7c65",
      "type": "Account"
    },
    "source_amount": 200000,
    "source_currency": "USD",
    "billing_amount": 200000,
    "billing_currency": "USD",
    "total_fee_amount": 0,
    "total_fee_currency": "USD",
    "destination_amount": 160000,
    "destination_currency": "GBP",
    "currency": "USD",
    "internal_reference": "wz-exchange-rugY-1744624261127",
    "identifiers": [],
    "payment_initiator": {
      "id": "019633b4-b78b-7083-a958-1f470c90eb89",
      "email": "[email protected]",
      "name": "Mina Medhurst"
    },
    "completion_date": "2025-04-14T09:51:04.877Z",
    "description": "Currency exchange from USD to GBP",
    "direction": "OUTBOUND",
    "type": "EXCHANGE",
    "client_metadata": {},
    "balance_before": 10000000,
    "balance_after": 9800000
  }
}

The API will respond with the relevant exchange details upon a successful request. Sub-account exchange order bookings will return with an fx_settlement_id which can be used to reconcile the single exchange in a bulk settlement scheduled to happen at a later time