Quickstart

1. Get your keys#

Sign up and open Developers → API keys. Every account starts with test keys, so you can build before your business is verified.

The key decides the mode: an order created with a test key is a test order, and its events go to your test webhook endpoints. Keep secret keys on your server and out of version control. A key can be limited to one store; such a key can't read your balance or payouts.

2. Create an order#

On your server, when the customer clicks pay:

curl https://velpay.pro/api/v1/orders \
  -H "Authorization: Bearer $VELPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-2041" \
  -d '{
    "amount": 4900,
    "currency": "usd",
    "reference": "A-2041",
    "description": "2 × Coffee beans 1 kg",
    "payer": { "email": "buyer@example.com", "name": "Sam Buyer" },
    "success_url": "https://shop.example/orders/A-2041/thanks",
    "cancel_url": "https://shop.example/cart",
    "metadata": { "cart_id": "c_8812" }
  }'

The same in Node:

const res = await fetch("https://velpay.pro/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VELPAY_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.number}`,
  },
  body: JSON.stringify({
    amount: 4900,            // minor units: $49.00
    currency: "usd",
    reference: order.number, // unique per mode
    payer: { email: order.email },
    success_url: `https://shop.example/orders/${order.number}/thanks`,
    cancel_url: "https://shop.example/cart",
  }),
});
const velpayOrder = await res.json();
if (!res.ok) throw new Error(velpayOrder.error.message);
// Store velpayOrder.id next to your order, then redirect:
return Response.redirect(velpayOrder.pay_link, 303);

• amount is an integer in the currency's smallest unit: cents for USD and EUR, whole yen for JPY.
• reference is your order number. It must be unique per mode; if a customer retries, reuse the open VelPay order or add a suffix.
• Idempotency-Key makes the call safe to retry: the same key and body return the same order for 48 hours.
• Optional: methods to limit what the payer sees, expires_in (900–86400 seconds, default 3600), locale for the checkout language, and crypto to preset a coin.

The response is the order object with state: "awaiting_payment" and a pay_link.

3. Send the payer to the pay link#

Redirect the browser to pay_link. The payer chooses crypto, Cash App or card and pays. Afterwards they come back to your success_url with velpay_order and velpay_status appended. Prefer to keep the payer on your page? Use the embedded checkout.

4. Listen for webhooks#

Open Developers → Webhooks, add an https endpoint and copy the public key shown there. We POST a signed event whenever an order changes. Fulfil on order.paid, never on the redirect alone: the redirect can be faked or skipped, the signed event can't. The webhooks guide has verification code for Node, PHP and Python and shows how to receive events on your laptop through a tunnel.

5. Simulate a payment#

Open the pay_link of your test order. A test banner says no real money moves. Pick a method, then use the Test controls box: Simulate payment pays the order, Simulate half payment (crypto) leaves it underpaid, Simulate expiry ends it unpaid. Your endpoint receives order.paid exactly as it would in live mode, and GET /api/v1/orders/:id now shows state: "paid". See testing for expiry, voids and refunds.

6. Go live#

1. Finish verification in the dashboard. Live mode opens when your business is approved; until then live keys answer 403 account_inactive.
2. Check which payment methods are switched on for live mode under your payment method settings. Test mode offers every method; live mode only the ones granted to your account and switched on.
3. Add your webhook endpoint again in live mode. Endpoints are per mode, so a test endpoint never receives live events.
4. Swap vp_sk_test_… for vp_sk_live_… on your server.
5. Place one small real order with each method you offer and check that it reaches paid in your system.