> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/codapay/recurring-payments-coming-soon/webhook-notifications.md).

# 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.

{% hint style="info" %}
Ensure your "Complete Notification URL" is configured in the Publisher Portal. Refer to the [Set up payments](/codapay/getting-started/set-up-payments.md) guide for detailed instructions.
{% endhint %}

### Event Types

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

| Event Type                 | Type                                                         | Description                                                           |
| -------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- |
| `SHOPPER_CREATED`          | [Shopper notification](#shopper-notifications)               | A new shopper profile is created.                                     |
| `PAYMENT_METHOD_ADDED`     | [Payment Method notification](#payment-method-notifications) | The shopper successfully saved a new payment method.                  |
| `PAYMENT_METHOD_REMOVED`   | [Payment Method notification](#payment-method-notifications) | The shopper removed a saved payment method.                           |
| `CHARGE_SUCCESSFUL`        | [Transaction Notification](#transaction-notifications)       | The payment transaction is successfully completed.                    |
| `CHARGE_FAILED`            | [Transaction Notification](#transaction-notifications)       | The payment transaction failed                                        |
| `AUTHORIZATION_SUCCESSFUL` | [Transaction Notification](#transaction-notifications)       | The user successfully authorized the transaction (e.g., 3DS).         |
| `AUTHORIZATION_FAILED`     | [Transaction Notification](#transaction-notifications)       | The user failed authorized or the bank denied the request.            |
| `CAPTURE_INITIATED`        | [Transaction Notification](#transaction-notifications)       | The system has started the process of capturing the authorized funds. |
| `CAPTURE_SUCCESSFUL`       | [Transaction Notification](#transaction-notifications)       | The funds have been successfully captured. Transaction is complete.   |
| `CAPTURE_FAILED`           | [Transaction Notification](#transaction-notifications)       | 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

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

#### Successful Notification Example

```json
{
    "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.

```json
{
    "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": {}
  }
}
```

{% hint style="info" %}
You can find the full list of error codes and their meanings is available [here](/codapay/error-codes.md).
{% endhint %}

#### Shopper Notifications

<table><thead><tr><th width="185.33203125">Field</th><th width="117.671875">Type</th><th>Description</th></tr></thead><tbody><tr><td>eventType</td><td>string</td><td>The specific event type being reported (e.g., <code>SHOPPER_CREATED</code>)</td></tr><tr><td>shopperId</td><td>string</td><td>The unique shopper ID generated by Coda</td></tr><tr><td>checksum</td><td>string</td><td>A security hash used to verify that the notification payload has not been tampered with</td></tr><tr><td>partnerShopperId</td><td>string</td><td>The merchant-side unique identifier for the shopper</td></tr><tr><td>status</td><td>string</td><td>The status of the shopperId</td></tr><tr><td>shopperInformation</td><td>object</td><td>Additional information about the shopper</td></tr></tbody></table>

#### Notification Example

```json
{
  "eventType": "SHOPPER_CREATED",
  "shopperId": "shp_sg18bfb6894ea0000",
  "partnerShopperId": "partner-shopper-345",
  "checksum": "76c1eb25c01e4d5fd2fe8e64091b82bc",
  "status": "active",
  "shopperInformation": {
    "email": "shopper@cool-shopper.com",
    "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

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

### Responding to Notifications

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

```json
{
  "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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/codapay/recurring-payments-coming-soon/webhook-notifications.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.