Integration steps
Get in touch
Sign in
Integration steps
Step-by-step instructions for the technical integration of the chargeback alert system

The Chargeback API conforms to REST design principles, featuring resource-oriented URLs, JSON-encoded request and response bodies, standard HTTP response codes, and authentication protocols.

Steps 1-2 are recommended to be performed by the developer and steps 3-6 by the account holder.

When integrating Chargebackhit, consider the total response time for your requests, which includes network latency, data enrichment from third-party servers, and the matching process to apply your rules and configurations.

SLA response times are under 2 seconds for inquiry, less than 24 hours for init-refund according to rules, and not critical for all other alert types.

Step 1 Login Information

  1. Receive an email invitation with credentials for accessing the web portal Chargebackhit HUB
  2. Get API keys (public and secret key) obtained from the Guide
    This page with settings for Chargebackhit users to configure their preferences.
    “Settings”
    section of the web portal

Step 2 Notification URL

  1. Create and specify a notification URL for both the sandbox and production environments
  2. Notification URLs can be set and modified within the Guide
    This page with settings for Chargebackhit users to configure their preferences.
    “Settings”
    section of the web portal

Step 3 Signature creation

Generate a digital signature using SHA-512 hash function encoded in base64. This signature uses the concatenation of the public key, JSON-encoded request data, and the public key again as input.

public_key + requestJsonData + public_key
1
2
3
4
function generateSignature(string $jsonEncodedBody, string $secretKey, string $publicKey): string
{
    return base64_encode(hash_hmac('sha512', $publicKey . $jsonEncodedBody . $publicKey, $secretKey));
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import (
    "crypto/hmac"
    "crypto/sha512"
    "encoding/base64"
    "encoding/hex"
)

func GenerateSignature(jsonString, publicKey, secretKey string) string {
    payloadData := publicKey + jsonString + publicKey
    keyForSign := []byte(secretKey)
    h := hmac.New(sha512.New, keyForSign)
    h.Write([]byte(payloadData))
    return base64.StdEncoding.EncodeToString([]byte(hex.EncodeToString(h.Sum(nil))))
}
1
2
3
4
5
6
7
8
import base64
import hashlib
import hmac

def generate_signature(data: str, public_key: str, secrey_key: str) -> str:
    encrypto_data = (public_key + data + public_key).encode('utf-8')
    sign = hmac.new(secrey_key.encode('utf-8'), encrypto_data, hashlib.sha512).hexdigest()
    return base64.b64encode(sign.encode('utf-8')).decode('utf-8')
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

private const val HMAC_SHA512 = "HmacSHA512"

fun generateSignature(jsonString: String, publicKey: String, secretKey: String): String {
    val hmac = hmac(publicKey + jsonString + publicKey, secretKey)

    return base64encode(hmac)
}

private fun base64encode(data: ByteArray): String {
    return Base64.getUrlEncoder().encodeToString(data.toHexString().toByteArray())
}
  
fun ByteArray.toHexString() = joinToString("") { "%02x".format(it) }

private fun hmac(data: String, key: String): ByteArray {
    val sks = SecretKeySpec(key.toByteArray(), HMAC_SHA512)
    val mac = Mac.getInstance(HMAC_SHA512)
    mac.init(sks)
   
    return mac.doFinal(data.toByteArray())
}
1
2
3
4
5
6
7
const CryptoJS = require("crypto-js");

function generateSignature(publicKey, secretKey, data) {
  var hashed = CryptoJS.HmacSHA512(publicKey + data + publicKey, secretKey);

  return Buffer.from(hashed.toString()).toString('base64')
}

Step 4 Signature verification

Verify the integrity and authenticity of notifications using the public and secret keys to calculate the signature. Headers of each request are to be placed in the following:

Parameter Description Example
signature Signature of the request allows verifying whether the request is genuine. MjNiYjVj…ZhYmMxMzNiZDY=
public_key Unique identification, which will be shared at the moment of registration along with the Private Key. Account

Step 5 Generate sandbox alerts

Initially configure and test the integration using sandbox alerts, which can be manually generated in the sandbox account under the alerts section.

Step 6 Matching and response

Match alerts to the corresponding transactions in the merchant’s database or CRM system using an appropriate matching algorithm.

It is a straightforward process, but in some cases, we need to apply Guide
Internal logic for quick matching of alert data by the system in real-time.
specific matching
algorithm.


Looking for help? Contact us
Stay informed with Changelog