Wilby DocsGet Sandbox Keys

Quickstart

For 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.

Fixed PriceMost businesses sell at a known price.Variable Amount After Checkout ✓For 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.

Tell Wilby your final price can change: POST /v1/settings {"variable_amount": true}, or choose it when you sign up.

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

The customer books a repair estimated at $46.70 and agrees that up to $56.00 may be charged without asking again. Your sign-up made the store "test-store" for you.

curl -X POST https://dev.usewilby.com/v1/orders \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-1" \
  -H "content-type: application/json" \
  -d '{
       "merchant_external_ref": "test-store",
       "customer": {
         "external_ref": "customer-1",
         "payment_method_ref": "pm_test_card"
       },
       "purpose": "Faucet repair (estimate)",
       "amount_cents": 4670,
       "max_amount_cents": 5600
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-1', 'content-type': 'application/json' },
  body: JSON.stringify({
    "merchant_external_ref": "test-store",
    "customer": {
      "external_ref": "customer-1",
      "payment_method_ref": "pm_test_card"
    },
    "purpose": "Faucet repair (estimate)",
    "amount_cents": 4670,
    "max_amount_cents": 5600
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.usewilby.com/v1/orders');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-price-changes-1', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["merchant_external_ref" =>"test-store","customer" =>["external_ref" =>"customer-1","payment_method_ref" =>"pm_test_card"],"purpose" =>"Faucet repair (estimate)","amount_cents" =>4670,"max_amount_cents" =>5600]),
]);
$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://dev.usewilby.com/v1/orders/$ORDER/confirm \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-2"
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/confirm`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-2', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.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-price-changes-2', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "confirmed".

3. Take the Payment

A hold for the estimate on the customer's card. The hold is kept active until the job is done.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/authorize \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-3"
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/authorize`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-3', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.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-price-changes-3', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "authorized", funding_method: "hold", held_cents: 4670.

4. The Final Price Is Higher

A part had to be replaced: $9.25 more, so the real price is $55.95. That is inside the $56.00 the customer allowed, so it goes through at once, with the parts receipt kept as evidence. Above $56.00, the customer would get a link and decide.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/incremental-charges \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-4" \
  -H "content-type: application/json" \
  -d '{
       "amount_cents": 925,
       "reason": "extra_parts",
       "evidence": [
         {
           "type": "receipt",
           "sha256": "9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
           "label": "Parts receipt"
         }
       ]
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/incremental-charges`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-4', 'content-type': 'application/json' },
  body: JSON.stringify({
    "amount_cents": 925,
    "reason": "extra_parts",
    "evidence": [
      {
        "type": "receipt",
        "sha256": "9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
        "label": "Parts receipt"
      }
    ]
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.usewilby.com/v1/orders/' . $order . '/incremental-charges');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-price-changes-4', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["amount_cents" =>925,"reason" =>"extra_parts","evidence" =>[["type" =>"receipt","sha256" =>"9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e","label" =>"Parts receipt"]]]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: the incremental charge was approved inside the customer's limit (no approval link needed).

5. Set the Final Price

Takes $55.95 in total and releases anything left on the hold.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/capture \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-5" \
  -H "content-type: application/json" \
  -d '{
       "capture_cents": 5595
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/capture`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-5', 'content-type': 'application/json' },
  body: JSON.stringify({
    "capture_cents": 5595
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.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-price-changes-5', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["capture_cents" =>5595]),
]);
$answer = json_decode(curl_exec($ch), true);

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

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.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/receipt-link \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-price-changes-6"
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/receipt-link`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-price-changes-6', 'content-type': 'application/json' },
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.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-price-changes-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