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.

POSThttps://api.payd.money/api/v2/payments/quote

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

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"
  }'

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

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. Defaults to the key's account.

Response

{
  "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.