Security Guidelines

Whether opting for a static or dynamic Transaction Completion Notification URL, prioritizing security is key. Unauthorized access to this URL could enable malicious actors to fabricate payment transactions, leading to potential financial loss. To safeguard against such risks, diligently implement the prescribed security measures outlined below for the protection of the Transaction Completion Notification URL.

Make sure your Transaction Completion Notification URL is secure!

---

Implement Checksum

A checksum ensures that callback/webhook notifications received from Codapay have not been altered in transit. Partners must validate the checksum before processing the notification.

The checksum format differs depending on the type of notification: Payin, Save Card (Only Available in V2 Payin), or Refund/Chargeback.

Payin Transactions (V1 / V2)

Used for standard payment(Payin) completion notifications.

Formula

txnId + apiKey + orderId + resultCode

Example

• txnId = 3381290433880074215

• apiKey = 5a8ca8f31f19a23c41edd14b29a74fd2

• orderId = 8ae6ffee169b

• resultCode = 0

Checksum string:

33812904338800742155a8ca8f31f19a23c41edd14b29a74fd28ae6ffee169b0

MD5 result:

5cb948816af0b5b61516fd71a17d271b

Save Card Notifications

Triggered when a user adds or removes a saved payment method.

Events

• PAYMENT_METHOD_ADDED

• PAYMENT_METHOD_REMOVED

Formula

eventType + apiKey + shopperId + paymentMethodId + partnerShopperId

Example Payload

{
  "eventType": "PAYMENT_METHOD_ADDED",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partnerShopperId": "test_partner_123_Id"
  },
  "paymentMethod": {
    "id": "pmt_sg1978616a1900024"
  }
}

Checksum string:

PAYMENT_METHOD_ADDED + apiKey + shp_sg197861636b40021 + pmt_sg1978616a1900024 + test_partner_123_Id

→ Apply MD5 hash.

Refund & Chargeback Notifications

Used for refund or chargeback events.

Formula

eventType + apiKey + txnId + orderId + resultCode + statusCode

This ensures that refund/chargeback notifications are validated consistently and securely.

Checksum Comparison Table

Scenario	Payload Format	Formula	Hash Algorithm	Example Parameters
Payin (V1/V2)	Query String	txnId + apiKey + orderId + resultCode	MD5	txnId: 3381290433880074215orderId: 8ae6ffee169bresultCode: 0
Save Card (Only Available in V2 Payin)	JSON Body	eventType + apiKey + shopperId + paymentMethodId + partnerShopperId	MD5	eventType: PAYMENT_METHOD_ADDEDshopperId:shp_... paymentMethodId: pmt_...
Refund / Chargeback	JSON Body	eventType + apiKey + txnId + orderId + resultCode + statusCode	MD5	eventType: REFUND txnId: 123... statusCode: 200

Implement HTTPS

This will prevent third parties from message eavesdropping.

Filtering Merchant IP

This whitelisting is based on rendering on the init interface, and only the IP you whitelisted can request orders. Directions: Publisher Portal -> Integration -> Security -> Codapay Partner Settings -> Action (Edit IP Address)

Filtering Codapay IP

Only if the transaction callback can get through your firewall and send you a transaction completion notification message.

To ensure that payment callback notifications are successfully received and not rejected by your servers, please take note of the following:

1. If your firewall or server configuration requires IP whitelisting for Codapay egress IPs, please send an email request to our support team at [e-mail]

2. Upon your request, we will provide you with the updated IP ranges or alternative domain/endpoint validation details required for your whitelist configuration.