Payment Method Webhook Events

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

Notification Payload Structure

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

Payment Method Notifications

Field	Type	Description
eventType	string	The specific event type being reported (e.g., PAYMENT_METHOD_ADDED)
timestamp	string	The timestamp of when the event occurred
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).

PAYMENT_METHOD_ADDED

This notification is sent when a new card is successfully saved and linked to the shopper profile.

Notification Payload

{
  "eventType": "PAYMENT_METHOD_ADDED",
  "timestamp": "2025-06-19T02:48:39.568907Z",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partner_shopper_id": "test_partner_123_Id",
    "email": "[e-mail]"
  },
  "paymentMethod": {
    "id": "pmt_sg1000616a1900024",
    "type": "card",
    "card": {
      "lastFour": "7263",
      "expirationMonth": "04",
      "expirationYear": "2027"
    }
  }
}

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.