Skip to main content
Execute a currency conversion between two currencies held in your Syncgram Pay balance. You must provide a quote_id from POST /api/v1/conversions/quotes to lock the rate before executing.

​
Execute a conversion

POST /api/v1/conversions
Authentication: API key or JWT (Authorization: Bearer <token>)

​
Request

​
from_currency
string
required
The currency to convert from. Example: USD.
​
to_currency
string
required
The currency to convert to. Example: NGN.
​
amount
number
required
The amount in from_currency to convert.
​
quote_id
string
required
A quote ID from POST /api/v1/conversions/quotes. The conversion executes at the rate locked in the quote.

​
Response

​
conversion_id
string
Unique identifier for this conversion.
​
status
string
Conversion status. Typically COMPLETED for synchronous conversions.
​
from_currency
string
Source currency.
​
to_currency
string
Destination currency.
​
from_amount
string
Amount debited in from_currency.
​
to_amount
string
Amount credited in to_currency.
​
exchange_rate
string
Rate applied to the conversion.
​
created_at
string
ISO 8601 timestamp when the conversion was executed.
​
quote_id
string
The quote ID used, if one was provided. Maps to reference_id internally.
​
metadata
object
Additional details about the conversion, including settlement_status and swapped_before_settlement.
{
  "conversion_id": "cvn_01j9kxp4q8m2r3t5v6w7y8z9",
  "status": "COMPLETED",
  "from_currency": "USD",
  "to_currency": "NGN",
  "from_amount": "1000.00",
  "to_amount": "1560500.00",
  "exchange_rate": "1560.50",
  "created_at": "2024-01-15T10:05:22Z",
  "quote_id": "cvq_01j9kxp4q8m2r3t5v6w7y8z9",
  "metadata": {
    "settlement_status": "SETTLED",
    "swapped_before_settlement": false
  }
}

​
Error codes

StatusDescription
400 Bad RequestUnsupported currency pair, insufficient balance, or expired quote
422 Unprocessable EntityValidation error on one or more fields

​
Example

curl -X POST https://api.syncgrampay.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_01j..." \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "NGN",
    "amount": 1000,
    "quote_id": "cvq_01j9kxp4q8m2r3t5v6w7y8z9"
  }'

​
List conversions

GET /api/v1/conversions
Authentication: API key or JWT Returns a paginated list of conversions for your organization.

​
Query parameters

​
limit
integer
Number of results per page. Min 1, max 100. Defaults to 50.
​
offset
integer
Number of results to skip. Defaults to 0.
​
from_currency
string
Filter by source currency.
​
to_currency
string
Filter by destination currency.
​
status
string
Filter by conversion status.
​
start_date
string
ISO 8601 start date for filtering by created_at.
​
end_date
string
ISO 8601 end date for filtering by created_at.

​
Response

​
total
integer
Total number of conversions matching the filters.
​
limit
integer
Page size used for this response.
​
offset
integer
Offset used for this response.
​
items
array
Array of conversion objects. Each item has the same shape as the execute conversion response.
{
  "total": 42,
  "limit": 50,
  "offset": 0,
  "items": [
    {
      "conversion_id": "cvn_01j9kxp4q8m2r3t5v6w7y8z9",
      "status": "COMPLETED",
      "from_currency": "USD",
      "to_currency": "NGN",
      "from_amount": "1000.00",
      "to_amount": "1560500.00",
      "exchange_rate": "1560.50",
      "created_at": "2024-01-15T10:05:22Z",
      "quote_id": "cvq_01j9kxp4q8m2r3t5v6w7y8z9",
      "metadata": {
        "settlement_status": "SETTLED",
        "swapped_before_settlement": false
      }
    }
  ]
}

​
Example

curl "https://api.syncgrampay.com/api/v1/conversions?limit=10&from_currency=USD" \
  -H "Authorization: Bearer sk_live_01j..."

​
Get a conversion

GET /api/v1/conversions/{conversion_id}
Authentication: API key or JWT Returns a single conversion by ID.

​
Path parameters

​
conversion_id
string
required
The conversion_id returned when the conversion was created.

​
Example

curl https://api.syncgrampay.com/api/v1/conversions/cvn_01j9kxp4q8m2r3t5v6w7y8z9 \
  -H "Authorization: Bearer sk_live_01j..."