Wilby DocsGet Sandbox Keys

Quickstart

Most businesses sell at a known price. Wilby takes the payment through your processor account and keeps a signed record of every step. Six requests from a new key to a finished order.

Fixed Price ✓Most businesses sell at a known price.Variable Amount After CheckoutFor services, weighed goods and anything priced after the work: the customer sets how much more may be charged without asking, and approves anything above it..You Charge and ReportYou charge through your own processor, as you do today.AI Agents OnlyYour business inside Claude and ChatGPT under your name.

1. Get sandbox keys (instant). Your sign-up makes a test store called test-store.
2. Save your key: export OH_KEY=oh_test_…
3. Save each value a step says to keep (for example export ORDER=prm_…).

Every request on this page is run by our automated tests on each release, so it works as written. Dashboard → Setup marks each step Done once Wilby has seen it work in your sandbox.

1. Create an Order

A customer buys a table lamp for $42.00. The price is fixed, so the most that may be charged is the price itself. Your sign-up made the store "test-store" for you.

curl -X POST https://app.usewilby.com/v1/orders \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-1" \
  -H "content-type: application/json" \
  -d '{
       "merchant_external_ref": "test-store",
       "customer": {
         "external_ref": "customer-3",
         "payment_method_ref": "pm_test_card"
       },
       "purpose": "Ceramic table lamp",
       "amount_cents": 4200,
       "max_amount_cents": 4200
     }'
Node
const r = await fetch(`https://app.usewilby.com/v1/orders`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-1', 'content-type': 'application/json' },
  body: JSON.stringify({
    "merchant_external_ref": "test-store",
    "customer": {
      "external_ref": "customer-3",
      "payment_method_ref": "pm_test_card"
    },
    "purpose": "Ceramic table lamp",
    "amount_cents": 4200,
    "max_amount_cents": 4200
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-1', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["merchant_external_ref" =>"test-store","customer" =>["external_ref" =>"customer-3","payment_method_ref" =>"pm_test_card"],"purpose" =>"Ceramic table lamp","amount_cents" =>4200,"max_amount_cents" =>4200]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: id (keep it for the next steps) and stage: "created". Keep: ORDER.

2. The Store Confirms It

Nothing is charged before the store says yes.

curl -X POST https://app.usewilby.com/v1/orders/$ORDER/confirm \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-2"
Node
const r = await fetch(`https://app.usewilby.com/v1/orders/${order}/confirm`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-2', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders/' . $order . '/confirm');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-2', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "confirmed".

3. Take the Payment

The $42.00 is held on the customer's card until the order ships.

curl -X POST https://app.usewilby.com/v1/orders/$ORDER/authorize \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-3"
Node
const r = await fetch(`https://app.usewilby.com/v1/orders/${order}/authorize`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-3', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders/' . $order . '/authorize');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-3', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "authorized" and held_cents: 4200.

4. The Order Ships

Takes the $42.00. The price didn't change, so there was nothing to ask.

curl -X POST https://app.usewilby.com/v1/orders/$ORDER/capture \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-4" \
  -H "content-type: application/json" \
  -d '{
       "capture_cents": 4200
     }'
Node
const r = await fetch(`https://app.usewilby.com/v1/orders/${order}/capture`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-4', 'content-type': 'application/json' },
  body: JSON.stringify({
    "capture_cents": 4200
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders/' . $order . '/capture');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-4', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["capture_cents" =>4200]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "captured" and capture_cents: 4200.

5. A Partial Refund

The lamp arrived with a scratch; you refund $10.00. Refunds go in the same signed record.

curl -X POST https://app.usewilby.com/v1/orders/$ORDER/refunds \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-5" \
  -H "content-type: application/json" \
  -d '{
       "amount_cents": 1000,
       "reason": "Arrived scratched"
     }'
Node
const r = await fetch(`https://app.usewilby.com/v1/orders/${order}/refunds`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-5', 'content-type': 'application/json' },
  body: JSON.stringify({
    "amount_cents": 1000,
    "reason": "Arrived scratched"
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders/' . $order . '/refunds');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-5', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["amount_cents" =>1000,"reason" =>"Arrived scratched"]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: the refund with its status.

6. Check the Signed Record

Every step above was signed and chained. Open `verify_url` in a browser: anyone can check it, with no account. In a dispute, this is your proof.

curl -X POST https://app.usewilby.com/v1/orders/$ORDER/receipt-link \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-fixed-price-6"
Node
const r = await fetch(`https://app.usewilby.com/v1/orders/${order}/receipt-link`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-fixed-price-6', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://app.usewilby.com/v1/orders/' . $order . '/receipt-link');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-fixed-price-6', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: verify_url, a page that shows every step and checks every signature.

Next