Signature Calculation

TrustPay uses the same signature algorithm for merchant API requests and merchant callbacks, including payment callbacks and chargeback alert callbacks.

Keep the merchant secret on the server. Never expose it in browser code, mobile applications, URLs, logs, or support tickets.

Algorithm

Given a JSON object and the merchant secret:

Remove the sign field.

Remove fields whose value is null or an empty string ("").

Keep valid zero values such as 0 and false.

Convert each remaining value to its canonical string form:

string: use the original string without trimming;

integer: base-10 digits;

JSON number: use its shortest non-exponential decimal representation;

boolean: true or false;

array or object: compact JSON.

Sort field names in ascending lexicographical order.

Join the pairs as key=value with &.

Append &secret=YOUR_MERCHANT_SECRET.

Calculate the MD5 digest of the UTF-8 bytes and output lowercase hexadecimal.

Do not URL-encode field names or values when building the canonical string.

Chargeback Alert Example

Payload before adding sign:

{
  "type": 7,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 352.99,
  "paid_amount": 352.99,
  "reason": "10.4",
  "event_type": "chargeback_alert.created",
  "alert_id": "cba_example_001",
  "provider_alert_id": "2L07DBRFGBDLIW7SH59V969JG",
  "platform_order_no": "TP202607270001",
  "warning_type": "ethoca",
  "alert_type": "fraud",
  "match_method": "arn",
  "currency": "USD",
  "chargeback_amount": 352.99,
  "chargeback_currency": "USD",
  "chargeback_alert_fee": 4.5299,
  "masked_card_number": "800012******6824",
  "arn": "12345678901234567890123",
  "chargeback_reason_code": "10.4",
  "source": "ethoca",
  "alert_timestamp": "2026-07-27T12:00:00Z",
  "transaction_timestamp": "2026-07-26T12:00:00Z",
  "received_at": "2026-07-27T12:00:01Z"
}

Example secret used only for this calculation:

test_secret_key_12345_abcdefghijklmnop

Canonical string:

alert_id=cba_example_001&alert_timestamp=2026-07-27T12:00:00Z&alert_type=fraud&arn=12345678901234567890123&chargeback_alert_fee=4.5299&chargeback_amount=352.99&chargeback_currency=USD&chargeback_reason_code=10.4&currency=USD&event_type=chargeback_alert.created&masked_card_number=800012******6824&match_method=arn&merchant_id=1001&order_amount=352.99&order_no=ORDER_123456&paid_amount=352.99&platform_order_no=TP202607270001&provider_alert_id=2L07DBRFGBDLIW7SH59V969JG&reason=10.4&received_at=2026-07-27T12:00:01Z&source=ethoca&transaction_timestamp=2026-07-26T12:00:00Z&type=7&warning_type=ethoca&secret=test_secret_key_12345_abcdefghijklmnop

Result:

74b056edb0a02de837ec134a241e19ea

JavaScript Example

Go Example

Verification Checklist

Parse the JSON body without changing values before verification.

Exclude only sign, null, and empty strings; do not exclude numeric zero.

Do not round amounts or add trailing zeros.

Do not URL-encode the canonical string.

Use the same merchant secret that is configured for the callback merchant.

Compare signatures in constant time.

Log only the verification result. Never log the canonical string or secret.

Signature Calculation

Algorithm#

Chargeback Alert Example#

JavaScript Example#

Go Example#

Verification Checklist#

Algorithm

Chargeback Alert Example

JavaScript Example

Go Example

Verification Checklist