> For the complete documentation index, see [llms.txt](https://coda-payments.gitbook.io/coda-public-technical-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/integration-guides/security-guidelines.md).

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

{% hint style="danger" %} <mark style="color:red;">**Make sure your Transaction Completion Notification URL is secure!**</mark>
{% endhint %}

***

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

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

<table><thead><tr><th width="140.87109375">Scenario</th><th width="144.02734375">Payload Format</th><th>Formula</th><th width="147.18359375">Hash Algorithm</th><th>Example Parameters</th></tr></thead><tbody><tr><td><strong>Payin (V1/V2)</strong></td><td>Query String</td><td><code>txnId + apiKey + orderId + resultCode</code></td><td>MD5</td><td>txnId: <code>3381290433880074215</code>orderId: <code>8ae6ffee169b</code>resultCode: <code>0</code></td></tr><tr><td><strong>Save Card (Only Available in V2 Payin)</strong></td><td>JSON Body</td><td><code>eventType + apiKey + shopperId + paymentMethodId + partnerShopperId</code></td><td>MD5</td><td><p>eventType: <code>PAYMENT_METHOD_ADDED</code>shopperId:<code>shp_...</code></p><p>paymentMethodId: <code>pmt_...</code></p></td></tr><tr><td><strong>Refund / Chargeback</strong></td><td>JSON Body</td><td><code>eventType + apiKey + txnId + orderId + resultCode + statusCode</code></td><td>MD5</td><td><p>eventType: <code>REFUND</code></p><p>txnId: <code>123...</code></p><p>statusCode: <code>200</code></p></td></tr></tbody></table>

## Implement HTTPS&#x20;

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](https://portal.coda.co/) -> Integration -> Security -> Codapay Partner Settings -> Action (Edit IP Address)

### **Filtering Codapay IP**

{% hint style="success" %}
Only if the transaction callback can get through your firewall and send you a transaction completion notification message.
{% endhint %}

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 <codapay_integration@coda.co>
2. Upon your request, we will provide you with the updated IP ranges or alternative domain/endpoint validation details required for your whitelist configuration.