Pay by onramp

Pay by onramp is a payment link with "kind": "onramp". Your backend creates it and shares checkout_url. On the pay page the customer verifies their identity once, then pays by card or bank in a secure onramp window embedded in the page. The payment is converted to a stablecoin (for example USDC) and delivered to ParuPay’s wallet. ParuPay takes its fees from the payment, and you are owed the net amount.

The customer never chooses a wallet, network or coin — they are locked by ParuPay.
The customer pays the onramp’s own processing and network fees on top of your amount; those fees are shown to them before they pay.
One successful payment closes the link, like any payment link.

Sandbox (sk_test_) works for every account straight away. Live (sk_live_) onramp payments must be enabled for your account by ParuPay — ask support@parupay.com. You can check what is enabled with GET /v1/onramp/status.

Who can pay


Currencies	`usd` or `eur` only. Other currencies are refused when the link is created.
Customers	Customers in the United States and the EU. Some US states are not supported (for example New York and Hawaii); the onramp tells the customer if they cannot continue.
Methods	Card or bank account, inside the onramp window.

Create

POST /v1/payment_links with Authorization: Bearer sk_… and "kind": "onramp".

{
  "kind": "onramp",
  "amount": 5000,
  "currency": "usd",
  "title": "Order 1042",
  "description": "Annual plan",
  "customer_name": "Northline Buyer",
  "customer_email": "buyer@example.com",
  "metadata": {
    "order_id": "1042",
    "return_url": "https://shop.example/orders/1042",
    "cancel_url": "https://shop.example/cart"
  }
}

Field	Required	Notes
`kind`	Yes	`"onramp"`. Without it (or `"link"`) you get a normal payment link.
`amount`	Yes	Minor units, greater than 0. 5000 is 50.00 USD.
`currency`	Yes	`usd` or `eur`.
`title`	Yes	Shown on the pay page.
`description`	No	Shown under the title.
`customer_email`	No	Prefills the onramp sign-in so the customer does not type it again.
`customer_name`, `customer_phone`	No	Stored on the link.
`metadata`	No	String key/value pairs, same limits as payment links. Put your `order_id` here.
`metadata.return_url` / `metadata.cancel_url`	No	Where the pay page sends the customer after paying or cancelling.

Response

The same as a payment link:

{
  "id": "plink_…",
  "url_slug": "…",
  "checkout_url": "https://pay.parupay.com/…"
}

Errors

Status	When
`400`	`currency` is not `usd` or `eur`.
`403`	Pay by onramp is not enabled for your account, or not yet for live mode. The message says which.

What the customer sees

The pay page opens with your logo, title and amount, and the onramp window loads inside it.
First time only: the customer signs in with a one-time code and verifies their identity.
The customer reviews the quote (amount, onramp fees, total) and pays by card or bank.
The page shows Payment received — finishing up… while the crypto is delivered, then the success screen. If you set return_url, the customer is sent back to you.

Delivery is usually quick but can take a few minutes. The customer may close the page once they have paid — ParuPay still records the payment and sends your webhook.

Statuses

Payment status	Meaning	What to do
`requires_action`	The onramp window is open; the customer has not paid yet.	Wait.
`processing`	The customer paid; the crypto is being delivered.	Wait — do not ship yet.
`succeeded`	Delivered. A charge (`ch_…`) is attached with ParuPay’s fee and your net amount.	Mark the order paid.
`requires_payment_method` + `last_payment_error`	The onramp declined the customer (identity or fraud checks).	Treat as failed. The customer can try again from the same link.
`canceled`	The customer pressed Cancel before paying.	Treat as cancelled.

Webhooks are the same as for any payment: payment_intent.succeeded when it completes and payment_intent.payment_failed when it is declined. See Webhooks and Payment statuses. On the charge, onramp payments have payment_method_type: "crypto_onramp" and card_brand set to the coin (for example "usdc"). The charge metadata includes onramp_transaction_id (the blockchain transaction), onramp_destination_amount, onramp_destination_currency and onramp_destination_network.

Fees and settlement

ParuPay’s fee (your MDR % plus the fixed fee, and the conversion fee when the currency differs from your settlement currency) is taken from the payment amount, exactly as for card payments. The charge shows platform_fee and net_amount.
The onramp’s own fees are paid by the customer on top of your amount — they do not reduce what you receive.
Your net amount is added to your balance in the merchant portal and settled to you by ParuPay under your settlement terms.

Onramp payments cannot be refunded through the API — the crypto has already been delivered. POST /v1/charges/:id/refunds returns an error for them. Contact support@parupay.com if a customer needs money back.

Check availability

GET /v1/onramp/status with your secret key tells you whether you can create onramp links in the key’s mode.

{
  "enabled": true,
  "configured": true,
  "option_enabled": true,
  "live_approved": false,
  "destination_currency": "usdc",
  "destination_network": "ethereum",
  "source_currencies": ["usd", "eur"]
}

Field	Meaning
`enabled`	You can create onramp links in this mode right now.
`option_enabled`	Pay by onramp is switched on for your account.
`live_approved`	ParuPay has approved live onramp payments for your account.
`destination_currency`, `destination_network`	The coin and network payments are delivered in.
`source_currencies`	Currencies you can create onramp links in.

Read

Request	What it does
`GET /v1/payment_links?kind=onramp`	Your onramp links, newest first, with views, payments and volume.
`GET /v1/payment_links/:id`	One link (`"kind": "onramp"`).
`GET /v1/payments?channel=onramp`	Onramp payments only, with status and charge.

Testing

Use sk_test_ and a small amount such as 10.00 — the sandbox has its own amount limits and larger test payments may not go through. In the onramp window use these test values:

Screen	Enter
One-time code	`000000`
SSN	`000000000`
Address line 1	`address_full_match` (any US city, state and ZIP outside New York and Hawaii)
Card	`4242 4242 4242 4242`, any future expiry, any 3-digit CVC

Use a new email address for each test customer. Sandbox payments deliver no real crypto.

Start

Accept payments

Developers

Who can pay

Create

Response

Errors

What the customer sees

Statuses

Fees and settlement

Check availability

Read

Testing