/ Guides / Payments / Send payments / Create payments with exchange

Create payments with exchange

Send a payment with an exchange to either a recipient or another Equals Money account.

A payment with an exchange allows you to send funds to a recipient in a currency that you aren't currently holding. For example, if you want to send funds in USD but only have a balance in GBP.

info

Currently, you can only make payments from the parent budget, not from any sub-budgets.

How it works

The following diagram describes the different steps required to send funds externally with Equals Money. Click on the image to enlarge it.

Diagram showing the steps required to send funds externally

Create a payment with exchange

Post/v2/orders/trade?accountId={accountId}

Before you start

To send a payment with an exchange, you first need to create a quote where:

  • type.from is set to balance
  • type.to is set to payment , multiple , or forward
  • sourceCurrency and targetCurrency are set to different currencies
  • either sourceCurrency.amount or targetCurrency.amount is provided
  • sourceCurrency.currency.budgetId and targetCurrency.currency.budgetId are set to the ID of the parent budget

For example, to make a 10 GBP payment to a recipient who wants to receive USD:

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/orders/quote?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrency": {
      "amount": 10,
      "currency": {
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "currencyCode": "GBP"
      }
    },
    "targetCurrency": {
      "currency": {
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "currencyCode": "USD"
      }
    },
    "settlementDate": "20231001",
    "type": {
      "from": "balance",
      "to": "payment"
    }
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/orders/quote?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceCurrency": {
      "amount": number,
      "currency": {
        "budgetId": string",
        "currencyCode": "string"
      }
    },
    "targetCurrency": {
      "currency": {
        "budgetId": "string",
        "currencyCode": "string"
      }
    },
    "settlementDate": "string",
    "type": {
      "from": "string",
      "to": "string"
    }
  }'

Request

Use this request to create a payment with exchange, using the orderId and quoteRequestId returned when you created a quote.

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/orders/trade?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "orderId": "FPLZQVE5G2ZZKS",
    "quoteRequestId": "SLQMQKRV8NR32DA3T0GZ7OC1SNDKO7X1HH",
    "payments": {
      "amount": 10,
      "currency": {
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "currencyCode": "GBP"
      },
      "recipientId": "8lciyups6",
      "internalReference": "REF-123-456",
      "externalReference": "REF-123-456"
    }
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/orders/trade?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "orderId": "string",
    "quoteRequestId": "string",
    "payments": {
      "amount": number,
      "currency": {
        "budgetId": "string",
        "currencyCode": "string"
      },
      "recipientId": "string",
      "internalReference": "string",
      "externalReference": "string"
    }
  }'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating an order for.

Allowable values:
An existing accountId

Request body schema

Parameter Description
orderId
string
required		 The ID of the order that was returned in the quote request.

Allowable values:
An existing orderId (<= 36 characters)
quoteRequestId
string
required		 The ID of the quote request.

Allowable values:
An existing quoteRequestId (<= 36 characters)
payments
object
required		 Details about the payment.

Allowable values:
A valid payments object containing the following fields: amount, currency, recipientId, internalReference, externalReference
payments.amount
number
required		 The amount that the recipient will receive.

Allowable values:
A valid number
payments.currency
object
required		 Details about the currency of the payment.

Allowable values:
A valid currency object containing the following fields: budgetId, currencyCode
payments.currency.budgetId
string
required		 The ID of the budget.

Allowable values:
An existing budgetId (<= 36 characters)
payments.currency.currencyCode
string
required		 The currency code, in ISO-4217 format.

Allowable values:
= 3
payments.recipientId
string
required		 The ID of the recipient that you're sending the payment to.

Allowable values:
An existing quoteRequestId (<= 36 characters)
payments.internalReference
string		 The payment reference that you see.

Allowable values:
<= 256 characters
payments.externalReference
string		 The payment reference that the recipient sees.

Allowable values:
<= 256 characters

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "orderId": "FPLZQVE5G2ZZKS",
  "quoteRequestId": "SLQMQKRV8NR32DA3T0GZ7OC1SNDKO7X1HH",
  "settlement": {
    "date": "20230825",
    "price": {
      "amount": 10,
      "currency": "GBP"
    },
    "charges": {
      "fee": 0
    }
  },
  "quote": {
    "rate": 1,
    "inverseRate": 1,
    "fromGbpAmount": 10,
    "from": {
      "amount": 10,
      "currency": "GBP"
    },
    "to": {
      "amount": 10,
      "currency": "USD"
    },
    "direction": "1"
  }
}
Copy
Copied
{
  "orderId": "string",
  "bank": "string",
  "settlement": {
    "date": "string",
    "price": {
      "amount": number,
      "currency": "string"
    },
    "charges": {
      "fee": number,
      "margin": number,
      "other": number
    }
  },
  "trade": {
    "rate": number,
    "inverseRate": number,
    "from": {
      "amount": number,
      "currency": "string"
    },
    "to": {
      "amount": number,
      "currency": "string"
    },
    "direction": "string"
  }
}
warning

For customers where the external reference affects account ownership validation:

If the provided external reference doesn’t match the one associated with the recipient, an error will occur. To resolve this, resubmit the request with the correct external reference, or create a new recipient with the preferred external reference.

For more detailed information about this request and its response, see the API reference.