Webhook Notifications

This reference describes how to receive and process server-to-server webhook notifications from Codapay. These notifications keep your backend synchronized with the transaction status as a user progresses through the payment flow.

Overview

Codapay uses webhooks to notify your "Complete Notification URL" whenever a transaction reaches a final state or a critical milestone.

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

Event Types

For Codapay integrations, your endpoint should be prepared to handle the following eventType values:

Event Type	Type	Description
SHOPPER_CREATED	Shopper notification	A new shopper profile is created.
PAYMENT_METHOD_ADDED	Payment Method notification	The shopper successfully saved a new payment method.
PAYMENT_METHOD_REMOVED	Payment Method notification	The shopper removed a saved payment method.
CHARGE_SUCCESSFUL	Transaction Notification	The payment transaction is successfully completed.
CHARGE_FAILED	Transaction Notification	The payment transaction failed
AUTHORIZATION_SUCCESSFUL	Transaction Notification	The user successfully authorized the transaction (e.g., 3DS).
AUTHORIZATION_FAILED	Transaction Notification	The user failed authorized or the bank denied the request.
CAPTURE_INITIATED	Transaction Notification	The system has started the process of capturing the authorized funds.
CAPTURE_SUCCESSFUL	Transaction Notification	The funds have been successfully captured. Transaction is complete.
CAPTURE_FAILED	Transaction Notification	The capture process failed after a successful authorization.

Notification Payload Structure

Notifications are sent as a POST request with a JSON body. Each type of notification has a specific structure and content.

Transaction Notifications

Field	Type	Description
eventType	string	The specific event type being reported (e.g., CAPTURE_SUCCESSFUL)
txnId	string	The unique transaction ID generated by Coda
orderId	string	The merchant-side unique identifier for the order
checksum	string	A security hash used to verify that the notification payload has not been tampered with
chargedAt	string	Timestamp indicating when the transaction was processed.
amountValue	decimal	The final amount charged to the user in the billing currency
amountCurrency	string	The ISO 4217 currency code for the charged amount (e.g., PHP)
originalValue	decimal	The original price of the item before any currency conversions
originalCurrency	string	The ISO 4217 currency code for the original price
resultCode	integer	Status code of the transaction. 0 indicates success; other values indicate errors.
resultDesc	string	A human-readable description of the transaction result.
shopper	object	An object containing shopper details such as ID, email, or partner-specific identifiers.
paymentMethod	object	Information regarding the payment instrument used (e.g., card type, last four digits).
transactionData	object	A flexible object containing supplementary metadata specific to the transaction or payment channel.

Successful Notification Example

{
    "eventType": "CAPTURE_SUCCESSFUL",
    "txnId": 783437392732893567,
    "orderId": "2eb63b9e-f4c5-4e20-9783-2253cd7dc1d0",
    "checksum": "76c1eb25c01e4d5fd2fe8e64091b82bc",
    "chargedAt": "2026-04-01T00:00:00Z",
    "amountValue": 59.0,
    "amountCurrency": "PHP",
    "originalValue": 59.0,
    "originalCurrency": "PHP",
    "resultCode": 0,
    "resultDesc": "Success",
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
}

Failed Notification Example

When an event like AUTHORIZATION_FAILED or CAPTURE_FAILED occurs, the resultCode will contain a non-zero value.

{
    "eventType": "AUTHORIZATION_FAILED",
    "txnId": 783437392732893567,
    "orderId": "2eb63b9e-f4c5-4e20-9783-2253cd7dc1d0",
    "checksum": "76c1eb25c01e4d5fd2fe8e64091b82bc",
    "chargedAt": "2026-04-01T00:00:00Z",
    "amountValue": 59.0,
    "amountCurrency": "PHP",
    "originalValue": 59.0,
    "originalCurrency": "PHP",
    "resultCode": 750,
    "resultDesc": "Failed",
    "shopper": {},
    "paymentMethod": {},
    "transactionData": {}
  }
}

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

Shopper Notifications

Field	Type	Description
eventType	string	The specific event type being reported (e.g., SHOPPER_CREATED)
shopperId	string	The unique shopper ID generated by Coda
checksum	string	A security hash used to verify that the notification payload has not been tampered with
partnerShopperId	string	The merchant-side unique identifier for the shopper
status	string	The status of the shopperId
shopperInformation	object	Additional information about the shopper

Notification Example

{
  "eventType": "SHOPPER_CREATED",
  "shopperId": "shp_sg18bfb6894ea0000",
  "partnerShopperId": "partner-shopper-345",
  "checksum": "76c1eb25c01e4d5fd2fe8e64091b82bc",
  "status": "active",
  "shopperInformation": {
    "email": "[e-mail]",
    "phoneNumber": "0553728274",
    "billingInformation": {
      "firstName": "John",
      "lastName": "Doe",
      "documentType": "CPF",
      "documentId": "1EF2345432345",
      "address": "33 Main St.",
      "city": "Awesome City",
      "region": "CA",
      "country": "US",
      "zipCode": "91220"
    }
  }
}

Payment Method Notifications

Field	Type	Description
eventType	string	The specific event type being reported (e.g., SHOPPER_CREATED)
timestamp	string	The timestamp of when the event occurred
checksum	string	A security hash used to verify that the notification payload has not been tampered with
status	string	The status of the link between the shopperId and the payment method
shopper	object	An object containing shopper details such as ID, email, or partner-specific identifiers.
paymentMethod	object	Information regarding the payment instrument used (e.g., token, card type, last four digits).

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.