> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Conversions

> Move a balance from one of your wallets into another currency at a rate you see first.

A conversion debits one of your wallets and credits another in a different currency. Nothing leaves Payve. Use it to hold the currency you will pay out in.

**Before you start:** a funded source wallet, and a key with the `conversions:write` scope.

## Quote, then convert

**1. Get a quote for a conversion**

Create a [quote](/guides/quotes.md) with `transactionType` set to `conversion`.

```bash
curl -X POST "$PAYVE_API_URL/v1/quotes" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "amount": 5000000,
    "transactionType": "conversion"
  }'
```

> [!WARNING]
>
> Set `transactionType` to `conversion`. A quote created for a payout can be priced differently from the rate a conversion settles at.

**2. Create the conversion**

Send the same currencies and amount with the `quoteId`.

**3. Wait for the event**

Payve sends `conversion.successful` or `conversion.failed`.

## Create a conversion

`POST /v1/conversions`

**Idempotency-Key** `string` *required*

A unique key for this conversion. Reuse it on every retry.

**sourceCurrency** `string` *required*

The wallet to debit.

**destinationCurrency** `string` *required*

The wallet to credit.

**amount** `integer` *required*

The amount in `sourceCurrency`, in minor units.

**merchantReference** `string` *required*

Your own reference, up to 255 characters.

**quoteId** `string`

A quote for the same currencies and amount.

**metadata** `object`

Your own key-value data.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/conversions" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: treasury-2026-11-18-ngn-ghs" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "amount": 5000000,
    "merchantReference": "treasury-2026-11-18",
    "quoteId": "qte_1a9c3e7b5d0f2846"
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/conversions`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Idempotency-Key': 'treasury-2026-11-18-ngn-ghs',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sourceCurrency: 'NGN',
    destinationCurrency: 'GHS',
    amount: 5000000,
    merchantReference: 'treasury-2026-11-18',
    quoteId: quote.id,
  }),
});
const { data: conversion } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/conversions",
    headers={
        "x-api-key": os.environ["PAYVE_API_KEY"],
        "Idempotency-Key": "treasury-2026-11-18-ngn-ghs",
    },
    json={
        "sourceCurrency": "NGN",
        "destinationCurrency": "GHS",
        "amount": 5000000,
        "merchantReference": "treasury-2026-11-18",
        "quoteId": quote["id"],
    },
)
conversion = res.json()["data"]
```

```json Response · 202
{
  "data": {
    "id": 1860,
    "publicId": "cnv_6e2b9a0d4c1f7385",
    "status": "pending",
    "subStatus": null,
    "sourceCurrency": "NGN",
    "destinationCurrency": "GHS",
    "sourceAmount": "5000000",
    "destinationAmount": "46500",
    "rate": "0.0093000000",
    "fee": "0",
    "merchantReference": "treasury-2026-11-18",
    "quoteId": "qte_1a9c3e7b5d0f2846",
    "userMessage": null,
    "createdAt": "2026-11-18T12:00:00.000Z"
  }
}
```

**id** `integer`

Use this in URLs: `GET /v1/conversions/{id}`.

**publicId** `string`

The `cnv_` id.

**status** `string`

`pending`, `processing`, `successful` or `failed`.

**sourceAmount** `string`

What leaves the source wallet, in minor units.

**destinationAmount** `string`

What reaches the destination wallet, in minor units.

**rate** `string | null`

The exchange rate applied.

**fee** `string`

Payve's fee, in minor units.

> [!WARNING]
>
> `202` means accepted. The destination wallet is credited only when the conversion is `successful`.
> Do not start a payout from the destination wallet until then.

## Wallets

Payve creates the source and destination wallets if you do not have them. The source wallet must hold the amount.

## Convert, or pay out across currencies?

| You want to | Use |
| - | - |
| Hold another currency for later | A conversion. |
| Pay someone in another currency now | A [payout](/guides/payouts.md#cross-currency-payouts) with different source and destination currencies. Payve converts as part of it. |

## Get and list conversions

| Request | Does |
| - | - |
| `GET /v1/conversions/{id}` | Returns one conversion, with a timeline in `events`. |
| `GET /v1/conversions` | Lists conversions. Filter with `status`, `from`, `to`, `q`; page with `cursor`. |
| `POST /v1/conversions/{id}/resend-webhook` | Sends a fresh event for a finished conversion. Needs `conversions:write`. |

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `400 validation_idempotency_key_required` | No `Idempotency-Key` header. | Send one. |
| `403 forbidden` | The key lacks `conversions:write`. | Use a key with the scope. |
| `403 kyc_tier_insufficient` | Your business is not verified. | Finish verification. |
| `422 validation_missing_field` | A field is missing, such as `merchantReference`. | Fix the fields named. |
| `422 wallet_insufficient_funds` | The source wallet cannot cover the amount. | Fund it, or convert less. |
| `422 quote_expired` | The quote is past its hold time. | Create a new quote. |
| `409 quote_already_consumed` | The quote was already used. | Create a new quote. |
| `404 resource_not_found` | No rate exists for that pair, or the quote is not yours. | Check the pair and the quote id. |

A conversion can also be accepted and fail afterwards. You then receive `conversion.failed`. Check both wallet balances before you try again.

## Cautions

> [!WARNING]
>
> **Do not retry a conversion with a new idempotency key after a timeout.** Retry with the same key.
> A second conversion under a new key converts the money twice.

> [!TIP]
>
> Use a `merchantReference` that names the purpose and date, such as `treasury-2026-11-18`. It
> appears on your statement.
