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

Codapay supports two notification methods:

• GET Notifications (Legacy) — Transaction status is sent as query parameters appended to your notification URL.

• POST Notifications — Transaction status is sent as a JSON body in a POST request to your notification URL.

Note: GET notifications are the default method. To activate POST notifications, please contact your Codapay account manager.

---

GET Notifications (Legacy)

Receive notifications of transaction status changes as your user progresses through the payment flow.

During the payment flow, the transaction status will be one of the following:

• Pending

• Successful

• Failed

You will be notified whenever a transaction is marked as 'Successful' or 'Failed' via the Transaction Completion Notification URL configured in the Publisher Portal.

Pre-requisite

• The Transaction "Complete Notification URL" is configured in Publisher Portal. Refer to Set up payments for detailed instructions. Changes will take effect immediately.

Notification parameters

Notifications are sent to the configured transaction complete notification URL with the appended query parameters below:

Parameters	Description
TxnId	Always The transaction ID generated during the payment request initiation
OrderId	Always Your Order ID, passed during the payment request initiation
*OriginAmount	*Always (v2.0 only) Original amount in OriginCurrency as provided in the initiation request
*OriginCurrency	*Always (v2.0 only) ISO 4217 alphabetic code (USD, GBP, etc). The original currency used in the initiation request to specify the item price. OriginCurrency can be different from PayCurrency.
*PayAmount	*Always (v2.0 only) Final price in PayCurrency charged to the user. Note: TotalPrice always = PayAmount
*PayCurrency	*Always (v2.0 only) ISO 4217 alphabetic code (USD, GBP, etc). Currency used for the actual payment charged to the user.
*SubTotalPrice	*Always (v2.0 only) The net amount of the transaction before taxes. Calculated as: totalPrice / (1 + payTaxRate). This represents the base item price excluding local service or digital taxes.
*PayTaxRate	*Always (v2.0 only) The tax percentage rate applied to the transaction (e.g., 0.10 for 10%). This value is dynamically determined based on the merchant configuration, regional tax laws, or the user's specific location (Zip Code).
resultDesc	Always The resultDesc parameter is designed to assist merchants in accurately analyzing and addressing the causes of transaction failures. If the resultCode equals 0, the resultDesc will return Success. If the resultCode indicates an error, the resultDesc will provide a detailed description of the error.
ResultCode	Always The ResultCode will help indicate the status of the transaction. ResultCode = 0 means the transaction is successful. ResultCode = 431, 481 or 216 means that the transaction is pending. All other ResultCode values mean that the transaction Failed. You can find the full list of error codes and their explanation here.
TotalPrice	Always The total amount the user has paid for the transaction. This will always be in local currency.
PaymentType	Always The PaymentType the user attempted to pay with. PaymentType is equal to the payment channel ID or 1 in case the payment channel is a Carrier Billing.
Checksum	Always The Checksum helps verify that the message is sent by Codapay and has not been tampered with. Refer to the Security section for more information on how to use this value.
MnoId	Optional If the need_mno_id parameter was used during payment channel initiation, this parameter will contain the payment channel ID
USDPrice	Optional If a transaction is initiated in a country where USD is not the local currency, the Coda callback parameter (TotalPrice) will default display the user's local currency amount. If you require adding the initial USDPrice to the callback, please configure it from the Publisher Portal. Refer to the USD report section for more details.

Expected Response

After sending the notification, Codapay expects an acknowledgement to confirm it has been received.

If your application processes the notification successfully, respond with ResultCode=0. Otherwise, return an error code.

If no response is received, the notification will be re-sent 3 times at 5-minute intervals. If all attempts fail, an email alert will be triggered.

To subscribe to transaction notifications, go to the Publisher Portal. Team > Manage Access > Tick "Transaction Notification" > Save Changes

Sample

v2.0 Notification

// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7715121708032676249
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.00
  PaymentType=237
  ResultCode=0
  Checksum=6b6c5e0f835f9f1442726bed3aedc3c9
  PayTaxRate=8.00 //This field is only returned in v2.0 API
  PayCurrency=MYR //This field is only returned in v2.0 API
  PayAmount=1.00 //This field is only returned in v2.0 API
  OriginAmount=1.00 //This field is only returned in v2.0 API
  OriginCurrency=MYR //This field is only returned in v2.0 API
  SubTotalPrice=0.93 //This field is only returned in v2.0 API

// Sample for USD payments initiated
https://<your_webhook_url>?
  TxnId=7715122576202672831
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.17
  PaymentType=237
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963
+ USDPrice=0.30
  PayTaxRate=8.00 //This field is only returned in v2.0 API
  PayCurrency=MYR //This field is only returned in v2.0 API
  PayAmount=1.17 //This field is only returned in v2.0 API
  OriginAmount=0.30 //This field is only returned in v2.0 API
  OriginCurrency=USD //This field is only returned in v2.0 API
  SubTotalPrice=1.08 //This field is only returned in v2.0 API

v1.0 Notification

// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7178589013775074766
  OrderId=12321312321314
  TotalPrice=100
  PaymentType=101
  ResultCode=0
  Checksum=e944d44f065eade8157737385a094a57
+ USDPrice=10.00

// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7178589013775038493
  OrderId=12321312321314
  TotalPrice=100
  PaymentType=101
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963

Response

ResultCode=0

Checking a transaction status

We highly recommend using the inquiryPaymentResult API call after receiving the purchase notification webhook. This will help reconcile the transaction status between your system and Coda's before releasing the purchased item.

---

POST Notifications

POST notifications provide a more structured and extensible notification format using JSON payloads delivered via POST requests.

Note: POST notifications must be activated for your account. Contact your Codapay account manager to enable this feature.

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
CHARGE_SUCCESSFUL	Transaction Notification	The payment transaction is successfully completed.
CHARGE_FAILED	Transaction Notification	The payment transaction failed.
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.

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., CHARGE_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., MYR)
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": "CHARGE_SUCCESSFUL",
  "txnId": "1a2b3c4d5e6f7890",
  "orderId": "2a5eb9fe-3fc5-4a98-9f83-235b3f0c5d0f",
  "checksum": "f0c1eb25c01e4d5fd2fe8eb4091b82bc",
  "chargedAt": "2026-06-01T06:00:002",
  "amountValue": 59.0,
  "amountCurrency": "MYR",
  "originalValue": 15.0,
  "originalCurrency": "MYR",
  "resultCode": 0,
  "resultDesc": "Success",
  "shopper": {},
  "paymentMethod": {},
  "transactionData": {}
}

Failed Notification Example

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

{
  "eventType": "CHARGE_FAILED",
  "txnId": "1a2b3c4d5e6f7890",
  "orderId": "2a5eb9fe-3fc5-4a98-9f83-235b3f0c5d0f",
  "checksum": "f0c1eb25c01e4d5fd2fe8eb4091b82bc",
  "chargedAt": "2026-06-01T06:00:002",
  "amountValue": 59.0,
  "amountCurrency": "MYR",
  "originalValue": 15.0,
  "originalCurrency": "MYR",
  "resultCode": 706,
  "resultDesc": "Failed",
  "shopper": {},
  "paymentMethod": {},
  "transactionData": {}
}

You can find the full list of error codes and their meanings 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
partnerShopperId	string	The merchant-side unique identifier for the shopper
checksum	string	A security hash used to verify that the notification payload has not been tampered with
status	string	The status of the shopperld
shopperInformation	object	Additional information about the shopper

Notification Example

{
  "eventType": "SHOPPER_CREATED",
  "shopperId": "shp_sg18bfbb8894ea0008",
  "partnerShopperId": "partner-shopper-345",
  "checksum": "?6c1eb25c01e4d5fd2fe8eb4091b82bc",
  "status": "active",
  "shopperInformation": {
    "email": "[e-mail]",
    "phoneNumber": "0553728274",
    "billingInformation": {
      "firstName": "John",
      "lastName": "Doe",
      "documentType": "CPF",
      "documentId": "18F2345432345",
      "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.