Webhooks
Receive signed payment-status notifications and integrate configurable checkout callbacks.
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.
| Flow | When it runs | Use it to |
|---|---|---|
| Order and payment status notification | After a subscribed payment status changes | Update fulfillment, reconciliation, and customer-order state without polling continuously. |
| Dynamic checkout webhook | While checkout is waiting for a merchant response | Apply 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.
payment.<status>, and DEUNA checks the merchant subscription.Configure status delivery
Define the delivery contract for each environment:
| Setting | What to define |
|---|---|
| Destination | The HTTPS endpoint that accepts status notifications. |
| Events | The payment.<status> events required by your order lifecycle. |
| Request contract | Any static headers, URL parameters, and approved payload transformation. |
| Failure handling | The 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": {
"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.
- Read the unmodified request body before a framework parses or reserializes it.
- Apply the HMAC-SHA256 and Base64 verification procedure certified for the delivery flow and environment.
- Compare the calculated value with
X-Signatureusing a constant-time comparison. - 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
- Verify the signature before trusting the payload.
- Record a deduplication key that includes the order token and event or resulting payment status.
- Return a successful
2xxresponse as soon as the request is durably accepted. - Re-read or reconcile the authoritative order state before fulfillment, cancellation, capture, refund, or another irreversible action.
- 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.
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
| Configuration | Requirement | What it controls |
|---|---|---|
event_name | Required | Merchant-specific event name using letters, numbers, hyphens, or underscores. Configure its trigger separately. |
url | Required | Merchant endpoint destination. Use HTTPS for the integration. |
http_method | Optional | HTTP method: GET, POST, PUT, or PATCH. Defaults to POST. |
headers | Optional | Array of key and value pairs for additional request headers. Values can use order templates. |
params, query_params | Optional | Arrays of key and value pairs for URL placeholders and query parameters. Values can use order templates. |
payload_template | Optional | Builds the merchant JSON request from the current order and event input. Without it, the request body contains only the event input. |
response_template | Optional | Maps the merchant JSON into the order response contract. Omit it when your endpoint already returns that contract. |
response_data | Required with response_template | JSON encoded as a string, used to validate the response template during configuration. It is not the live merchant response. |
error_response_template | Optional | Maps an alternative merchant error shape. Without it, merchant error responses use code and message. |
fields_update.fields | Optional | Array 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_fields | Optional | Array 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.fields | Required when creating the configuration | Accepts 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_fields | Optional | Array of declared custom-field names to include in the checkout result. This is separate from permission to update those fields. |
propagate_response | Optional | Defaults 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.fields | Merchant response data | Update behavior |
|---|---|---|
TotalAmount | order.total_amount | Replaces the payable total. |
TotalDiscount | order.total_discount | Replaces the aggregate discount amount. |
Discounts | order.discounts | Replaces the complete order-level discount array. |
Items.TotalAmount | order.items[].id, order.items[].total_amount | Matches existing items by ID and updates their amount, original amount, and total discount. |
Items.Discounts | order.items[].id, order.items[].discounts | Matches existing items by ID and replaces their discount references. |
Shipping | order.shipping | Replaces 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:
{
"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:
{
"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
| Concern | Merchant endpoint requirement |
|---|---|
| Repeat execution | Handle repeated input idempotently. Recalculate when the promotion input changes. |
| Response contract | Return JSON that matches the configured response shape or response template. |
| Required fields | Include every configured update field, including zero values when removing a discount. |
| Latency | Complete within the timeout certified for the integration because checkout waits for the response. |
| Errors | Return 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.
Configure and implement this flow for each environment:
- 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.
- 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,
onCardBinDetectedexposescardBinandcardBrand; see the Web SDK callback reference. The client callback and the server-to-server webhook are separate steps. - 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.
- 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.
- 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:
{
"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.
{
"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"
}'const response = await fetch("https://merchant.example.com/checkout/card-discounts", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
body: JSON.stringify({
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"POST",
"https://merchant.example.com/checkout/card-discounts",
headers={
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
json={
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://merchant.example.com/checkout/card-discounts",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Signature: SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation: OPERATION_FROM_DEUNA"
],
CURLOPT_POSTFIELDS => json_encode([
"order_token" => "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id" => "merchant-order-123",
"currency" => "USD",
"total_amount" => 10000,
"cardBin" => "411111",
"cardBrand" => "visa"
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("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")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("POST", "https://merchant.example.com/checkout/card-discounts", strings.NewReader("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
if err != nil { panic(err) }
request.Header.Set("Content-Type", "application/json")
request.Header.Set("X-Signature", "SIGNATURE_FROM_DEUNA")
request.Header.Set("X-Deuna-Operation", "OPERATION_FROM_DEUNA")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}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:
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 field | JSON type | Required in this example | Meaning |
|---|---|---|---|
order.total_amount | integer | Yes | Final payable total in minor currency units, after the discount. |
order.total_discount | integer | Yes | Total discount in the same units, including the card promotion. |
order.discounts | array of objects | Yes | Complete 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:
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 field | JSON type | Meaning |
|---|---|---|
amount | integer | Monetary amount applied by this discount. |
code, reference | string | Merchant promotion code and reference identifier. |
description, details_url | string | Description and optional details link for the promotion. |
type | string | Discount type: order_value, product, or free_shipping. |
discount_category | string | Merchant classification for the discount. |
target_type | string | Target component when applicable: item or shipping. |
free_shipping | object | Shipping-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:
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.
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: