Skip to main content
On this page

DEUNA webhooks cover two different server-to-server flows: notifications that publish payment-state changes to your backend, and synchronous callbacks that let DEUNA request merchant-specific data or logic during checkout. Choose the flow by what your integration needs to accomplish.

FlowWhen it runsUse it to
Order and payment status notificationAfter a subscribed payment status changesUpdate fulfillment, reconciliation, and customer-order state without polling continuously.
Dynamic checkout webhookWhile checkout is waiting for a merchant responseApply coupons or card-based discounts, calculate tips or taxes, retrieve shipping information, or validate data.

Browser redirects, SDK callbacks, and provider-to-DEUNA callbacks are separate integration surfaces. Do not use them as proof of payment or as replacements for these backend flows.

Order and payment status notifications#

Status notifications deliver the latest order snapshot to your backend when the normalized payment status matches an event subscribed for the merchant. These notifications are asynchronous: the payment lifecycle does not wait for your business logic to finish.

01 · state
Payment status changes
DEUNA records a normalized payment result such as processed, authorized, captured, denied, voided, or refunded.
02 · subscription
The event is selected
The payment status becomes an event named payment.<status>, and DEUNA checks the merchant subscription.
03 · delivery
The order snapshot is sent
DEUNA sends the configured request to the merchant destination.
04 · receiver
Your backend reconciles
Your server verifies the signature, acknowledges the request, and processes the update idempotently.

Configure status delivery

Define the delivery contract for each environment:

SettingWhat to define
DestinationThe HTTPS endpoint that accepts status notifications.
EventsThe payment.<status> events required by your order lifecycle.
Request contractAny static headers, URL parameters, and approved payload transformation.
Failure handlingThe acknowledgement, retry, monitoring, and reconciliation behavior agreed for the integration.

The available events follow the payment lifecycle documented in Payment workflow and statuses. Event coverage can differ by payment method because not every method supports every payment operation or status.

Default payload

Without a custom payload transformation, DEUNA sends an HTTP POST with Content-Type: application/json and the current order under the order property:

