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.
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://app.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://app.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://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-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://app.usewilby.com/v1/orders/$ORDER/confirm \
-H "Authorization: Bearer $OH_KEY" \
-H "Idempotency-Key: quickstart-price-changes-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-price-changes-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-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://app.usewilby.com/v1/orders/$ORDER/authorize \
-H "Authorization: Bearer $OH_KEY" \
-H "Idempotency-Key: quickstart-price-changes-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-price-changes-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-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://app.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://app.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://app.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://app.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://app.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://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-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://app.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://app.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://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-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
- Try a decline: use
pm_test_declineas the payment method. Other test cards and banks: Sandbox. - Ask for $20 more instead of $9.25: it's above the customer's $56.00, so the answer has an
approval_urlfor the customer. - Get told about every step: Webhooks. See what's left before going live:
GET /v1/integration/check.