Ramp - Payward Developer Documentation

The Payward Ramp API lets you embed a fiat-to-crypto on-ramp into your application. Instead of building payment processing, KYC, and crypto delivery yourself, you call Ramp endpoints to discover what’s available, preview pricing, and then generate a hosted checkout URL that handles the rest. Your user pays in fiat; Payward delivers crypto to the destination wallet.

Not what you’re looking for? Ramp is designed for end-user fiat-to-crypto purchases via a hosted checkout flow. If you need to move funds between PWS accounts (Transfers), convert assets programmatically without a checkout UI (Conversions), or execute institutional FX-style trades (Swap), see the PWS API reference.

How it works

A typical Ramp integration follows four steps:

Discover

Query supported countries, fiat currencies, payment methods, and cryptocurrency assets to know what options are valid for your user’s location.

Preview

Call the prospective quote endpoint to show the user an estimated spend/receive breakdown before they commit.

Check limits

Optionally verify that the user’s intended amount falls within min/max bounds.

Checkout

Generate a hosted checkout URL and redirect the user to it. Payward handles payment processing and crypto delivery.

Base URL

https://api.services.payward.com

Authentication

All requests require two headers:

Header	Description
`API-Key`	Your public API key
`API-Sign`	HMAC signature computed with your private key

See Authentication for how to generate the signature.

Step 1 — Discover supported options

Before building your UI, query the discovery endpoints to understand what’s valid for your user’s country. All four endpoints are read-only and can be called at startup or cached.

List supported countries

GET /v1/ramp/countries

Returns countries where Ramp is available. Countries that require regional filtering include a subdivisions array. Use the returned country value and any relevant subdivision value as inputs to all other Ramp endpoints.

List fiat currencies

GET /v1/ramp/fiat-currencies

Returns fiat currencies supported for funding Ramp transactions (e.g., USD, EUR). Pass the returned codes as in_asset_symbol in later calls.

List payment methods

GET /v1/ramp/payment-methods

Returns available payment methods (e.g., credit_card). Pass the returned identifiers as in_method.

List cryptocurrency assets

GET /v1/ramp/buy/crypto

Returns cryptocurrency assets available for purchase, along with their supported networks and withdrawal methods. Both out_asset_symbol and out_method values for later calls come from here. All four discovery endpoints are cursor-paginated. Use page_size to set the first page size (default 50, maximum 200). If a response includes next_page_token, pass that value as page_token to fetch the next page. Page tokens are scoped to the original endpoint and country/subdivision where applicable, and the token’s page size wins over a new page_size value. Query parameters:

Parameter	Required	Description
`country`	Yes	Required for fiat currencies, payment methods, and cryptocurrency assets
`subdivision`	No	ISO 3166-2 suffix from the countries response
`page_size`	No	First-page size, from 1 to 200. Defaults to 50
`page_token`	No	Opaque token from `next_page_token` for the next page of the same result set

curl -X GET "https://api.services.payward.com/v1/ramp/buy/crypto?country=US&subdivision=CA&page_size=200" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Sign: $PWS_API_SIGN"

Step 2 — Preview pricing

Before sending your user to checkout, call the prospective quote endpoint to display an estimated cost breakdown. This call does not reserve liquidity — it’s safe to call on every keystroke for a live price preview.

GET /v1/ramp/quotes/prospective

Required parameters:

Parameter	Description
`in_asset_symbol`	Fiat currency ticker (e.g., `USD`)
`in_method`	Payment method (e.g., `credit_card`)
`in_amount`	Amount the user intends to spend
`out_asset_symbol`	Cryptocurrency asset ticker to receive (e.g., `BTC`)
`out_method`	Withdrawal method (e.g., `Bitcoin`)
`country`	User’s country code

Optional parameters:

Parameter	Description
`in_asset_type`	Asset classification (`fiat`, `crypto`, `stablecoin`, `xstock`)
`out_asset_type`	Asset classification for the destination side
`subdivision`	US state / CA province code
`affiliate_fee_bps`	Your affiliate fee in basis points (e.g., `250` = 2.5%)

The response includes a spend object (fiat side) and a receive object (crypto side), each with a full fee breakdown. Asset references use the money-like { symbol, type } shape:

{
  "data": {
    "spend": {
      "asset": { "symbol": "USD", "type": "fiat" },
      "total": "1015.00",
      "subtotal": "1000.00",
      "fee": "10.00",
      "deposit_fee": "5.00",
      "affiliate_fee": "2.50",
      "withdrawal_fee": null
    },
    "receive": {
      "asset": { "symbol": "BTC", "type": "crypto" },
      "total": "0.01587302",
      "subtotal": "0.01587302",
      "fee": null,
      "deposit_fee": null,
      "affiliate_fee": null,
      "withdrawal_fee": "0.00010000"
    },
    "unit_price": {
      "asset": { "symbol": "BTC", "type": "crypto" },
      "denomination_asset": { "symbol": "USD", "type": "fiat" },
      "unit_price": "63000.00"
    }
  }
}

