Auth & Capture Notifications

This reference describes the webhook notifications specific to authorization and capture separation. These notifications keep your backend synchronized as a transaction moves through the authorize, capture, or cancel stages.

Note: Authorization and capture separation requires POST notifications to be enabled. Both features must be activated for your account. Contact your Codapay account manager to enable them.

Overview

Codapay uses webhooks to notify your "Complete Notification URL" whenever a transaction reaches a final state or a critical milestone in the authorization and capture flow.

Ensure your "Complete Notification URL" is configured in the Publisher Portal. Refer to the Set up payments guide for detailed instructions.

Event Types

For authorization and capture separation, your endpoint should be prepared to handle the following eventType values:

Event Type	Description
authorization_successful	The user successfully authorized the transaction (e.g., 3DS)
authorization_failed	The user failed authorization or the bank denied the request
cancelled	You have decided to cancel the transaction after a successful authorization and before capture
capture_initiated	The system has started the process of capturing the authorized funds
capture_successful	The funds have been successfully captured. Transaction is complete
capture_failed	The capture process failed after a successful authorization

Notification Payload Structure

Notifications are sent as a POST request with a JSON body.

Field	Type	Description
eventType	string	The specific event type being reported (e.g., capture_successful)
timestamp	string	Notification timestamp
data.txnId	string	The unique transaction ID generated by Coda
data.orderId	string	The merchant-side unique identifier for the order
data.amountValue	decimal	The final amount charged to the user in the billing currency
data.amountCurrency	string	The ISO 4217 currency code for the charged amount (e.g., MYR)
data.originalValue	decimal	The original price of the item before any currency conversions
data.originalCurrency	string	The ISO 4217 currency code for the original price
data.resultCode	integer	Status code of the transaction. 0 indicates success; other values indicate errors.
data.resultDesc	string	A human-readable description of the transaction result.
data.shopper	object	An object containing shopper details such as ID, email, or partner-specific identifiers.
data.paymentMethod	object	Information regarding the payment instrument used (e.g., card type, last four digits).
data.transactionData	object	A flexible object containing supplementary metadata specific to the transaction or payment channel.

Successful Notification Example

The following example shows a CAPTURE_SUCCESSFUL notification, indicating that the funds have been successfully captured:

{
  "eventType": "capture_successful",
  "timestamp": "1776084951007",
  "data": {
    "txnId": "7760845022800001729",
    "orderId": "12321312321314",
    "amountValue": 1,
    "amountCurrency": "EUR",
    "originalValue": 1,
    "originalCurrency": "EUR",
    "resultCode": 0,
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
  }
}

Failed Notification Example

When an event like authorization_failed, capture_failed or cancelled occurs, the resultCode will contain a non-zero value.

{
  "eventType": "cancelled",
  "timestamp": "1776085975305",
  "data": {
    "txnId": "7760859208170001746",
    "orderId": "12321312321314",
    "amountValue": 1,
    "amountCurrency": "EUR",
    "originalValue": 1,
    "originalCurrency": "EUR",
    "resultCode": 221,
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
  }
}

You can find the full list of error codes and their meanings available here.

Notification Signature Verification

Every POST notification includes two headers that allow you to verify the request originated from Codapay and has not been tampered with:

Header	Description
X-Request-Time	The timestamp of the request, represented as epoch milliseconds (string of digits)
X-Signature	HMAC-SHA512 hex digest computed by Codapay using your merchant secret key

How It Works

Codapay and your server both agree on a single UTF-8 string to sign:

X-Request-Time + "." + raw POST body (UTF-8)

The HMAC-SHA512 algorithm is applied to this string using your merchant secret key, producing a 128-character lowercase hexadecimal digest.

Codapay sends this digest in the X-Signature header. Your server must recompute the same hex digest and compare it to the received value.

Validation Steps

1. Read the X-Request-Time and X-Signature headers from the incoming request.

2. Read the raw body bytes of the request.

3. Build the signed string: requestTime + "." + body (interpreted as UTF-8).

4. Compute the expected signature: HMAC-SHA512(secretKey, signedString) → lowercase hex.

5. Compare expectedHex to the X-Signature header value using a constant-time comparison to prevent timing attacks. The comparison is case-insensitive.

If the values do not match, reject the request.

Example — Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class SignatureValidator {

    private static final String HMAC_SHA512 = "HmacSHA512";

    public static boolean validate(String secretKey, String requestTime, byte[] body, String xSignature) {
        String bodyUtf8 = new String(body, StandardCharsets.UTF_8);
        String text = requestTime + "." + bodyUtf8;
        String expected = hmacSha512Hex(secretKey, text);
        return MessageDigest.isEqual(
            expected.toLowerCase().getBytes(),
            xSignature.toLowerCase().getBytes()
        );
    }

    private static String hmacSha512Hex(String secretKey, String text) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA512);
            mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA512));
            byte[] raw = mac.doFinal(text.getBytes(StandardCharsets.UTF_8));
            return HEX.formatHex(raw);
        } catch (Exception e) {
            throw new IllegalStateException("HMAC-SHA512 not available", e);
        }
    }
}

Responding to Notifications

To acknowledge receipt of the notification, your server must respond with a 200 OK and the following JSON body:

{
  "ResultCode": 0
}

Retry Policy: If no valid response is received, Codapay will re-send the notification 3 times at 5-minute intervals. If all attempts fail, an email alert will be triggered to your technical contact.