Create FX Transaction

Use this API to create a transaction intent for FX Transactions. This API will respond with a Transaction ID, use this Transaction ID in the GET Transaction endpoint to get the FX quotation (e.g. exchange rate)

Example POST to create an FX Transaction (transaction intent)

curl -X POST 'https://developer-api-staging.pavebank.dev/v1/fx/transaction' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --data '{
  "base_account_id": "account_<Example_GBP_Account>",
  "quote_account_id": "account_<Example_JPY_Account>",
  "requested_asset": "JPY",
  "requested_amount": "100000",
  "description": "FX Example Transaction Intent"
}'

This API will respond with a transaction_id

{
  "transaction_id": "transaction_1jt9vwzof57z427158knbxsf2s"
}

Use this transaction_id in the GET Transaction endpoint to get the FX Transaction. This is a transaction intent and not an executed FX Transaction. If you would like to execute the FX Transaction, use the FX Transaction PUT API.

It might take several seconds for the Transaction to be able to be retrieved by this API. If you get a 404 error, please try again in 5-15 seconds.

// Example transaction response after using transaction_1jt9vwzof57z427158knbxsf2s 

{
  "transaction_id": "transaction_1jt9vwzof57z427158knbxsf2s",
  "status": "intent_created",
  "timestamp": "2025-11-28T09:08:10.728212Z",
  "type": "FX-TRADE",
  "customer_type": "Exchange (Currency)",
  "fx_trade": {
    "initiated_at": "2025-11-28T09:08:23.729004Z",
    "processed_at": "2025-11-28T09:08:23.729004Z",
    "executed_at": "2025-11-28T09:08:23.729004Z",
    "initiated_by": {
      "id": "user_<YOUR_USER_ID>",
      "first_name": "",
      "last_name": ""
    },
    "checked_at": null,
    "checked_by": null,
    "sell_amount": "48785", 
    "sell_asset": "GBP", // The base asset 
    "buy_amount": "100000", // The requested amount  
    "buy_asset": "JPY", // The requested asset 
    "fee_asset": "",
    "fee_amount": null,
    "conversion_rate": "204.9806247720",
    "sell_account_name": "Current Account GBP",
    "sell_account_iban": "<SELL_ACCOUNT_IBAN>",
    "sell_account_id": "account_<Example_GBP_Account>",
    "buy_account_name": "Current Account JPY",
    "buy_account_iban": "<BUY_ACCOUNT_IBAN>",
    "buy_account_id": "account_<Example_JPY_Account>",
    "to_legal_entity_id": "legalentity_<LEGAL_ENTITY_ID>",
    "to_legal_entity_name": "",
    "from_legal_entity_id": "legalentity_<LEGAL_ENTITY_ID>",
    "from_legal_entity_name": "",
    "description": "FX Example Transaction Intent"
  }
}

The transaction intent will automatically expire if the transaction intent is not executed

Authorization

AuthorizationRequiredBearer <token>

Enter your token in the format: Bearer {token}

In: header

Request Body

application/jsonOptional

base_account_idRequiredstring

descriptionRequiredstring

quote_account_idRequiredstring

requested_amountRequiredstring

The amount of money. Our API expect amount values to be in minor units - the smallest unit of a currency depending on the number of decimals. For example, USD has two decimals. So $10 is represented by 1000. JPY has no decimals, so ¥10 is 10.

requested_assetRequiredstring

The currency in which the amount is made (e.g. USD, EUR, SGD)

Header Parameters

idempotency-keyRequiredstring

Response Body

Success response

transaction_idRequiredstring

curl -X POST "https://developer-api-staging.pavebank.dev/v1/fx/transaction" \
  -H "idempotency-key: string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "base_account_id": "string",
    "description": "string",
    "quote_account_id": "string",
    "requested_amount": "string",
    "requested_asset": "string"
  }'

{
  "transaction_id": "string"
}