APG PayAPG Paydocs

FX rates

Create FX conversions

POST/fx-conversions

Convert an amount at an enterprise's rates. The answer is the conversion, nothing is stored.

Permissions

Required permission
fxRates:query

Requires the `query` action on `fxRates` for the supplied runtime context

Request body

This body is a tagged shape: type is always "FxconvCmdConvert". Send it; more variants can be added, and a caller that switches on it keeps working when they are.

Discriminated by type
type = "FxconvCmdConvert"
enterpriseIdEntIdrequired

Identifier of an enterprise.

Example ent_9f2Kd8QpLzXw

rateSetCodestringrequired

Which rate set to price from.

Example 0.9412

baseCurrencyIsoCurrencyrequired

The currency being converted from.

AFNDZDARSAMDAWGAUDAZNBSDBHDTHB
+156 more

PAB, BBD, BYR, BZD, BMD, VEF, BOB, BRL, BND, BGN, BIF, CAD, CVE, KYD, XOF, XAF, XPF, CLP, COP, KMF, CDF, BAM, NIO, CRC, HRK, CUP, CZK, GMD, DKK, MKD, DJF, STD, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, LAK, KWD, MWK, AOA, MMK, GEL, LBP, ALL, HNL, SLL, LRD, LYD, SZL, LSL, MGA, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, PEN, MRU, PKR, MOP, TOP, CUC, UYU, PHP, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, RSD, SCR, SGD, SBD, KGS, SOS, TJS, SSP, LKR, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, TTD, MNT, TND, TRY, TMT, AED, UGX, COU, CLF, UYI, USD, USN, USS, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWL, PLN

termCurrencyIsoCurrencyrequired

The currency being converted to.

AFNDZDARSAMDAWGAUDAZNBSDBHDTHB
+156 more

PAB, BBD, BYR, BZD, BMD, VEF, BOB, BRL, BND, BGN, BIF, CAD, CVE, KYD, XOF, XAF, XPF, CLP, COP, KMF, CDF, BAM, NIO, CRC, HRK, CUP, CZK, GMD, DKK, MKD, DJF, STD, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, LAK, KWD, MWK, AOA, MMK, GEL, LBP, ALL, HNL, SLL, LRD, LYD, SZL, LSL, MGA, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, PEN, MRU, PKR, MOP, TOP, CUC, UYU, PHP, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, RSD, SCR, SGD, SBD, KGS, SOS, TJS, SSP, LKR, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, TTD, MNT, TND, TRY, TMT, AED, UGX, COU, CLF, UYI, USD, USN, USS, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWL, PLN

customerBuysBasebooleanrequired

true where the customer is buying the base currency, so the ask rate applies; false where they are selling it, so the bid does. Required, half of all conversions would otherwise be priced on the wrong side of the spread.

Example true

roundingModestring

How to round, HALF_EVEN, HALF_UP, FLOOR, CEILING, DOWN, UP. Defaults to HALF_EVEN.

precisioninteger (int32)

Decimal places for the unrounded figure. Defaults to 8.

Example 1250

ratesAtstring (date-time)

Price at the rates as they stood at this instant. Defaults to the current rates.

Example 2026-08-19T04:21:07Z

curl -X POST https://api.tst.au.apgpay.dev/fx-conversions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "FxconvCmdConvert",
  "enterpriseId": "ent_9f2Kd8QpLzXw",
  "rateSetCode": "0.9412",
  "baseCurrency": "AUD",
  "termCurrency": "AUD",
  "amount": {
    "type": "FxconvAmountMajorUnits",
    "majorUnits": "string"
  },
  "customerBuysBase": true,
  "roundingMode": "string",
  "precision": 1250,
  "ratesAt": "2026-08-19T04:21:07Z"
}'

Responses

The response is a tagged shape: type is always "FxconvCreateRspAttributes". Switch on it; subtypes can be added, and a client that already reads it will not break.

Discriminated by type
type = "FxconvCreateRspAttributes"

The resource that was created.

Example
{
  "type": "FxconvCreateRspAttributes",
  "created": {
    "type": "FxconvViewAttributes",
    "enterpriseId": "ent_9f2Kd8QpLzXw",
    "rateSetCode": "0.9412",
    "sourceAmount": "string",
    "amounts": {
      "type": "FxconvAmountsAttributes",
      "sourceCurrency": "AUD",
      "termCurrency": "AUD",
      "termAmountMinorUnits": 1250,
      "termAmountMajorUnits": "string",
      "termAmountUnrounded": "string"
    },
    "rate": {
      "type": "FxconvRateAttributes",
      "baseCurrency": "AUD",
      "termCurrency": "AUD",
      "exchangeRate": "0.9412"
    },
    "crossRates": [
      {
        "type": "FxconvRateAttributes",
        "baseCurrency": "AUD",
        "termCurrency": "AUD",
        "exchangeRate": "0.9412"
      }
    ],
    "ratesUpdatedAt": "2026-08-19T04:21:07Z"
  }
}

Error responses