Migrate to V2

This document outlines the key changes when migrating from FX API v1 to v2.

General Changes

All v2 endpoints require the X-Trace-Version: "2" header
Resource and data structure changes as detailed below
Improved consistency in error handling and response formats

Request/Response Structure Changes

Currency Pair

V1:

"currencyPair": "BRL_USD"

V2:

"currencyPair": {
  "source": "BRL",
  "target": "USD"
}

In the V2 object:

source represents the currency of origin (the currency being exchanged from)
target represents the destination currency (the currency being exchanged to)

For example, the V1 string representation "BRL_USD" is equivalent to the V2 object representation { "source": "BRL", "target": "USD" }.

Usage examples:

When buying USD with BRL, use: { "source": "BRL", "target": "USD" }
When selling USD for BRL, use: { "source": "USD", "target": "BRL" }

The source and target currencies together with the operation field determine the direction of the exchange.

Amount Object

V1:

"amount": {
  "value": 1500000,
  "currency": "BRL"
}

V2:

"amount": {
  "value": 1500000,
  "decimals": 2,
  "currency": "BRL"
}

The decimals field specifies the decimal precision, with the default being 2.

Example:

{
  "value": 100000,
  "decimals": 2,
  "currency": "USD"
}

This represents USD 1,000.00 (100000 ÷ 10^2).

Operation/Side

V1:

"side": "BUY"

V2:

"operation": "BUY"

Terminology Changes

V1 Term	V2 Term
`side`	`operation`
`merchantId`	`counterpartyId`
`spotPrice`	`referenceRate`
`retailPrice`	`customerRate`
`payAmount`	`paymentAmount`

Order Status Changes

V1 Status	V2 Status
`OPEN`	`CREATED`
`CLOSED`	removed
`COMPLETED`	`COMPLETED`
`FAILED`	removed
`CANCELED`	`CANCELED`

Key Status Changes:

The OPEN status is now CREATED in V2
The CLOSED status has been removed from V2
The FAILED status has been removed from V2
The order status is now part of a state object that includes timestamps and reason information
V2 maintains a history of state changes in the states array
Failure scenarios are handled through the reason object within the state

Company ID

Now explicitly included in all responses:

"companyId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6"

Webhook Events

V1 Event	V2 Event
`ORDER_OPEN`	`ORDER_CREATED`
`ORDER_CLOSED`	removed
`ORDER_CANCELED`	`ORDER_CANCELED`
`ORDER_FAILED`	removed
`ORDER_COMPLETED`	`ORDER_COMPLETED`

Webhook Event Changes:

The event payload structure has been updated to match V2 API response formats
The ORDER_OPEN event is now ORDER_CREATED
The ORDER_CLOSED event has been removed
The ORDER_FAILED event has been removed
Event structure includes nested state information instead of flat status fields
Failure information is included in the reason field of the order state

Create Quote Endpoint

V1:

{
  "currencyPair": "BRL_USD",
  "merchantId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "expiresIn": 300
}

V2:

{
  "currencyPair": {
    "source": "BRL",
    "target": "USD"
  },
  "counterpartyId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "expiresIn": 300
}

Create Order Endpoint

V1:

{
  "currencyPair": "BRL_USD",
  "amount": {
    "value": 1500000,
    "currency": "BRL"
  },
  "merchantId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "quoteId": "24b2ae17-5a58-4465-acbb-45e11fdc2496",
  "idempotentId": "24b2ae17-5a58-4465-acbb-45e11fdc2496"
}

V2:

{
  "currencyPair": {
    "source": "BRL",
    "target": "USD"
  },
  "amount": {
    "value": 1500000, 
    "currency": "BRL"
  },
  "counterpartyId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "quoteId": "24b2ae17-5a58-4465-acbb-45e11fdc2496",
  "idempotentId": "24b2ae17-5a58-4465-acbb-45e11fdc2496"
}

Order Response Structure

V1:

{
  "id": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "idempotentId": "24b2ae17-5a58-4465-acbb-45e11fdc2496",
  "merchant": {
    "id": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
    "name": "PayPal"
  },
  "company": {
    "id": "93360f9a-5827-4c60-9ccd-c3b9a3c90cab",
    "name": "PayPal"
  },
  "side": "BUY",
  "currencyPair": "BRL_USD",
  "payAmount": {
    "value": 1500000,
    "currency": "BRL"
  },
  "receiveAmount": {
    "value": 300000,
    "currency": "USD"
  },
  "spotPrice": 5.1289,
  "retailPrice": 5.1689,
  "status": "OPEN",
  "createdAt": "2023-01-01T12:35:25Z"
}

V2:

{
  "id": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "idempotentId": "24b2ae17-5a58-4465-acbb-45e11fdc2496",
  "companyId": "93360f9a-5827-4c60-9ccd-c3b9a3c90cab",
  "counterpartyId": "fd6f3913-c44c-4a08-b81a-773e0de3c8c6",
  "operation": "BUY",
  "currencyPair": {
    "source": "BRL",
    "target": "USD"
  },
  "paymentAmount": {
    "value": 1500000,
    "decimals": 2,
    "currency": "BRL"
  },
  "receiveAmount": {
    "value": 300000,
    "decimals": 2,
    "currency": "USD"
  },
  "referenceRate": 5.1289,
  "customerRate": 5.1689,
  "currentState": {
    "status": "CREATED",
    "reason": null,
    "createdAt": "2023-08-17T12:35:25Z"
  },
  "states": [
    {
      "status": "CREATED",
      "reason": null,
      "createdAt": "2023-08-17T12:35:25Z"
    }
  ],
  "createdAt": "2023-08-17T12:35:25Z",
  "updatedAt": "2023-08-17T12:35:25Z"
}