Event Types

What ShotPay sends, and what rides in data.object when it does. The envelope around it is described under Webhooks, and what to do with session.completed under How your store finds out.

Event	Sent when	data.object
session.completed	A customer confirmed a plan and the down payment was collected.	Session
session.cancelled	A customer walked away from the checkout. Arrives as they leave, not at the deadline.	Session
session.expired	A session lapsed before anyone acted on it.	Session
contract.activated	The agreement was opened. Arrives before its first contract.paid.	Contract
contract.paid	Any capture settled, the Cart Capture included.	Installment
contract.completed	The final installment settled.	Contract
contract.past_due	Attempt 2 on an Installment Capture failed and the consumer was notified. Both clocks start here.	Installment
contract.delinquent	The grace period ran out and the late charge was assessed. The plan defaults at the end of the cure period.	Installment
contract.cancelled	The plan was called off. Nothing further is collected.	Contract
contract.defaulted	The plan went unpaid and was written off. Nothing further is collected.	Contract
payment.failed	An automated attempt on an Installment Capture failed.	Payment failure

Payloads

The shape carried in data.object. Amounts are integer minor units (cents) and timestamps are ISO 8601, matching the rest of the API.

Session

Field	Notes
id	The session token.
status	pending, decision_made, completed, cancelled or expired.
order_reference	Your own order identifier, as sent when the session was opened.
total_amount	The order total the session was quoted against.
customer_email	Null when the customer was not identified.
expires_at	When the session lapses if nobody acts on it.
completed_at	Null until the plan is confirmed.
metadata	Your own key/value pairs, as sent when the session was opened. {} when none.

Contract

Field	Notes
reference	The agreement's identifier.
order_reference	Carried over from the session.
status	The agreement's state.
customer_name	The name on the customer's ShotPay account.
customer_email	The address on the customer's ShotPay account.
total_amount	The order total.
product	layaway or bnpl.
reservation_fee_amount	The Reservation Fee, retained on default.
customer_total	What the customer pays — total_amount plus the reservation fee.
down_payment_amount	Collected at checkout.
started_at	Null until the agreement opens.
completed_at	Null until the final installment settles.
metadata	Copied from the session the contract came from. {} when none.

Installment

Names its contract rather than embedding it, so a receiver does not have to hold state to know which plan moved.

Field	Notes
contract_reference	The agreement this installment belongs to.
order_reference	Carried over from the session.
sequence	The row's position. 1 is the Cart Capture.
type	cart_capture or installment_capture.
installment_number	The Installment Capture's number within the plan; null on the Cart Capture.
amount
due_date	A date, not a timestamp.
status	The capture's state.
paid_at	Null until it settles.
past_due_at	T₀ — when the consumer was notified. Null until then.
grace_ends_at	Derived from past_due_at. Null until then.
defaults_at	Derived from past_due_at. Null until then.

Payment failure

The installment, plus why the charge did not go through.

Field	Notes
attempt_number	Which attempt on the capture failed.
rail	ach or card.
failure_reason	What the processor said. Null when it gave no reason.
return_code	The ACH return code, when the bank gave one. Null on card.
will_retry	Whether Attempt 2 is scheduled.