Schemas

WebhookTransactionEvent

Envelope for every transaction webhook. The contract is additive by default. New fields may appear at any time without a version bump and receivers must ignore unknown fields. Payloads never contain cardholder data. Amounts are integers in minor units.

id

string · pattern: ^evt_[0-9a-z]{26}$ · required

Event id, the idempotency key across retries and replays.

type

string · enum · required

Enum values:

transaction.authorized

transaction.captured

transaction.succeeded

transaction.settled

transaction.partially_settled

transaction.paid

transaction.voided

transaction.refunded

created_at

string · date-time · required

Event creation time (ISO 8601 UTC).

api_version

string · required

Payload schema version.

object · required

WebhookTransactionSnapshot

Snapshot of the transaction row that triggered the event.

id

integer · required

Gateway transaction id, the value the transaction routes currently take. Leaves the payload on a future api_version once the routes accept public ids.

public_id

string · pattern: ^txn_[0-9a-z]{26}$ · required

The transaction's opaque public id, the stable Softlemon reference to store.

transaction_type

string · enum · required

Enum values:

sale

auth

capture

void

refund

status

string · required

Transaction status. See the transaction statuses guide.

payment_method

string · required

card for the card lane, otherwise the alternative payment method code (for example psc).

amount

integer · required

Amount in minor units.

currency

string · required

ISO 4217 currency code.

merchant_trans_id

string | null

The merchant's own reference. Captures, refunds and voids share the parent's value. It is not unique on its own.

related_trans_id

integer | null

Parent transaction id on child rows (captures, refunds, voids).

payment_session_id

string · pattern: ^ps_[0-9a-z]{26}$

Present on redirect/APM transactions only: the payment session public id to reconcile against the payment sessions API.

provider_transaction_id

string | null

Present on redirect/APM transactions only: the provider's own transaction id.

captured_amount

integer

Present only on authorization rows (transaction_type = auth).

refunded_amount

integer

Present only on sale and capture rows.

acquirer_provider

string | null

acquirer_trans_id

string | null

acquirer_auth_code

string | null

description

string | null

created_at

string | null · date-time

updated_at

string | null · date-time

WebhookParentTransactionSummary

Present only on child-row events (captures, refunds and voids). Contains the parent's updated totals.

id

integer · required

public_id

string · pattern: ^txn_[0-9a-z]{26}$ · required

status

string · required

amount

integer · required

captured_amount

integer · required

refunded_amount

integer · required

WebhookPingEvent

Test ping payload. Signed like a real event and never persisted.

id

string · pattern: ^evt_[0-9a-z]{26}$ · required

type

string · const · required

Const value: ping

created_at

string · date-time · required

api_version

string · required

object · required

WebhookTransactionEvent

id

string · pattern: ^evt_[0-9a-z]{26}$ · required

Event id, the idempotency key across retries and replays.

type

string · enum · required

Enum values:

transaction.authorized

transaction.captured

transaction.succeeded

transaction.settled

transaction.partially_settled

transaction.paid

transaction.voided

transaction.refunded

created_at

string · date-time · required

Event creation time (ISO 8601 UTC).

api_version

string · required

Payload schema version.

object · required

WebhookTransactionSnapshot

Snapshot of the transaction row that triggered the event.

id

integer · required

Gateway transaction id, the value the transaction routes currently take. Leaves the payload on a future api_version once the routes accept public ids.

public_id

string · pattern: ^txn_[0-9a-z]{26}$ · required

The transaction's opaque public id, the stable Softlemon reference to store.

transaction_type

string · enum · required

Enum values:

sale

auth

capture

void

refund

status

string · required

Transaction status. See the transaction statuses guide.

payment_method

string · required

card for the card lane, otherwise the alternative payment method code (for example psc).

amount

integer · required

Amount in minor units.

currency

string · required

ISO 4217 currency code.

merchant_trans_id

string | null

The merchant's own reference. Captures, refunds and voids share the parent's value. It is not unique on its own.

related_trans_id

integer | null

Parent transaction id on child rows (captures, refunds, voids).

payment_session_id

string · pattern: ^ps_[0-9a-z]{26}$

Present on redirect/APM transactions only: the payment session public id to reconcile against the payment sessions API.

provider_transaction_id

string | null

Present on redirect/APM transactions only: the provider's own transaction id.

captured_amount

integer

Present only on authorization rows (transaction_type = auth).

refunded_amount

integer

Present only on sale and capture rows.

acquirer_provider

string | null

acquirer_trans_id

string | null

acquirer_auth_code

string | null

description

string | null

created_at

string | null · date-time

updated_at

string | null · date-time

WebhookParentTransactionSummary

Present only on child-row events (captures, refunds and voids). Contains the parent's updated totals.

id

integer · required

public_id

string · pattern: ^txn_[0-9a-z]{26}$ · required

status

string · required

amount

integer · required

captured_amount

integer · required

refunded_amount

integer · required