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