202, and the check can end in a rejection or a hold.
Before you begin
- Send order events to staging and get
202responses. - Keep the
webhook-id, the body, and theidempotencyKeyof every request you send, so you can resend it unchanged. - Agree with your Bilt integration manager how you get rejection reports. A self-serve lookup is planned and not available yet.
How it works
Every event endsACCEPTED, HELD, or REJECTED, and a held or rejected event carries one reason. A held event waits for something that has not arrived yet, and Bilt checks it again by itself. A rejected event is final, so you fix the event and send it as a new request.
Steps
1
Read the reason
Ask your Bilt integration manager for the result, giving the
webhook-id. Look up the reason in the order report reasons table.2
Leave held events alone
Do not resend a
HELD event. Bilt checks it again once the PURCHASE, the card AUTHORIZED, the card CAPTURED, or the customer’s account link arrives.3
Fix a rejected event
Every other reason is yours to fix, except
PARTNER_DISABLED, which Bilt fixes. Change the event, give it a new idempotencyKey, and send it with a new webhook-id.4
Retry a request that did not get a 202
After a timeout or a
500, send the same webhook-id with exactly the same body. Sign it again with the current time. Bilt ignores the copy if it already has the request.5
Resend a request that failed the signature check
Bilt never processed it. Fix the key, the clock, or the signed bytes, and send it again. See Sign your requests.
What can go wrong
- You change the body on a retry. Bilt rejects it with
IDEMPOTENCY_KEY_REUSED. - You resend an accepted
orderIdorreturnIdwith another body. Bilt rejects it withORDER_CONFLICT. - A card capture arrives before its authorization. Bilt holds it with
AUTHORIZATION_NOT_FOUNDuntil the authorization lands. - The customer never links. The event stays held with
CONSUMER_NOT_LINKED.
Next steps
- Errors and retries lists every reason and what to do about it.
- Test and go live has the staging test plan for order reporting.