Transaction status webhook

Signed payload Conomy sends to your configured webhook URL when a transaction status changes.

Objects

Webhook configuration object

Default webhook URL.

defaultcvu.staticcvu.dynamic

Per-flavor webhook URLs keyed by flavor.

Webhook event object

payment.createdpayment.authorizedpayment.capturedpayment.receivedpayment.settledpayment.unsettledpayment.expiredpayment.failedpayment.refundedpayment.requiresReviewpayment.attemptedpayment.amountMismatchpayment.underpaidpayment.overpaidpayment.pendingAssignmentpayment.reviewApprovedpayment.reviewRejectedpayment.reviewResolvedpayment.refund.createdpayment.refund.settledpayment.refund.failedcustomer.levelChangedpayment.statusChanged

Optional raw discriminator that produced the eventType, for example attempted, settled, or refundCreated.

Transaction snapshot included in a webhook delivery.

idstringrequired

Unique identifier of the Conomy transaction.

externalIdstring

External identifier provided by the merchant or provider.

totalAmountstring

Total amount processed for the transaction.

currencystring

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

productstring

Canonical purchaseCurrency:currency pair for the transaction, for example ARS:ARS or ARS:USDT.

purchaseAmountstring

Amount paid by the payer in purchaseCurrency.

purchaseCurrencystring

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

statusstringrequired

CREATEDATTEMPTPENDINGAUTHORIZEDPENDING_CAPTUREDCAPTUREDRECEIVEDSETTLEDUNSETTLEDEXPIREDFAILEDREQUIRES_REVIEWREFUNDED

typestring

descriptionstring

Transaction description when provided by the payment flow.

parentPaymentIdstring

relatedPaymentIdstring

settledAtstringdate-time

expiredAtstringdate-time

unsettledAtstringdate-time

unsettledReasonstring

settlementBatchIdstring

documentationStatusstring

PENDING_UPLOADUPLOADEDAPPROVEDREJECTEDSENT

customerIdstring

originatorobject

Payer/originator details. For CVU deposits, bankAccount and cvu carry the payer-side account number when the originating rail provides it. clearinghouseId is optional and may appear on any rail that exposes a clearinghouse reference; availability depends on the rail.

idstring

emailstringemail

Webhook transaction object

Unique identifier of the Conomy transaction.

External identifier provided by the merchant or provider.

Total amount processed for the transaction.

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

Canonical purchaseCurrency:currency pair for the transaction, for example ARS:ARS or ARS:USDT.

Amount paid by the payer in purchaseCurrency.

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

CREATEDATTEMPTPENDINGAUTHORIZEDPENDING_CAPTUREDCAPTUREDRECEIVEDSETTLEDUNSETTLEDEXPIREDFAILEDREQUIRES_REVIEWREFUNDED

Transaction description when provided by the payment flow.

PENDING_UPLOADUPLOADEDAPPROVEDREJECTEDSENT

Notification delivery object

Unique ID of this delivery. Pass it to the get and replay operations.

When this attempt was made.

The identity the notified transaction belongs to.

The transaction the event is about.

The event name that was sent. Same values as the eventType field of the webhook-transaction-event payload.

Raw discriminator that produced the eventType, for example settled or refundCreated.

deliveredfailedskipped

HTTP status your endpoint returned, or 0 when the request never completed — a timeout, DNS or TLS failure.

How many HTTP requests this single delivery row represents.

Host the request was sent to. Only the host is recorded, never the full URL, path or query string.

Whether this delivery originated in the sandbox environment.

True when this row was produced by the replay operation.

ID of the delivery this row repeats. Present only when isReplay is true. The same value is sent to your endpoint as the X-Webhook-Replay-Of header, which is how you deduplicate a replay.

Who requested the replay. Not populated yet — the audit row currently records when (createdAt) and which (replayOf) but no actor. Treat it as absent until that ships.

Webhook payload sent by Conomy to the client URL.

eventTypestringrequired

reasonstring

Optional raw discriminator that produced the eventType, for example attempted, settled, or refundCreated.

timestampstringdate-timerequired

transactionobjectrequired

Transaction snapshot included in a webhook delivery.

identityobjectrequired

First 500 characters of your endpoint's response body, kept for diagnosis. Truncated, never the full body.

Transport-level error when the request never reached your endpoint. Absent when the request completed.

Signed payload Conomy sends to your configured webhook URL when a transaction status changes. This callback is delivered to your application; you do not call this endpoint against the Conomy API. If you configured a secretKey, verify the X-Webhook-Signature header before processing the event.

Your receiver must be idempotent: The same event can arrive more than once — a delivery can reach you and fail only on the way back, and an operator can deliberately replay one through POST /v1/notifications/{id}/replay. Key your processing on transaction.id together with eventType and make reprocessing a no-op. Receiving an event twice must never credit an account, release goods or notify a user twice.

Recognising a replay: A replayed request carries the X-Webhook-Replay-Of header with the ID of the original delivery, and its body is byte-identical to the one already sent — same eventType, same timestamp, same transaction snapshot. That header and the body are the two handles you have for deduplication; the payload carries no separate event ID. A replay is signed with your CURRENT secretKey, so verify X-Webhook-Signature exactly as you do for a first delivery.

Seeing what we sent: GET /v1/notifications returns the audit log of every delivery attempted to your endpoint, including the stored payload and the response you returned.

WEBHOOKtransactionStatusChanged

Conomy → your URL

Headers

HMAC-SHA256 hex digest of the raw request body, present when a secretKey is configured.

ID of the original delivery this request repeats. Present only on a replay; absent on a first delivery. Use it, together with the event body, to detect and drop an event you have already processed.

Payload required

Transaction status event delivered to the client webhook URL.

Optional raw discriminator that produced the eventType, for example attempted, settled, or refundCreated.

Transaction snapshot included in a webhook delivery.

idstringrequired

Unique identifier of the Conomy transaction.

externalIdstring

External identifier provided by the merchant or provider.

totalAmountstring

Total amount processed for the transaction.

currencystring

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

productstring

Canonical purchaseCurrency:currency pair for the transaction, for example ARS:ARS or ARS:USDT.

purchaseAmountstring

Amount paid by the payer in purchaseCurrency.

purchaseCurrencystring

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

statusstringrequired

CREATEDATTEMPTPENDINGAUTHORIZEDPENDING_CAPTUREDCAPTUREDRECEIVEDSETTLEDUNSETTLEDEXPIREDFAILEDREQUIRES_REVIEWREFUNDED

typestring

descriptionstring

Transaction description when provided by the payment flow.

parentPaymentIdstring

relatedPaymentIdstring

settledAtstringdate-time

expiredAtstringdate-time

unsettledAtstringdate-time

unsettledReasonstring

settlementBatchIdstring

documentationStatusstring

PENDING_UPLOADUPLOADEDAPPROVEDREJECTEDSENT

customerIdstring

originatorobject

idstring

emailstringemail

Expected response from your URL

200Return any 2xx response after accepting the event. The response body is ignored.