Affiliate fee note: affiliate_fee_bps increases the fee charged to the user. In responses, affiliate_fee represents your portion of the returned fee amount, so do not add it again in your UI.

Step 3 — Check transaction limits (optional)

GET /v1/ramp/limits

Returns the minimum and maximum transaction amounts for a given configuration. Call this to validate user input before generating a checkout URL or to display limit guidance in your UI. Uses the same required parameters as the prospective quote endpoint.

Step 4 — Generate a checkout URL

Once you have confirmed options and the user is ready to proceed, generate a hosted checkout URL. Redirect your user to this URL — Payward handles the payment form, KYC checks, and crypto delivery.

GET /v1/ramp/checkout

Required parameters:

Parameter	Description
`in_asset_symbol`	Fiat currency ticker (e.g., `USD`)
`in_method`	Payment method
`in_amount`	Amount to charge
`out_asset_symbol`	Cryptocurrency asset ticker to deliver
`out_method`	Withdrawal method
`country`	User’s country code

Useful optional parameters:

Parameter	Description
`in_asset_type`	Asset classification for the funding side
`out_asset_type`	Asset classification for the destination side
`wallet_address`	Pre-fill the destination wallet address
`network`	Specify the withdrawal network
`memo`	Memo/tag for assets that require it (e.g., XRP)
`redirect_url`	Where to send the user after a successful purchase
`failure_url`	Where to send the user after a failed purchase
`affiliate_fee_bps`	Your affiliate fee in basis points
`external_user_id`	Your internal user ID (stored for reconciliation)
`external_partner_id`	Your partner identifier for multi-tenant reconciliation
`external_transaction_id`	Your internal transaction ID
`external_metadata`	Arbitrary metadata (max 1000 chars)

The response contains the checkout URL and an echo of the submitted parameters for client-side confirmation. The echoed asset fields use the money-like { symbol, type } shape:

{
  "data": {
    "checkout_url": "https://ramp.example.com/checkout/abc123def456",
    "request_data": {
      "in_asset": { "symbol": "USD", "type": "fiat" },
      "in_method": "credit_card",
      "in_amount": "1000.00",
      "out_asset": { "symbol": "BTC", "type": "crypto" },
      "out_method": "Bitcoin",
      "network": "Bitcoin",
      "wallet_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "memo": null,
      "affiliate_fee_bps": "250",
      "country": "GB",
      "subdivision": null,
      "redirect_url": "https://example.com/checkout/success",
      "failure_url": "https://example.com/checkout/failure",
      "external_user_id": "user_01J0M7C0Z9F8YX3GQH8E",
      "external_partner_id": null,
      "external_transaction_id": "INV-2026-04-0042",
      "external_metadata": "{\"order_id\":\"order_12345\"}"
    }
  }
}

Redirect the user to checkout_url. The hosted page collects card details, performs any required identity verification, and delivers the crypto.

Receiving transaction updates

Payward pushes real-time transaction status updates to a webhook endpoint you implement. Register your endpoint via the Webhooks API, then handle POST callbacks at your URL. Each callback payload includes the transaction status and, when complete, the delivered amount and destination address. The external_transaction_id and external_user_id you passed at checkout are echoed back, making reconciliation straightforward. See the Transaction Update webhook reference for the full payload schema.

API reference

Endpoint	Description
`GET /v1/ramp/countries`	List supported countries and subdivisions
`GET /v1/ramp/fiat-currencies`	List supported fiat currencies
`GET /v1/ramp/payment-methods`	List supported payment methods
`GET /v1/ramp/buy/crypto`	List cryptocurrency assets available for purchase
`GET /v1/ramp/limits`	Get min/max transaction limits
`GET /v1/ramp/quotes/prospective`	Preview spend/receive amounts without reserving liquidity
`GET /v1/ramp/checkout`	Generate a hosted checkout URL
`POST {your_webhook_url}`	Receive real-time transaction status updates

​How it works

​Base URL

​Authentication

​Step 1 — Discover supported options

​List supported countries

​List fiat currencies

​List payment methods

​List cryptocurrency assets

​Step 2 — Preview pricing

​Step 3 — Check transaction limits (optional)

​Step 4 — Generate a checkout URL

​Receiving transaction updates

​API reference

How it works

Base URL

Authentication

Step 1 — Discover supported options

List supported countries

List fiat currencies

List payment methods

List cryptocurrency assets

Step 2 — Preview pricing

Step 3 — Check transaction limits (optional)

Step 4 — Generate a checkout URL

Receiving transaction updates

API reference