Create Quote

Overview

Generate a price quote for a payment before creating a checkout. This endpoint provides real-time exchange rates, payment method details, and the exact amount your customer will pay. Use quotes to:

Show accurate pricing to customers before they commit
Display exchange rates and fees transparently
Build custom checkout flows with upfront pricing
Lock in rates for a short period (quotes are valid for 30 seconds)

When to use: When you want to show customers the exact amount they’ll pay in their chosen currency before starting the checkout process.

Authentication

Type: API Key (required)

Required Headers

Header	Required	Description
`Authorization`	Yes	Format: `Bearer sk_sandbox_...` or `Bearer sk_live_...`
`Content-Type`	Yes	Must be `application/json`

Request

Method & Path

POST /v1/quotes

Request Body

{
  "pricing": {
    "base_currency": "USD",
    "amount": "50.00"
  },
  "payment_method": "bank_transfer",
  "to_currency": "NGN"
}

Request Fields

View request fields

object

required

Pricing configuration (same format as checkout)

string

required

Your base currency (e.g., USD)

string

required

Amount in base currency

object

Required: NoCurrency overrides (only when base is USD)

string

required

Payment method ID (e.g., bank_transfer, mobile_money)

string

required

Currency customer wants to pay in

string

Required: NoSpecific payment rail identifier

string

Required: NoCustomer email (for context)

string

Required: NoCustomer name (for context)

Dependencies & Prerequisites

Before using this endpoint:

Get payment methods

See Payment method support for the valid payment_method IDs.

Get supported currencies

Use List Supported Currencies to validate currency codes.

Optionally resolve rails

Use GET /v1/payment-methods/rails?payment_method=X&currency=Y to fetch valid payment_rail options.

Example Use Case

Scenario: Your e-commerce platform needs to display accurate pricing to customers before checkout. A customer in Nigeria wants to purchase a $50 USD product and prefers to pay via bank transfer in NGN. You need to show them the exact amount they’ll pay in their local currency, including all fees, before they commit to the purchase. Implementation:

// Step 1: Customer selects "Bank Transfer" and "NGN"
const quoteResponse = await fetch(
  "https://api.bachs.io/v1/quotes",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_abc123xyz...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pricing: {
        base_currency: "USD",
        amount: "50.00",
      },
      payment_method: "bank_transfer",
      to_currency: "NGN",
      customer_email: "customer@example.com",
    }),
  },
);

const quote = await quoteResponse.json();

// Step 2: Display quote to customer
console.log(`
  Amount to pay: ₦${quote.amount_local_base} NGN
  Exchange rate: 1 USD = ${quote.exchange_rate} NGN
  Expires in: ${Math.floor((new Date(quote.expires_at) - new Date()) / 1000)} seconds
`);

// Step 3: Customer confirms; use the quote to show pricing, then create a checkout session

Response

200 Success

Returns a detailed quote with pricing, exchange rates, and payment details.

{
  "quote_id": "quote_1a2b3c4d5e6f",
  "payment_method": "bank_transfer",
  "payment_rail": "rail_123",
  "currency": "NGN",
  "base_amount_usd": "50.00",
  "amount_local_base": "75000.00",
  "processing_fee": "750.00",
  "total_amount": "75750.00",
  "exchange_rate": "1500.00",
  "payment_type": null,
  "expires_at": "2026-01-24T14:40:00.000Z",
  "customer_bears_fee": true
}

Response Fields

View response fields

string

Unique identifier for this quote (valid for 30 seconds)

string

Payment method used

string

Payment rail identifier used

string

Currency customer will pay in

string

Base amount in USD before conversion and fees

string

Amount in the customer’s local currency (what they pay)

string

Processing fee amount in the payment currency

string

Total amount customer pays (base + fee)

string

Exchange rate applied (1 USD = X local currency)

string|null

Which direction the quote prices, for example deposit for money coming in.

string

ISO 8601 timestamp when quote expires

boolean

Whether the customer pays the processing fee on top of the base amount

Error Responses

400 Bad Request

Invalid request parameters or unsupported combination.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported payment method for currency",
    "details": {
      "payment_method": "mobile_money is not supported for USD"
    }
  }
}

Common causes:

Invalid payment_method (not in supported list)
Invalid currency combination (payment method doesn’t support that currency)
Invalid amount format (must be string, not number)
Missing required fields

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Using Quotes in Checkout Flows

Option 1: Display Quote, Then Create Checkout

// 1. Get quote
const quote = await getQuote({ ... });

// 2. Show quote to customer
showQuoteModal({
  amount: quote.amount_local_base,
  currency: quote.currency,
  exchangeRate: quote.exchange_rate
});

// 3. Customer confirms, create checkout
const checkout = await createCheckout({ ... });

// 4. Redirect to checkout
window.location.href = checkout.checkout_url;

Option 2: Build a custom-UI checkout

For full control over the UI, use a custom-UI checkout session. You do not pass a quote to it: the price is locked when you set the method and currency on the session.

// 1. Create a custom-UI session
const session = await fetch('https://api.bachs.io/v1/checkout-sessions', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({ ui_mode: 'custom', /* amount, currency, ... */ }),
});
const { checkout_id } = await session.json();

// 2. Set the method + currency; Bachs prices and locks it
await fetch(`https://api.bachs.io/v1/checkout-sessions/${checkout_id}`, {
  method: 'PATCH',
  headers: { ... },
  body: JSON.stringify({ payment_method: 'bank_transfer', currency: 'NGN' }),
});

// 3. Confirm, then read payment_status (or subscribe to webhooks)

