Create single-currency payments

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. Click on the image to enlarge it.

Diagram showing the steps required to send funds externally

Create a single-currency payment

POST /v2/orders/trade

Before you start

To send a single-currency payment, 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 the same currency
at least one of 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 create a quote for a 10 GBP payment to an external recipient:

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"
    }
  }'

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 single-currency payment, using the orderId and quoteRequestId returned when you created a quote.

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": "M35TVZVMB4NYPO",
    "quoteRequestId": "UFTDF36PC1YHKDB61QC4V4324ATF9KCDPV",
    "payments": {
      "amount": 10,
      "currency": {
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "currencyCode": "GBP"
      },
      "recipientId": "7d238pq10",
      "internalReference": "PAYX-123",
      "externalReference": "PAYX-123"
    }
  }'

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

accountId

string

required

The ID of the account that you’re creating a single-currency payments for.Allowable values: An existing accountId

Request body schema

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 that was returned in the quote request.Allowable values: An existing quoteRequestId (≤ 36 characters)

payments

object

required

Details about the payment that you’re making.Allowable values: A valid payments object containing the following fields: amount, currency, recipientId , internalReference, externalReference

Show payments properties

payments.amount

number

required

The payment amount.Allowable values: A valid number

payments.currency

object

required

Details about the payment’s currency.Allowable values: A valid currency object containing the following fields: budgetId, currencyCode

payments.recipientId

string

required

The ID of the recipient that you’re sending the payment to.Allowable values: An existing recipientId

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.

{
  "orderId": "M35TVZVMB4NYPO",
  "bank": "BANK",
  "settlement": {
    "date": "20231001",
    "price": {
      "amount": 10,
      "currency": "GBP"
    },
    "charges": {
      "fee": 0,
      "margin": 0,
      "other": 0
    }
  },
  "trade": {
    "rate": 0,
    "inverseRate": 0,
    "from": {
      "amount": 10,
      "currency": "GBP"
    },
    "to": {
      "amount": 10,
      "currency": "GBP"
    }
  }
}

{
  "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"
    }
  }
}

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.

Group placeholder

Group

Group

How it works

Create a single-currency payment

Before you start

Request

Query parameters

Request body schema

Response

​How it works

​Create a single-currency payment

​Before you start

​Request

​Query parameters

​Request body schema

​Response

How it works

Create a single-currency payment

Before you start

Request

Query parameters

Request body schema

Response