Create Buy Checkout

Create a checkout intent to execute an on-ramp (fiat to crypto) transaction. Pass the onramp value from a quote response to select which quote to use.

POSThttps://api.zenpayz.com/payment/api/v1/on-ramp/checkout

Bearer · API key

Request

Headers

Header	Description
Content-Type REQUIRED	application/json
x-request-id OPTIONAL	Custom request ID for tracing

Public Endpoint

This endpoint does not require authentication headers.

Body Parameters

Parameter	Type	Description
onramp REQUIRED	string	Identifier from quote response (e.g. moonpay)
source REQUIRED	string	Fiat currency (e.g. usd)
destination REQUIRED	string	Crypto ID (e.g. btc_bitcoin)
amount REQUIRED	number	Fiat amount
type REQUIRED	string	buy
paymentMethod REQUIRED	string	Payment method (e.g. creditcard)
walletAddress OPTIONAL	string	Crypto wallet address for delivery. See Wallet Addresses
walletMemo OPTIONAL	string	Memo/tag for XRP, XLM, etc.
network OPTIONAL	string	Blockchain network (e.g. ethereum)
country OPTIONAL	string	ISO country code
sessionId OPTIONAL	string	Checkout session ID for tracking
walletAddresses OPTIONAL	object	Network-to-address mappings (e.g. { "ethereum": "0x..." })

Wallet Resolution

If walletAddress is not provided but sessionId is, ZenPays automatically resolves the wallet from your merchant settings. See Wallet Addresses for details.

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "redirectUrl": "https://checkout.example.com/...",
    "status": "pending"
  },
  "message": "Checkout intent created"
}

Response Fields

Parameter	Type	Description
transactionId OPTIONAL	string	Unique transaction identifier
redirectUrl OPTIONAL	string	URL to redirect the user to complete payment
status OPTIONAL	string	Initial status (pending)

After receiving the response, redirect the user to redirectUrl to complete payment.

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid request body
RAMP_CHECKOUT_FAILED	500	Failed to create checkout intent

Examples

cURL

curl -X POST https://api.zenpayz.com/payment/api/v1/on-ramp/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "onramp": "moonpay",
    "source": "usd",
    "destination": "btc_bitcoin",
    "amount": 100,
    "type": "buy",
    "paymentMethod": "creditcard",
    "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }'

JavaScript

const response = await fetch('https://api.zenpayz.com/payment/api/v1/on-ramp/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    onramp: 'moonpay',
    source: 'usd',
    destination: 'btc_bitcoin',
    amount: 100,
    type: 'buy',
    paymentMethod: 'creditcard',
    walletAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  }),
});

const { data } = await response.json();

// Redirect user to complete payment
window.location.href = data.redirectUrl;

Python

import requests

response = requests.post(
    "https://api.zenpayz.com/payment/api/v1/on-ramp/checkout",
    json={
        "onramp": "moonpay",
        "source": "usd",
        "destination": "btc_bitcoin",
        "amount": 100,
        "type": "buy",
        "paymentMethod": "creditcard",
        "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    },
)

data = response.json()["data"]
print(f"Transaction: {data['transactionId']}")
print(f"Redirect to: {data['redirectUrl']}")

Full Integration Flow

1. GET  /on-ramp/supported-assets   → Populate currency dropdowns
2. GET  /on-ramp/payment-methods/usd → Get available payment options
3. GET  /on-ramp/quotes?source=usd&destination=btc_bitcoin&amount=100
                                      → Show pricing options to user
4. POST /on-ramp/checkout            → Create checkout with selected quote
5. Redirect to redirectUrl            → User completes payment
6. GET  /on-ramp/transactions/{id}   → Poll until completed or failed

---

Intent-Based Buy Checkout (Recommended)

For merchants using ramp intents, use this endpoint to create a buy checkout tied to an existing intent.

Endpoint

POST /payment/api/v1/on-ramp/buy/checkout

Body Parameters

Parameter	Type	Description
intentId REQUIRED	string	Ramp intent ID
cryptoCurrency REQUIRED	string	Crypto to buy (e.g. USDT)
chain REQUIRED	string	Blockchain network (e.g. tron, ethereum)
fiatCurrency REQUIRED	string	Fiat currency (e.g. USD)
fiatAmount REQUIRED	number	Amount to pay in fiat
cryptoAmount REQUIRED	number	Expected crypto amount to receive
rate REQUIRED	number	Locked exchange rate
totalFee REQUIRED	number	Total fees
quoteId OPTIONAL	string	Quote ID from quotes endpoint

Sample Request

{
  "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
  "cryptoCurrency": "USDT",
  "chain": "tron",
  "fiatCurrency": "USD",
  "fiatAmount": 100,
  "cryptoAmount": 98.5,
  "rate": 1.0,
  "totalFee": 1.5
}

Response (200 OK)

{
  "success": true,
  "data": {
    "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
    "paymentIntentId": "pi_abc123def456",
    "checkoutUrl": "https://checkout.zenpayz.com/pay/pi_abc123def456",
    "fiatAmount": 100,
    "fiatCurrency": "USD",
    "cryptoAmount": 98.5,
    "cryptoCurrency": "USDT",
    "chain": "tron",
    "rate": 1.0,
    "expiresAt": "2026-03-15T10:00:00.000Z"
  },
  "message": "Buy checkout created"
}

Response Fields

Parameter	Type	Description
intentId OPTIONAL	string	Ramp intent ID
paymentIntentId OPTIONAL	string	Payment intent for the fiat charge
checkoutUrl OPTIONAL	string	URL to redirect customer for payment
fiatAmount OPTIONAL	number	Fiat amount to charge
fiatCurrency OPTIONAL	string	Fiat currency
cryptoAmount OPTIONAL	number	Crypto amount customer will receive
cryptoCurrency OPTIONAL	string	Crypto currency
chain OPTIONAL	string	Blockchain network
rate OPTIONAL	number	Exchange rate applied
expiresAt OPTIONAL	string	Checkout expiry (ISO 8601)

Next Steps

• Transaction Status -- Poll transaction progress
• Buy Quotes -- Get quotes before checkout
• Wallet Addresses -- Understand wallet resolution