Integration steps
Integration steps
Step-by-step instructions for the technical integration of the chargeback system

Overview

Chargeback API conform to representational state transfer (REST) design principles. They have predictable resource-oriented URLs, accept json-encoded request bodies, return JSON-encoded responses, use standard HTTP response codes and authentication.

warning
All data sent to Chargebackhit with the upload API must be in a JSON string format that is capable of parsing back to JSON.

The main steps of the integration are:

  • Technical integration with Chargebackhit
  • Testing:
    • Sandbox account
    • Production account
  • Account settings

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


Step 1 - Login Information

  • Receive an invitation to work email with account credentials for the merchant portal hub
  • Get API keys (public and secret key) obtained from the Guide
    This page with settings for Chargebackhit users to configure their preferences.
    “Settings”
    page

Step 2 - Notification URL

Create and provide notification URL for:

  • Sandbox account
  • Production account
You can also set and change URLs in the portal inside Guide
This page with settings for Chargebackhit users to configure their preferences.
“Settings”.

Step 3 - Signature Creation

The value of a signature is a base64-encoded value of hash function SHA-512. For the encryption key, the Secret Key will be applied. The following string will be used for signature data:

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

The signature allows the merchant system to verify the source and the integrity of the notification details transmitted between the Merchant and Chargebackhit.

The merchant will apply the Public Key and Secret Key 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

The merchant is initially configured for working via a test environment and can check the Integration with a set of test alerts, which can be generated manually in the sandbox account in the alerts section:

warning
The merchant can go live after integration is completed, and UAT testing is passed.


Step 6 - Matching and response

To address the alerts (refund, provide the response, etc.), firstly, we need to match the alerts to the exact transaction in the merchant’s database/CRM.

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
.

Timeouts

success
When integrating Chargebackhit into your workflows, you need to consider how long you can wait for a response from our system.

In an API-based service, timeouts define the total time available to process and respond to a request. By total time, we mean the time it takes for your request to get to our servers, be processed and responded to, and the response to return to your server.

The response time includes three main components:

  • Network latency
    The delay in communicating over a network with our APIs.
  • Data enrichment
    The time to get all the values for data enrichment. Since Chargebackhit has no control over third-party servers and data sources, response times may vary.
  • Matching Process
    The time to process all rules and custom configurations in your account to create the full API response.

SLA response time:

  • Inquiry - less than 2 seconds
  • Init-refund - is according to the rules (less than 24 hours)
For all other alert types SLA response time is not critical.