The standalone quote endpoint below still exists for previewing a price, but the removed POST /v1/payments/whitelabel one-shot endpoint does not — a custom-UI checkout locks its own price on PATCH.

Quote expirationQuotes are valid for 30 seconds from creation. After expiration:

The quote_id becomes invalid
Exchange rates may have changed
You must generate a new quote

Why? Exchange rates and fees can change rapidly. Short expiration ensures customers see accurate, up-to-date pricing.Exchange ratesExchange rates are fetched from multiple sources and updated frequently. The rate in a quote is:

Locked for the quote’s lifetime (30 seconds)
Inclusive of all fees and margins
Final - the amount shown is what the customer pays

FeesFees are transparently shown in the quote:

Platform fee: Bachs’s fee for processing
Processing fee: the fee charged for handling the payment
Total fee: Sum of all fees

Fees are already included in the amount field. The customer pays only the amount, not amount + fees.Payment railsIf you don’t specify a payment_rail, Bachs automatically selects the best available option based on:

Currency and payment method combination
Availability and reliability
Cost optimization
Success rates

To see available rails for a payment method plus currency:

curl "https://api.bachs.io/v1/payment-methods/rails?payment_method=bank_transfer&currency=NGN" \
  -H "Authorization: Bearer sk_sandbox_..."

Quote vs Direct Checkout

When to Use Quotes

Use quotes when:

You need to display accurate pricing before checkout
Building a custom, multi-step checkout flow
Displaying exchange rates transparently to customers
Customers choose currency/method before committing
Using whitelabel checkout

When to Skip Quotes

Skip quotes when:

Using standard hosted checkout (it handles quotes internally)
One-click payment flows
Customers don’t need to see rates upfront
Simplicity is priority

Testing

Sandbox Quotes

In the sandbox deployment (sk_sandbox_...):

Quotes use simulated exchange rates
Fees are calculated but not charged
All payment methods and currencies are available
Quotes still expire after 30 seconds

Testing Different Rates

To test different exchange rate scenarios:

Create quotes at different times

Generate multiple quotes across short intervals.

Compare returned rates

Rates may vary slightly to simulate real conditions.

Validate expiration behavior

Wait up to 10 minutes and confirm old quotes are rejected.

Common Questions

Can I extend quote expiration?

No, quotes always expire after 30 seconds. This ensures pricing accuracy. If a customer needs more time, generate a new quote.

Do quotes cost anything?

No, generating quotes is free. You’re only charged when a payment is completed.

Can I get a quote without a customer email?

Yes, customer_email and customer_name are optional. They’re only used for context and future features.

What happens if exchange rates change during checkout?

If using a quote in a whitelabel checkout, the rate is locked for the quote’s lifetime (30 seconds). If the quote expires, the payment will fail and you’ll need a new quote.

Can I quote multiple currencies at once?

No, each quote is for a single payment method + currency combination. To show multiple options, make multiple quote requests.

Create Checkout - Standard hosted checkout
Create Whitelabel Checkout - Use quotes for custom checkout
Payment method support - The valid payment method IDs
List Supported Currencies - Get valid currency codes

Next Steps

After getting a quote:

Display pricing

Show the returned amount, currency, and expiry to your customer.

Create a hosted checkout

Use Create Checkout for hosted flow.

Or build a custom flow

Use Whitelabel Checkout.

Monitor payment

Track status with Get Charge Status.

Get Started

Products & pricing

Subscriptions

Customer portal

Payments

Payouts

Dashboard

Developer Portal

CLI

For You and Your Customers

Create Quote

Overview

Authentication

Required Headers

Request

Method & Path

Request Body

Request Fields

Dependencies & Prerequisites

Example Use Case

Response

200 Success

Response Fields

Error Responses

Using Quotes in Checkout Flows

Option 1: Display Quote, Then Create Checkout

Option 2: Build a custom-UI checkout

Quote vs Direct Checkout

When to Use Quotes

When to Skip Quotes

Testing

Sandbox Quotes

Testing Different Rates

Common Questions

Can I extend quote expiration?

Do quotes cost anything?

Can I get a quote without a customer email?

What happens if exchange rates change during checkout?

Can I quote multiple currencies at once?

Next Steps

​Overview

​Authentication

​Required Headers

​Request

​Method & Path

​Request Body

​Request Fields

​Dependencies & Prerequisites

​Example Use Case

​Response

​200 Success

​Response Fields

​Error Responses

​Using Quotes in Checkout Flows

​Option 1: Display Quote, Then Create Checkout

​Option 2: Build a custom-UI checkout

​Quote vs Direct Checkout

​When to Use Quotes

​When to Skip Quotes

​Testing

​Sandbox Quotes

​Testing Different Rates

​Common Questions

​Can I extend quote expiration?

​Do quotes cost anything?

​Can I get a quote without a customer email?

​What happens if exchange rates change during checkout?

​Can I quote multiple currencies at once?

​Related Endpoints

​Next Steps

Overview

Authentication

Required Headers

Request

Method & Path

Request Body

Request Fields

Dependencies & Prerequisites

Example Use Case

Response

200 Success

Response Fields

Error Responses

Using Quotes in Checkout Flows

Option 1: Display Quote, Then Create Checkout

Option 2: Build a custom-UI checkout

Quote vs Direct Checkout

When to Use Quotes

When to Skip Quotes

Testing

Sandbox Quotes

Testing Different Rates

Common Questions

Can I extend quote expiration?

Do quotes cost anything?

Can I get a quote without a customer email?

What happens if exchange rates change during checkout?

Can I quote multiple currencies at once?

Related Endpoints

Next Steps