Order-status notificationJSON
{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "processed",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "processed",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

The order can contain the customer, item, amount, payment, processor, fraud, metadata, and custom-field data associated with that transaction. Treat order.payment.data.status as the authoritative payment state, and use order.token, order.order_id, and the applicable transaction identifiers for reconciliation.

A merchant-specific configuration can change the HTTP method, headers, URL parameters, subscribed statuses, and payload shape. If a custom configuration is enabled, implement the exact contract certified for that merchant instead of assuming the default body.

Verify the signature

Current delivery adds an X-Signature header. This replaces older examples that refer to X-Deuna-Signature.

  1. Read the unmodified request body before a framework parses or reserializes it.
  2. Apply the HMAC-SHA256 and Base64 verification procedure certified for the delivery flow and environment.
  3. Compare the calculated value with X-Signature using a constant-time comparison.
  4. Reject the request before processing if the values do not match.

Status notifications and dynamic webhooks do not always sign the same input when payload transformation is enabled. Do not reuse a verifier between those flows until the signed input and key derivation have been confirmed during certification.

Keep private API keys on the server. Never place them in browser code, mobile applications, logs, or webhook responses.

Acknowledge and reconcile

  1. Verify the signature before trusting the payload.
  2. Record a deduplication key that includes the order token and event or resulting payment status.
  3. Return a successful 2xx response as soon as the request is durably accepted.
  4. Re-read or reconcile the authoritative order state before fulfillment, cancellation, capture, refund, or another irreversible action.
  5. Ignore a notification that would move your local record backward from a newer state.

Delivery failures can be retried. Do not assume exactly-once delivery, a fixed retry interval, or arrival in lifecycle order.

Dynamic checkout webhooks#

Dynamic webhooks are synchronous, merchant-specific callbacks. When checkout triggers a configured event, DEUNA sends a signed request to your endpoint, validates the response, applies only the permitted updates, and returns the configured result to checkout.

Dynamic webhooks are enabled and configured as part of the merchant implementation. They are not registered from browser or mobile code.

Configuration and execution flow

Configure the webhook with DEUNA as part of your merchant setup. Agree on the event name, destination, request and response shapes, validation rules, and fields the callback may update. After configuration, checkout can execute the event through the same agreed contract.

Sequence diagram
1Merchant team andbackend2DEUNA3Checkout UIConfigure event, endpoint,contract, and allowedupdatesTrigger the configured eventwith order and inputSend the signed requestReturn the agreed JSONresponseValidate the responseand apply permittedupdatesContinue with the configuredresult
Merchant or customerDEUNA

If the event is not configured for the merchant and environment, DEUNA does not call your endpoint. Treat a required callback that did not run as a configuration issue during certification.

Configuration capabilities

ConfigurationRequirementWhat it controls
event_nameRequiredMerchant-specific event name using letters, numbers, hyphens, or underscores. Configure its trigger separately.
urlRequiredMerchant endpoint destination. Use HTTPS for the integration.
http_methodOptionalHTTP method: GET, POST, PUT, or PATCH. Defaults to POST.
headersOptionalArray of key and value pairs for additional request headers. Values can use order templates.
params, query_paramsOptionalArrays of key and value pairs for URL placeholders and query parameters. Values can use order templates.
payload_templateOptionalBuilds the merchant JSON request from the current order and event input. Without it, the request body contains only the event input.
response_templateOptionalMaps the merchant JSON into the order response contract. Omit it when your endpoint already returns that contract.
response_dataRequired with response_templateJSON encoded as a string, used to validate the response template during configuration. It is not the live merchant response.
error_response_templateOptionalMaps an alternative merchant error shape. Without it, merchant error responses use code and message.
fields_update.fieldsOptionalArray of permitted order updates. Include each amount, discount list, or item field that the callback must replace. See the pricing fields below.
fields_update.custom_fieldsOptionalArray of custom-field names permitted to change. Fields must be declared, and their returned values must satisfy the order's custom-field schema.
response_body.fieldsRequired when creating the configurationAccepts Order, ShippingRate, and ShippingMethods. The mapped response includes the order; this list also selects auxiliary shipping results. It does not restrict which properties appear inside the order.
response_body.custom_fieldsOptionalArray of declared custom-field names to include in the checkout result. This is separate from permission to update those fields.
propagate_responseOptionalDefaults to false. Keep it false for order updates; the alternative carries the merchant JSON under dynamic_response instead of the mapped order result.

Configure pricing updates

Configuration field names and response JSON paths are different. Select only the updates your promotion needs:

Value in fields_update.fieldsMerchant response dataUpdate behavior
TotalAmountorder.total_amountReplaces the payable total.
TotalDiscountorder.total_discountReplaces the aggregate discount amount.
Discountsorder.discountsReplaces the complete order-level discount array.
Items.TotalAmountorder.items[].id, order.items[].total_amountMatches existing items by ID and updates their amount, original amount, and total discount.
Items.Discountsorder.items[].id, order.items[].discountsMatches existing items by ID and replaces their discount references.
Shippingorder.shippingReplaces the shipping original amount, total discount, and discount references.

The webhook assigns these values independently. It does not recalculate the payable total, aggregate discounts, or item allocations from the discount list. Return every allowlisted field on each successful call. Omitting a selected field can reset an amount to zero or clear a list; it is not a partial-update instruction.

The following excerpt shows the core of a tip calculation definition. It is configuration data, not a request that should be sent from the browser:

Dynamic webhook configuration excerptJSON
{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

During execution, checkout can supply event-specific input:

Event inputJSON
{
  "data": {
    "tip_amount": 500
  }
}

Without a payload template, the merchant endpoint receives that event data. With a payload template, the template can use both the current order and the event input to build the outbound JSON.

Implement the merchant endpoint

ConcernMerchant endpoint requirement
Repeat executionHandle repeated input idempotently. Recalculate when the promotion input changes.
Response contractReturn JSON that matches the configured response shape or response template.
Required fieldsInclude every configured update field, including zero values when removing a discount.
LatencyComplete within the timeout certified for the integration because checkout waits for the response.
ErrorsReturn a non-2xx response for a business or processing failure, using the configured error shape.

Dynamic calls include X-Signature and X-Deuna-Operation. When a payload template changes the outbound body, use the signature-verification input agreed during certification; do not assume it is identical to the status-notification contract above.

With response propagation disabled, the merchant response can contain order, shipping_rate, and shipping_methods. DEUNA returns the mapped order and the configured auxiliary results. With propagation enabled, the merchant response must be valid JSON and is exposed under dynamic_response. Use the mapped flow for order repricing.

Practical patterns

Card-based discounts

Use a dynamic checkout webhook to apply a promotion based on the card entered during checkout. Your backend decides eligibility and calculates the discount; DEUNA applies the configured order updates before payment.

Your backend owns the eligible bank identification numbers (BINs), card brands, and discount rules. Your DEUNA Technical Account Manager (TAM) does not need that eligibility list. DEUNA calls the endpoint when the configured trigger runs; your endpoint evaluates every request and returns either the discounted order or the order without that promotion.

A callback configured before payment runs before each payment request through that configured flow, without a BIN eligibility filter in DEUNA. A BIN-detection callback can run earlier to refresh the checkout price when the customer enters or changes a card. Confirm the callback timing and request data with DEUNA.

Complete repricing and refresh the order before checkout builds the payment request. Updating stored order totals inside a pre-payment callback does not automatically rebuild amounts already placed in that payment request.

The example below uses BIN detection. Card entry can produce a BIN event after the first six digits, before the customer completes the card details. BIN detection does not confirm that the full card is valid or that a payment is authorized.

Sequence diagram
1Checkout2DEUNA3Merchant backendCard BIN detected or changedExecute configured discounteventSigned request with orderand card inputEvaluate eligibility andcalculate totalsEligible cardDiscounted totals anddiscountsIneligible cardTotals and discounts withoutthis promotionSave permitted order updatesRefreshed order and totalsDisplay price and build paymentrequestSubmit payment withrefreshed total
Merchant or customerDEUNA

Configure and implement this flow for each environment:

  1. Configure the webhook with DEUNA. Give your DEUNA Technical Account Manager (TAM) the HTTPS destination and expected request and response. Agree on the event name, callback timing, signature verification, timeout, error handling, and order fields the response may update. Keep promotion eligibility and discount calculation in your backend.
  2. Connect the agreed trigger. For a pre-payment callback, configure its execution with DEUNA for the required payment flow. For the BIN-detection example below, coordinate the checkout wiring so that a detected or changed BIN executes the agreed event. Registering a webhook alone does not connect it to card entry. For Web SDK Payment Widget and Elements, onCardBinDetected exposes cardBin and cardBrand; see the Web SDK callback reference. The client callback and the server-to-server webhook are separate steps.
  3. Implement the merchant endpoint. Verify the signed request and evaluate the promotion on your server using the agreed order and BIN input. Keep private credentials on the server, and do not request the full card number or security code for this flow. Handle repeated calls without accumulating the same discount.
  4. Return the recalculated order. Return the revised payable total, aggregate discount, and complete discount array in the agreed JSON response. Configure the three permitted updates shown below and return the mapped order to checkout. Agree on a response template if your endpoint uses another shape, and disable response propagation for this update.
  5. Refresh the price before payment. Display the order returned by DEUNA and use its revised total for payment. Agree on how checkout removes or recalculates the promotion when the customer changes or clears the card. Define whether checkout retries, blocks payment, or continues without the promotion if the callback fails.

For example, a 10% promotion on a USD 100.00 order with no other charges produces a USD 10.00 discount and a USD 90.00 payable total. Your endpoint must calculate consistent totals; returning an eligibility flag alone does not change the order amount.

Example request and response contract

The following example covers an order with no other discounts or charges. The event name and outbound request shape are an example merchant agreement, not a built-in card-discount event or a default schema for every merchant. Confirm the contract and checkout wiring with your TAM before using it.

Amounts are integers in the order currency's minor units: 10000 represents USD 100.00. Keep the BIN as a string so that leading zeros are preserved.

Checkout supplies this event input when it executes the agreed event:

Checkout input for the example card_discount eventJSON
{
  "data": {
    "cardBin": "411111",
    "cardBrand": "visa"
  }
}

Configure the following mapping with DEUNA. This is a configuration excerpt, not a browser request. The payload template combines the current order with the event input; without it, the merchant receives only the event data.

Example card-discount webhook configurationJSON
{
  "event_name": "card_discount",
  "url": "https://merchant.example.com/checkout/card-discounts",
  "http_method": "POST",
  "payload_template": "{\"order_token\":\"{{ .Order.Token }}\",\"order_id\":\"{{ .Order.OrderID }}\",\"currency\":\"{{ .Order.Currency }}\",\"total_amount\":{{ .Order.TotalAmount }},\"cardBin\":\"{{ .Payload.cardBin }}\",\"cardBrand\":\"{{ .Payload.cardBrand }}\"}",
  "fields_update": {
    "fields": ["TotalAmount", "TotalDiscount", "Discounts"]
  },
  "response_body": {
    "fields": ["Order"]
  },
  "propagate_response": false
}

The merchant endpoint receives a request equivalent to the following cURL. DEUNA supplies the signature and operation header values. Confirm signature verification for transformed payloads with your TAM.

curl --request POST 'https://merchant.example.com/checkout/card-discounts' \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: SIGNATURE_FROM_DEUNA' \
  --header 'X-Deuna-Operation: OPERATION_FROM_DEUNA' \
  --data '{
    "order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "currency": "USD",
    "total_amount": 10000,
    "cardBin": "411111",
    "cardBrand": "visa"
  }'

The order fields identify the order being repriced; the card fields contain the event input. Validate the input on your server and use your authoritative pricing and promotion rules. Recalculate from your order's promotion base, because the incoming total may already include a discount from an earlier call. Agree on handling an unknown brand or an empty BIN when the card is cleared.

For an eligible card, return the following response with a successful HTTP status and a JSON body:

Merchant response: eligible cardHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 9000,
    "total_discount": 1000,
    "discounts": [
      {
        "amount": 1000,
        "code": "CARD_PROMO",
        "reference": "merchant-promotion-123",
        "description": "Card promotion",
        "type": "order_value",
        "discount_category": "promotion"
      }
    ]
  }
}
Response fieldJSON typeRequired in this exampleMeaning
order.total_amountintegerYesFinal payable total in minor currency units, after the discount.
order.total_discountintegerYesTotal discount in the same units, including the card promotion.
order.discountsarray of objectsYesComplete discount list to save on the order. An empty array clears this list.

