Wilby DocsGet Sandbox Keys

Quickstart

You charge through your own processor, as you do today. Wilby says yes or no before each money step, then you report what you did. The most common path for platforms.

Fixed PriceMost 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 Report ✓You charge through your own processor, as you do today.AI Agents OnlyYour business inside Claude and ChatGPT under your name.

Choose "We charge with our own processor" when you sign up, or switch your sandbox: POST /v1/sandbox/payments-path {"path": "you_charge"}.

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

An order at $46.70. If your final price can change, `max_amount_cents` is how much may be charged without asking again (here $56.00); for a fixed price, leave it out.

curl -X POST https://dev.usewilby.com/v1/orders \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-1" \
  -H "content-type: application/json" \
  -d '{
       "merchant_external_ref": "test-store",
       "customer": {
         "external_ref": "customer-2"
       },
       "purpose": "Order 1042 (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-you-charge-1', 'content-type': 'application/json' },
  body: JSON.stringify({
    "merchant_external_ref": "test-store",
    "customer": {
      "external_ref": "customer-2"
    },
    "purpose": "Order 1042 (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-you-charge-1', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["merchant_external_ref" =>"test-store","customer" =>["external_ref" =>"customer-2"],"purpose" =>"Order 1042 (estimate)","amount_cents" =>4670,"max_amount_cents" =>5600]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: id 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-you-charge-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-you-charge-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-you-charge-2', 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage: "confirmed".

3. Ask Before You Hold the Card

Before every charge, hold, capture or refund, ask first. A yes is good for 10 minutes and one report.

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

Look for: allowed: true and approval_id (keep it). Keep: APPROVAL_ID.

4. Hold the Card, Then Report It

Hold $46.70 with your processor as you do today, then tell Wilby what happened, with the approval.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/payments \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-4" \
  -H "content-type: application/json" \
  -d '{
       "kind": "authorize",
       "amount_cents": 4670,
       "processor": "stripe",
       "processor_ref": "pi_quickstart_hold",
       "status": "succeeded",
       "approval_id": "$APPROVAL_ID"
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/payments`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-you-charge-4', 'content-type': 'application/json' },
  body: JSON.stringify({
    "kind": "authorize",
    "amount_cents": 4670,
    "processor": "stripe",
    "processor_ref": "pi_quickstart_hold",
    "status": "succeeded",
    "approval_id": approvalId
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.usewilby.com/v1/orders/' . $order . '/payments');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-you-charge-4', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["kind" =>"authorize","amount_cents" =>4670,"processor" =>"stripe","processor_ref" =>"pi_quickstart_hold","status" =>"succeeded","approval_id" =>$approval_id]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: approved: true (it matched a yes).

5. If the Price Changes: Ask for the Extra

Only if your final price can change. $9.25 more is inside the $56.00 the customer allowed, so it's approved at once. Above it, the answer would have an approval_url for the customer.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/incremental-charges \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-5" \
  -H "content-type: application/json" \
  -d '{
       "amount_cents": 925,
       "reason": "price_change",
       "evidence": [
         {
           "type": "receipt",
           "sha256": "9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
           "label": "Updated invoice"
         }
       ]
     }'
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-you-charge-5', 'content-type': 'application/json' },
  body: JSON.stringify({
    "amount_cents": 925,
    "reason": "price_change",
    "evidence": [
      {
        "type": "receipt",
        "sha256": "9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
        "label": "Updated invoice"
      }
    ]
  }),
});
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-you-charge-5', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["amount_cents" =>925,"reason" =>"price_change","evidence" =>[["type" =>"receipt","sha256" =>"9f2c4a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e","label" =>"Updated invoice"]]]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: incremental_charge.status: "approved" and incremental_charge.incremental_charge_id (keep it). Keep: INCREMENTAL_CHARGE_ID.

6. If the Price Changes: Ask, Then Charge the Extra

The $9.25 the customer allowed: ask, charge it with your processor, and report it with the incremental charge's id.

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

Look for: allowed: true. Keep: CHARGE_APPROVAL.

7. If the Price Changes: Report the Incremental Charge

With incremental_charge_id, the incremental charge shows "Approved and Paid" everywhere.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/payments \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-7" \
  -H "content-type: application/json" \
  -d '{
       "kind": "charge",
       "amount_cents": 925,
       "processor": "stripe",
       "processor_ref": "pi_quickstart_extra",
       "status": "succeeded",
       "approval_id": "$CHARGE_APPROVAL",
       "incremental_charge_id": "$INCREMENTAL_CHARGE_ID"
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/payments`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-you-charge-7', 'content-type': 'application/json' },
  body: JSON.stringify({
    "kind": "charge",
    "amount_cents": 925,
    "processor": "stripe",
    "processor_ref": "pi_quickstart_extra",
    "status": "succeeded",
    "approval_id": chargeApproval,
    "incremental_charge_id": incrementalChargeId
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.usewilby.com/v1/orders/' . $order . '/payments');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-you-charge-7', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["kind" =>"charge","amount_cents" =>925,"processor" =>"stripe","processor_ref" =>"pi_quickstart_extra","status" =>"succeeded","approval_id" =>$charge_approval,"incremental_charge_id" =>$incremental_charge_id]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: approved: true.

8. Set the Final Price

Tell Wilby the final price ($55.95; for a fixed price, the same as the order). The record says exactly what to do with your processor (partner_must): here, capture the $46.70 hold.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/capture \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-8" \
  -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-you-charge-8', '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-you-charge-8', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["capture_cents" =>5595]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: stage, and partner_must in the record.

9. Ask, Then Capture the Hold

Ask before capturing, as before every money step.

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

Look for: allowed: true. Keep: CAPTURE_APPROVAL.

10. Report the Capture

Capture with your processor, then report it with the approval. The order is finished.

curl -X POST https://dev.usewilby.com/v1/orders/$ORDER/payments \
  -H "Authorization: Bearer $OH_KEY" \
  -H "Idempotency-Key: quickstart-you-charge-10" \
  -H "content-type: application/json" \
  -d '{
       "kind": "capture",
       "amount_cents": 4670,
       "processor": "stripe",
       "processor_ref": "pi_quickstart_hold",
       "status": "succeeded",
       "approval_id": "$CAPTURE_APPROVAL"
     }'
Node
const r = await fetch(`https://dev.usewilby.com/v1/orders/${order}/payments`, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.OH_KEY}`, 'idempotency-key': 'quickstart-you-charge-10', 'content-type': 'application/json' },
  body: JSON.stringify({
    "kind": "capture",
    "amount_cents": 4670,
    "processor": "stripe",
    "processor_ref": "pi_quickstart_hold",
    "status": "succeeded",
    "approval_id": captureApproval
  }),
});
const answer = await r.json();
PHP
$ch = curl_init('https://dev.usewilby.com/v1/orders/' . $order . '/payments');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('OH_KEY'), 'Idempotency-Key: quickstart-you-charge-10', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(["kind" =>"capture","amount_cents" =>4670,"processor" =>"stripe","processor_ref" =>"pi_quickstart_hold","status" =>"succeeded","approval_id" =>$capture_approval]),
]);
$answer = json_decode(curl_exec($ch), true);

Look for: approved: true.

Next