# Quotes and fees

Ask Payd what a payment will cost before you send it. A quote shows the fee, the exchange rate, and what moves on your balance.

<div class="endpoint"><span class="method post">POST</span><code>https://api.payd.money/api/v2/payments/quote</code></div>

A quote does not move money and does not hold a rate. Ask for a fresh one just before you pay out.

::: code-group

```bash [cURL]
curl https://api.payd.money/api/v2/payments/quote \
  -u "$PAYD_API_USERNAME:$PAYD_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "withdrawal",
    "amount": 2500,
    "currency": "KES",
    "country_code": "KE",
    "dial_code": "+254",
    "transaction_channel": "mobile"
  }'
```

```js [Node.js]
const auth = Buffer.from(
  `${process.env.PAYD_API_USERNAME}:${process.env.PAYD_API_PASSWORD}`,
).toString('base64')

const quote = await fetch('https://api.payd.money/api/v2/payments/quote', {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    operation_type: 'withdrawal',
    amount: 2500,
    currency: 'KES',
    country_code: 'KE',
    dial_code: '+254',
    transaction_channel: 'mobile',
  }),
}).then((r) => r.json())

console.log(`Fee ${quote.fee_local} ${quote.local_currency}, ${quote.total_charge_usd} USD from your balance`)
```

```python [Python]
import os
import requests

quote = requests.post(
    "https://api.payd.money/api/v2/payments/quote",
    auth=(os.environ["PAYD_API_USERNAME"], os.environ["PAYD_API_PASSWORD"]),
    json={
        "operation_type": "withdrawal",
        "amount": 2500,
        "currency": "KES",
        "country_code": "KE",
        "dial_code": "+254",
        "transaction_channel": "mobile",
    },
    timeout=15,
).json()
print(f"Fee {quote['fee_local']} {quote['local_currency']}, {quote['total_charge_usd']} USD from your balance")
```

:::

## Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operation_type` | string | No | `receipt` for a collection, `withdrawal` for a payout. Defaults to `withdrawal`. |
| `amount` | number | Yes | The payment amount in `currency`. Must be more than zero. |
| `currency` | string | Yes | The payment currency, such as `KES` or `UGX`. |
| `country_code` | string | Yes | The two-letter country code of the payment. |
| `dial_code` | string | Yes | The country's dialling code with a `+`, such as `+254` or `+256`. |
| `transaction_channel` | string | Yes | `mobile`, `bank` or `card`, as in the payment you plan to send. |
| `account_id` | string | No | Your [account id](./authentication.md#find-your-account-id). Defaults to the key's account. |

## Response

```json
{
  "operation_type": "withdrawal",
  "amount_local": 2500,
  "local_currency": "KES",
  "fee_local": 37.5,
  "total_charge_local": 2537.5,
  "amount_usd": 19.37,
  "fee_usd": 0.29,
  "total_charge_usd": 19.66,
  "settlement_usd": 19.66,
  "settlement_currency": "USD",
  "rate": 129.1,
  "live_rate": true,
  "provider_fee_usd": 0,
  "provider_fee_estimated": false
}
```

| Field | Meaning |
| --- | --- |
| `amount_local`, `local_currency` | The amount you asked about. |
| `fee_local` | Payd's fee in the local currency. |
| `total_charge_local` | Amount plus fee in the local currency. |
| `amount_usd`, `fee_usd`, `total_charge_usd` | The same figures in US dollars. |
| `rate` | Units of local currency per US dollar. |
| `live_rate` | `true` when the rate is current. |
| `settlement_usd` | What moves on your balance, in US dollars. For a payout, the amount taken. For a collection, the amount added. |
| `provider_fee_usd` | For collections, an estimate of what the mobile money network keeps. `0` for payouts. |
| `provider_fee_estimated` | `true` when `provider_fee_usd` is an estimate. A collection can land a little under the quote. |

Ignore any other field in the response.

## How fees work

- Payd charges its fee in US dollars, on your balance.
- For a payout, your balance must cover `total_charge_usd`. If it does not, the payout fails with `insufficient_balance`.
- For a collection, the fee comes out of what you receive. The customer pays the amount you asked for.

## Errors

| `error_code` | Message | Fix |
| --- | --- | --- |
| `invalid_argument` | `a quote needs an amount greater than zero` | Send a positive `amount`. |
| `invalid_argument` | `a quote needs a currency` | Send `currency`. |
| `invalid_argument` | `account not found` | Check `account_id`. |
| `permission_denied` | `you do not have access to this account` | Use your key's account id. |
| `resource_not_found` | `no pricing configured...` | Payd does not offer this country, currency and channel together. Check `dial_code` and `transaction_channel`. |