Return all three configured fields on every successful call, including calls that remove the promotion. For an ineligible card in this example, return:

Merchant response: no card discountHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 10000,
    "total_discount": 0,
    "discounts": []
  }
}

DEUNA updates only the fields permitted by fields_update and returns the saved order under order to checkout. The merchant response above contains the three update fields; the checkout response contains the order with its remaining fields preserved. If other promotions apply, preserve them in the returned discount list and recalculate the totals accordingly. Only return an empty list and zero aggregate discount when no discounts remain.

Discount object contract

Each entry in the order's discount array describes an applied discount. Use integer amounts in minor currency units; a percentage promotion must return its calculated monetary amount. The following fields are supported by the mapped discount contract:

Discount fieldJSON typeMeaning
amountintegerMonetary amount applied by this discount.
code, referencestringMerchant promotion code and reference identifier.
description, details_urlstringDescription and optional details link for the promotion.
typestringDiscount type: order_value, product, or free_shipping.
discount_categorystringMerchant classification for the discount.
target_typestringTarget component when applicable: item or shipping.
free_shippingobjectShipping-promotion details: is_free_shipping is a boolean; maximum_cost_allowed is an integer in minor currency units.

These fields describe the result of your promotion logic; they do not configure eligible BINs or cause DEUNA to calculate a discount. Include the fields required by your agreed contract. Item and shipping discount lists use reference objects containing amount and ref_idx; they do not repeat the full order-level discount object. Keep those references consistent with the returned order discounts.

For a calculation or processing failure, return a non-2xx HTTP status. Without a custom error mapping, use the error body shown below. The status illustrates a temporary failure, and the error code is merchant-defined:

Merchant error responseHTTP
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "code": "PROMOTION_UNAVAILABLE",
  "message": "Unable to calculate the card promotion."
}

Agree on an error_response_template if your endpoint uses another error shape. An ineligible card is a normal no-discount result, not a processing failure. Checkout must follow the failure behavior agreed in step 5 instead of assuming a discount was applied.

Tip calculation example

This example shows the complete checkout-to-merchant path for a configured tip event.

Sequence diagram
1Shopper + checkoutUI2DEUNA3Merchant backendtip_amount_updated + ordertokenSigned request with order +tip inputRecalculated total + tipfieldValidate response andapply permittedupdatesUpdated order + tip resultDisplay the new total
Merchant or customerDEUNA

For a tip definition, allowlist only the amount and custom fields that the merchant response is expected to change. The merchant endpoint remains responsible for calculating a consistent order total.

Test in sandbox#

Test status notifications

Test a dynamic webhook

Test a card-based discount

Complete the dynamic webhook checks and verify the card-entry flow before enabling the promotion in production:

In this section