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.

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

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.

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:

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

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)