Chargebackhit API Reference

Download OpenAPI specification:Download

Enhance your understanding with our detailed business guide.

Support: support@chargebackhit.com

Get started

Chargebackhit provides API that empowers you to process and manage alerts. Chargebackhit APIs accept and return JSON in the HTTP body. You can interact with the APIs directly using your preferred HTTP/REST library or one of the client libraries provided by Chargebackhit.

Environment	Base URL
Webhook	https://api.chargebackhit.com/client-webhook-endpoint
Integration	https://api.chargebackhit.com/api/v2/integration
Alerts	https://api.chargebackhit.com/api/v2/alerts
MIDs	https://api.chargebackhit.com/api/v2/caids
Enrollment	https://api.chargebackhit.com/api/v2/import

Event handling in Webhooks

For non-ordered events, adopt practices like temporarily storing webhooks before processing, using Chargebackhit's API for additional data in case of event collisions, and processing events asynchronously to avoid timeout issues.

Authentication

When you sign up for an account, you are given a secret and public API key pair. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.

To start accepting alerts, even in the sandbox environment, you need credentials. You can easily find your credentials in the admin panel. The signature value is base64-encoded from the SHA-512 hash function. Apply the merchant's secret key for the encryption key, and use the following string for signature data:
base64encode(sha512(public_key + requestJsonData + public_key))

▶PHP


  function generateSignature(string $jsonEncodedBody, string $secretKey, string $publicKey): string
  {
    return base64_encode(hash_hmac('sha512', $publicKey . $jsonEncodedBody . $publicKey, $secretKey));
  }

▶Python


import base64
import hashlib
import hmac
def generate_signature(data: str, public_key: str, secret_key: str) -> str:
    encrypto_data = (public_key + data + public_key).encode('utf-8')
    sign = hmac.new(secret_key.encode('utf-8'), encrypto_data, hashlib.sha512).hexdigest()
    return base64.b64encode(sign.encode('utf-8')).decode('utf-8')

▶JavaScript


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')
}

▶GO


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))))
}

▶Kotlin


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())
}

To access the detailed information mentioned above, navigate to guide.

Integration

The Chargebackhit provides the following main requests for testing integration:

Generate sandbox alert for creating simulated alerts to test and validate integrations in a secure environment
Response outcome for effectively communicating chargeback and outcomes while maintaining secure and accurate data sharing.

Both requests offer appropriate response codes to help users identify successful integrations, bad requests, or unauthorized access.

Generate sandbox alert

The primary purpose of this request is to support the testing and validation of Chargebackhit integrations in a controlled environment. The request aims to create simulated alerts for testing purposes. This request ensures secure communication through the use of request signatures and public keys. It contains comprehensive information about the alert.

The request also gathers essential card-related details, such as the card acceptor ID, etc. Additionally, it encompasses merchant details, including their identification, name, and payment descriptor.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

required	object All information about it. This includes information such as the date the alert was published, the alert amount with currency, alert type, etc.
required	object Data associated with the alert transaction, used for matching the alert to the transaction. This includes information such as the date the transaction was created, the transaction amount with currency, transaction type, etc.
required	object All information about the Merchant Identification (MID). This includes information such as the unique identifier for the merchant, internal ID, payment descriptor, etc.

Responses

Request samples

Payload

Content type

application/json

{"alert": {"id": "pal-1ed9d459-3f17-4a10-be7d-a09360154a29",
"card_acceptor_id": "000000000554111",
"date": "2023-02-20T14:15:22Z",
"provider": "verifi",
"product": "oi",
"type": "inquiry",
"outcome": "acknowledged",
"acquirer_bin": "444111",
"amount": "10.00",
"currency": "USD",
"mcc": "5732",
"descriptor": "*original payment descriptor com 553 45 98",
"reason_group": "fraud",
"reason_code": "10.4",
"rdr": {"status": "declined",
"rule": "This rule will accept all RDR cases above 0.01",
"pricing_tier": "Tier 2"
}
},
"transaction": {"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "633042476707421",
"date": "2023-01-01T14:15:22Z",
"amount": "10.00",
"currency": "USD",
"type": "sale",
"card_brand": "VISA",
"bin": "411111",
"last_four": "1111",
"auth_code": "00251",
"arn": "24871153022084127852235"
},
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}

Response samples

400
401

Content type

application/json

{"error": {"code": "validation",
"message": "Validation error",
"constraints": {"field": [{"code": "not_null",
"message": "not_null"
}
]
}
}
}

Validate outcome

The primary purpose of the request is to facilitate effective communication of chargeback and outcomes while ensuring secure and accurate data sharing. The request is designed to process and communicate the outcome of a chargeback.

The request encompasses detailed information about the order, refund, customer, device, transactions, products, and merchant, including various identifiers, dates, amounts, currencies, and contact details. It also covers relevant URLs related to the merchant's policies and terms.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

outcome required	string Enum: "reversed" "previously-reversed" "decline" "reverse-error" "shipped" … 3 more Standard required response codes. Upon receiving a webhook alert, promptly provide a valid response. Only the initial response is accepted unless set to `pending`. No modifications are allowed after submission.
	object All information about the order. This includes information such as the order ID, the date the order was created, the order amount with currency, etc.
	object All information about the customer. This includes information such as the customer ID, personal data, device information, etc.
	Array of objects All information about the transactions. This includes information such as the order ID, the date the order was created, the order amount with currency, etc.
	Array of objects All information about the purchased products. This includes information such as the product name, SKU, description, etc.
	object All information about the merchant. This includes information such as the merchant's payment terms, refund policy, warranty terms, etc.

Responses

Request samples

Payload

Content type

application/json

{"outcome": "reversed",
"order": {"order_id": "3235354",
"date": "2014-11-01T14:15:22Z",
"amount": "19.99",
"currency": "USD",
"address": {"address1": "94 Mayflower Street Bronx",
"address2": "Apt 2B",
"city": "New York",
"postal_code": "10001",
"region": "NY",
"country": "USA"
},
"refund": {"date": "2014-11-01T14:15:22Z",
"amount": "19.99",
"currency": "USD"
}
},
"customer": {"customer_id": "JD123458932",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890",
"email": "johndoe@mail.com",
"date_of_birth": "1985-11-01T14:15:22Z",
"first_transaction_date": "2014-11-01T14:15:22Z",
"length_of_relationship": "5 years",
"authentication_used": "johndoe@mail.com",
"device": {"identifier": "12313212-asdfa-123123",
"name": "Johns Phone",
"location": "New York",
"ip_address": "192.168.50.123"
}
},
"transactions": [{"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "201409338",
"date": "2014-11-01T14:15:22Z",
"amount": "19.99",
"currency": "USD",
"type": "sale",
"bin": "123456",
"last_four": "1114",
"recurring_transaction": "monthly"
}
],
"products": [{"name": "Z 12 Month Antivirus Protection 1",
"sku": "16309",
"description": "12 month premium antivirus for Windows",
"url": "https://www.example.com/store/sku/16309",
"quantity": "1",
"notes": "Includes free monthly security updates"
}
],
"merchant": {"payment_terms_url": "https://www.example.com/collection_policy.html",
"refund_policy_url": "https://www.example.com/refund_policy.html",
"warranty_terms_url": "https://www.example.com/warranty",
"terms_and_conditions_url": "https://www.example.com/legal/terms.html"
}
}

Response samples

400
401

Content type

application/json

{"error": {"code": "validation",
"message": "Validation error",
"constraints": {"field": [{"code": "not_null",
"message": "not_null"
}
]
}
}
}

Manage alerts

This section ensures seamless and efficient management of alerts and outcomes within the Chargebackhit.

Update response outcome allows for efficient and secure updates of alert outcomes, ensuring up-to-date information. Get alert by ID facilitates secure access to detailed information about a specific alert, while alert list enables users to securely and effectively retrieve tailored lists of alerts based on various filtering parameters.

Update response outcome

This request facilitates efficient and secure updating of alert outcomes within the Chargebackhit.

The primary purpose of a request in the Chargebackhit is to update the outcome of a previously submitted alert. This request allows users to provide an updated response outcome for a specific alert identified by its unique identifier (UUID).

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

outcome required	string Enum: "reversed" "previously-reversed" "decline" "reverse-error" "not-found" … 3 more Standard required response codes. Upon receiving a webhook alert, the primary task is to promptly provide a valid response using one of the outcomes.
	object It contains identifier for the order.

Responses

Request samples

Payload

Content type

application/json

{"outcome": "reversed",
"order": {"order_id": "3235354"
}
}

Response samples

400
401

Content type

application/json

{"error": {"code": "validation",
"message": "Validation error",
"constraints": {"field": [{"code": "not_null",
"message": "not_null"
}
]
}
}
}

Get alert by ID

This request allows users to securely and efficiently access detailed information about a specific alert within the Chargebackhit.

The main purpose of a request in the Chargebackhit is to retrieve detailed information about a specific alert using its unique identifier (UUID). This request allows users to access and review the alert's data, including the alert's details, associated transaction data, and merchant information.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json

Array of objects

Detailed information about a specific alert.

This includes information such as the alert details, transaction data, and merchant identification (MID).

Response samples

200
400
401
404

Content type

application/json

{"data": [{"alert": {"id": "pal-1ed9d459-3f17-4a10-be7d-a09360154a29",
"card_acceptor_id": "000000000554111",
"date": "2023-02-20T14:15:22Z",
"provider": "verifi",
"product": "oi",
"type": "inquiry",
"outcome": "acknowledged",
"acquirer_bin": "444111",
"amount": "10.00",
"currency": "USD",
"mcc": "5732",
"descriptor": "*original payment descriptor com 553 45 98",
"reason_group": "fraud",
"reason_code": "10.4",
"rdr": {"status": "declined",
"rule": "This rule will accept all RDR cases above 0.01",
"pricing_tier": "Tier 2"
}
},
"transaction": {"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "633042476707421",
"date": "2023-01-01T14:15:22Z",
"amount": "10.00",
"currency": "USD",
"type": "sale",
"card_brand": "VISA",
"bin": "411111",
"last_four": "1111",
"auth_code": "00251",
"arn": "24871153022084127852235"
},
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}
]
}

Retrieve alerts list

This request allows users to securely and effectively retrieve a tailored list of alerts from the Chargebackhit based on a wide range of filtering parameters, ensuring the retrieval of relevant information.

The main purpose of the request in the Chargebackhit is to retrieve a list of alerts based on various filtering parameters, including alert types, outcomes, providers, products, transaction details, and merchant-related information. This request allows users to narrow down and access specific sets of alerts based on their requirements.

Additionally, the request provides pagination options to limit the number of results, helping manage network traffic and improve efficiency.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

	object Set of parameters used for detailed filtering. This includes parameters such as system account IDs, merchant IDs, transaction IDs, alert dates, etc.
	object The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.
	object Pagination to limit the number of results to help keep network traffic in check.

Responses

Response Schema: application/json

	Array of objects Detailed information about a specific alert. This includes information such as the alert details, transaction data, and merchant identification (MID).
	object Pagination to limit the number of results to help keep network traffic in check.

Request samples

Payload

Content type

application/json

{"filter": {"ids": ["id1",
"id2"
],
"merchant_ids": ["4e3b7f3f-2e1f-4fd3-9d4f-3a8f2e4e576d",
"8a1b5c7e-7eab-4f2a-92f8-228c7b5e16f4"
],
"merchant_internal_ids": ["mid_QWE1234",
"RTY1234"
],
"order_ids": ["b7ffcd9b-1ff5-48cd-94de-5c832547a9de",
"29c6530f-81aa-4964-9969-794f9fc143ac"
],
"transaction_ids": ["633042476707421",
"633042476707422"
],
"transaction_merchant_ids": ["f150ed65-e5fd-4309-a612-a5f4f84f6071",
"4a2ed65-l3cd-9302-b612-a5f4f84f6072"
],
"created_at_from": "2023-01-01T00:00:00Z",
"created_at_to": "2023-01-31T23:59:59Z",
"alert_date_from": "2023-01-10T00:00:00Z",
"alert_date_to": "2023-02-10T23:59:59Z",
"transaction_date_from": "2023-01-01T00:00:00Z",
"transaction_date_to": "2023-01-31T23:59:59Z",
"amount_usd_from": "5.00",
"amount_usd_to": "100.00",
"currencies": ["USD",
"EUR"
],
"types": ["inquiry",
"fraud-notification"
],
"transaction_types": ["sale"
],
"outcomes": ["reversed",
"acknowledged"
],
"providers": ["ethoca",
"verifi"
],
"products": ["oi",
"cdrn"
],
"arns": ["74624453223331975021538",
"24005453223520000007553"
],
"bin": "422121",
"acquirer_bins": ["444111",
"555222"
],
"caids": ["000000000309705",
"000000000209707"
],
"descriptors": ["Online Tech Store",
"Gadget World"
],
"acquirer_names": ["Acquirer A",
"Acquirer B"
],
"last_four": "1111",
"auth_codes": ["00251",
"00452"
]
},
"sort": {"field": "created_at_from",
"direction": "asc"
},
"pagination": {"method": "offset",
"limit": "100",
"offset": "100"
}
}

Response samples

200
400
401

Content type

application/json

{"data": [{"alert": {"id": "pal-1ed9d459-3f17-4a10-be7d-a09360154a29",
"card_acceptor_id": "000000000554111",
"date": "2023-02-20T14:15:22Z",
"provider": "verifi",
"product": "oi",
"type": "inquiry",
"outcome": "acknowledged",
"acquirer_bin": "444111",
"amount": "10.00",
"currency": "USD",
"mcc": "5732",
"descriptor": "*original payment descriptor com 553 45 98",
"reason_group": "fraud",
"reason_code": "10.4",
"rdr": {"status": "declined",
"rule": "This rule will accept all RDR cases above 0.01",
"pricing_tier": "Tier 2"
}
},
"transaction": {"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "633042476707421",
"date": "2023-01-01T14:15:22Z",
"amount": "10.00",
"currency": "USD",
"type": "sale",
"card_brand": "VISA",
"bin": "411111",
"last_four": "1111",
"auth_code": "00251",
"arn": "24871153022084127852235"
},
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}
],
"pagination": {"limit": 100,
"offset": 100,
"total_count": 999
}
}

Webhook

Webhooks are a simple yet powerful way to receive automated notifications from Chargebackhit.

With Webhooks, you can set up your application to receive notifications whenever certain alert events occur and make instant action and applicable responses.

Webhook

In the Chargebackhit webhooks implementation, there are several types of webhooks based on the alert type parameter.

Prevent webhooks are triggered when a transaction inquiry occurs that requires an immediate response - sharing transaction details, including order, customer, and product. Prevent represents the inquiry and prevented webhook alert types. Prevent includes Order Insight (OI), Compelling Evidence (CE3.0), and Consumer Clarity (CC). All transaction data can affect and increase a cardholder and issuer experience. The more valid and relevant data provided, the more effective the response can be. In addition to the basic value of Prevent, the Compelling Evidence 3.0 rule aims to deflect fraud disputes when specific conditions are met and valid mandatory fields are transferred. The mandatory fields are highlighted with the CE3.0 badges.
Resolve webhooks are triggered when a merchant-directed refund is needed to resolve a potential dispute case or automated pre-dispute resolution has occurred. Merchant-directed refunds are notified by the alert type init-refund (CDRN, ETHOCA), while automated pre-dispute resolutions are notified by the alert type resolved (RDR).
Inform webhooks are triggered when a Visa Fraud or Dispute case is filed with alert types fraud-notification or dispute-notification, respectively.

Prevent, Resolve, and Inform webhooks have a unified structure and need to be distinguished by the alert type, with specific products and providers specified in the corresponding fields.

The responses should be in accordance with the specified alert type.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

required	object All information about it. This includes information such as the date the alert was published, the alert amount with currency, alert type, etc.
required	object Data associated with the alert transaction, used for matching the alert to the transaction. This includes information such as the date the transaction was created, the transaction amount with currency, transaction type, etc.
required	object All information about the Merchant Identification (MID). This includes information such as the unique identifier for the merchant, internal ID, payment descriptor, etc.

Responses

Response Schema: application/json

One of

outcome required	string Default: "acknowledged" Standard required response codes.
	object All information about the order. This includes information such as the order ID, the date the order was created, the order amount with currency, etc.
required	object All information about the customer. This includes information such as the customer ID, personal data, device information, etc.
	Array of objects All information about the related transactions. This includes information such as the transaction ID, transaction creation date, amount, currency, etc.
required	Array of objects All information about the purchased products. This includes information such as the product name, SKU, description, etc.
	object `Cardholder/Issuer Experience` Information about the merchant, including their contacts, policies, and more, can be provided as a default during MID enrollment. If such parameters are not transmitted by the merchant, Chargebackhit will send them by default using the information provided during the onboarding process.

Request samples

Payload

Content type

application/json

{"alert": {"id": "pal-1ed9d459-3f17-4a10-be7d-a09360154a29",
"card_acceptor_id": "000000000554111",
"date": "2023-02-20T14:15:22Z",
"provider": "verifi",
"product": "oi",
"type": "inquiry",
"outcome": "acknowledged",
"acquirer_bin": "444111",
"amount": "10.00",
"currency": "USD",
"mcc": "5732",
"descriptor": "*original payment descriptor com 553 45 98",
"reason_group": "fraud",
"reason_code": "10.4",
"rdr": {"status": "declined",
"rule": "This rule will accept all RDR cases above 0.01",
"pricing_tier": "Tier 2"
}
},
"transaction": {"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "633042476707421",
"date": "2023-01-01T14:15:22Z",
"amount": "10.00",
"currency": "USD",
"type": "sale",
"card_brand": "VISA",
"bin": "411111",
"last_four": "1111",
"auth_code": "00251",
"arn": "24871153022084127852235"
},
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}

Response samples

200

Content type

application/json

Example

inquiry

{"outcome": "acknowledged",
"order": {"order_id": "3235354",
"date": "2014-11-01T14:15:22Z",
"amount": "19.99",
"currency": "USD",
"address": {"address1": "94 Mayflower Street Bronx",
"address2": "Apt 2B",
"city": "New York",
"postal_code": "10001",
"region": "NY",
"country": "USA"
},
"refund": {"date": "2014-11-01T14:15:22Z",
"amount": "19.99",
"currency": "USD"
}
},
"customer": {"customer_id": "JD123458932",
"first_name": "John",
"last_name": "Doe",
"phone": "+1234567890",
"email": "jonh@mail.com",
"date_of_birth": "1985-11-01T00:00:00Z",
"first_transaction_date": "2014-11-01T14:15:22Z",
"length_of_relationship": "5 years",
"authentication_used": "ex@mail.com",
"device": {"identifier": "12313212-asdfa-123123",
"name": "Johns Phone",
"location": "New York",
"ip_address": "192.168.50.123",
"type": "PC",
"fingerprint": "f82c23f0-74ef-11eb-9439-0242ac130002"
}
},
"transactions": [{"transaction_merchant_id": "f150ed65-e5fd-4309-a612-a5f4f84f6071",
"transaction_id": "201409338",
"date": "2014-11-01T14:15:22Z",
"amount": "22.24",
"currency": "USD",
"type": "sale",
"bin": "123456",
"last_four": "1114",
"recurring_transaction": "monthly"
}
],
"products": [{"name": "Z 12 Month Antivirus Protection 1",
"sku": null,
"description": "12 month premium antivirus for Windows",
"url": "https://www.example.com/store/sku/16309",
"quantity": "1; 2 pieces; 3 kg; ...",
"notes": "Includes free monthly security updates"
}
],
"merchant": {"merchant_name": "Acme Corporation",
"merchant_contact_phone": "+123456789012",
"merchant_address": {"address1": "94 Mayflower Street Bronx",
"address2": "Apt 2B",
"city": "New York",
"postal_code": "10001",
"region": "NY",
"country": "USA"
},
"merchant_url": "https://www.acmecorp.com",
"store_name": "Acme Online Store",
"payment_terms_url": "https://www.example.com/collection_policy.html",
"refund_policy_url": "https://www.example.com/refund_policy.html",
"warranty_terms_url": "https://www.example.com/warranty",
"terms_and_conditions_url": "https://www.example.com/legal/terms.html"
}
}

MIDs

The API offers comprehensive tools for managing and analyzing merchant and CAID data, enabling businesses to assess risk levels, and create holistic risk profiles.

Get merchant

This request allows retrieving specific merchant details using a unique identifier id. The response includes the merchant's id, name, and payment descriptor.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json

object

All information about the Merchant Identification (MID).

This includes information such as the unique identifier for the merchant, internal ID, payment descriptor, etc.

Response samples

200
400
404

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}

Update merchant

The method to update individual MID (Merchant) details using a unique identifier id.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

internal_id

string <= 500 characters

Internal ID or something else that you uses to identify your mid (field merchant_internal_id from enrollment).

Responses

Response Schema: application/json

object

All information about the Merchant Identification (MID).

This includes information such as the unique identifier for the merchant, internal ID, payment descriptor, etc.

Request samples

Payload

Content type

application/json

{"internal_id": "mid_QWE12345"
}

Response samples

200
400
404

Content type

application/json

{"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
}

Get merchant list

This request provides list of retrieves merchant lists using flexible filtering, sorting, and pagination options. Users can paginate results, sort by specified fields, and filter by parameters like ids, descriptors, and names. The response contains merchant details and pagination information.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

	object Set of parameters used for detailed filtering. This includes parameters such as system account IDs, internal IDs, payment descriptors, etc.
	object The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.
	object Pagination to limit the number of results to help keep network traffic in check.

Responses

Response Schema: application/json

	Array of objects All information about the Merchant Identification (MID). This includes information such as the unique identifier for the merchant, internal ID, payment descriptor, etc.
	object Pagination to limit the number of results to help keep network traffic in check.

Request samples

Payload

Content type

application/json

{"filter": {"ids": ["123e4567-e89b-12d3-a456-426614174000",
"123e4567-e89b-12d3-a456-426614174001"
],
"internal_ids": ["mid_QWE1234",
"RTY1234"
],
"descriptors": ["Online Tech Store",
"Gadget World"
],
"name": "Amazing Electronics"
},
"sort": {"field": "ids",
"direction": "asc"
},
"pagination": {"limit": 100,
"offset": 0
}
}

Response samples

200
400

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
}
],
"pagination": {"limit": 100,
"offset": 100,
"total_count": 999
}
}

Get CAID

Method to retrieve individual CAID (Card Acceptor ID) details using a unique identifier id.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

query Parameters

include

Array of arrays

Items Value: "caid.activities"

Include the product activations.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json

object

All information about retrieving individual CAID details.

This includes parameters such as system CAID ID, creation date, active status, merchant details, etc.

Response samples

200
400
404

Content type

application/json

{"data": {"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"created_at": "2022-10-01T14:30:00Z",
"active_from": "2022-10-01T00:00:00Z",
"mcc": "5812",
"bin": "411111",
"caid": "123456789012",
"psp_name": "Stripe",
"description": "caid_QWE12345",
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
},
"activities": [{"active_from": "2022-08-31T09:47:17Z",
"provider": "cdrn",
"product": "verifi",
"alert_type": "init-refund"
}
],
"required_products": ["oi"
],
"info": {"products": [{"product": "oi",
"status": "enrolled",
"failure_reason": "old-arn",
"date_of_enrollment": "2023-01-01T00:00:00Z",
"date_of_disenrollment": "2023-01-01T00:00:00Z"
}
]
}
}
}

Update CAID

The method to update individual CAID (Card Acceptor ID) details using a unique identifier id.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

query Parameters

include

Array of arrays

Items Value: "caid.activities"

Include the product activations.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

internal_id

string <= 500 characters

Internal ID or something else that you uses to identify your mid (field description from enrollment).

Responses

Response Schema: application/json

object

All information about retrieving individual CAID details.

This includes parameters such as system CAID ID, creation date, active status, merchant details, etc.

Request samples

Payload

Content type

application/json

{"internal_id": "caid_QWE12345"
}

Response samples

200
400
404

Content type

application/json

{"data": {"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"created_at": "2022-10-01T14:30:00Z",
"active_from": "2022-10-01T00:00:00Z",
"mcc": "5812",
"bin": "411111",
"caid": "123456789012",
"psp_name": "Stripe",
"description": "caid_QWE12345",
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
},
"activities": [{"active_from": "2022-08-31T09:47:17Z",
"provider": "cdrn",
"product": "verifi",
"alert_type": "init-refund"
}
],
"required_products": ["oi"
],
"info": {"products": [{"product": "oi",
"status": "enrolled",
"failure_reason": "old-arn",
"date_of_enrollment": "2023-01-01T00:00:00Z",
"date_of_disenrollment": "2023-01-01T00:00:00Z"
}
]
}
}
}

Disenroll product by CAID

Method to disenroll products for individual CAID (Card Acceptor ID) using a unique identifier id.

path Parameters

id

required

string <uuid>

Unique identifier for the entity.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

products

Array of strings

Items Enum: "ethoca" "rdr" "oi" "cdrn" "consumer-clarity" … 2 more

Products that are disenrolled for this CAID.

This includes the product names such as Ethoca, RDR, OI, CDRN, Consumer Clarity, Visa Dispute, and Visa Fraud.

In case of invalid status of product you will receive an error with code: validation_status_invalid and message: status must be a valid value for a product passed in request.

Responses

Response Schema: application/json

object

All information about retrieving individual CAID details.

This includes parameters such as system CAID ID, creation date, active status, merchant details, etc.

Request samples

Payload

Content type

application/json

{"products": ["oi"
]
}

Response samples

200
400
404

Content type

application/json

{"data": {"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"created_at": "2022-10-01T14:30:00Z",
"active_from": "2022-10-01T00:00:00Z",
"mcc": "5812",
"bin": "411111",
"caid": "123456789012",
"psp_name": "Stripe",
"description": "caid_QWE12345",
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
},
"activities": [{"active_from": "2022-08-31T09:47:17Z",
"provider": "cdrn",
"product": "verifi",
"alert_type": "init-refund"
}
],
"required_products": ["oi"
],
"info": {"products": [{"product": "oi",
"status": "enrolled",
"failure_reason": "old-arn",
"date_of_enrollment": "2023-01-01T00:00:00Z",
"date_of_disenrollment": "2023-01-01T00:00:00Z"
}
]
}
}
}

Get CAID list

Leveraging the API's ability to access a list of CAIDs with comprehensive filtering, sorting, and pagination options, the response can gather crucial information such as PSP identifiers, BINs, and merchant details.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

	object Set of parameters used for detailed filtering. This includes parameters such as system account IDs, merchant IDs, creation dates, update dates, statuses, etc.
	object The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.
	object Pagination to limit the number of results to help keep network traffic in check.

Responses

Response Schema: application/json

	Array of objects Information about retrieving individual CAID details. This includes parameters such as system CAID ID, creation date, active status, merchant details, etc.
	object Pagination to limit the number of results to help keep network traffic in check.

Request samples

Payload

Content type

application/json

{"filter": {"ids": ["a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"ad7h8i9j0-e3f6-7489-afcd-stuvwx9y12ef"
],
"merchant_ids": ["m123",
"n456"
],
"merchant_internal_ids": ["mid_QWE1234",
"RTY1234"
],
"created_at_from": "2022-01-01T00:00:00Z",
"created_at_to": "2022-12-31T23:59:59Z",
"updated_at_from": "2022-01-01T00:00:00Z",
"updated_at_to": "2022-12-31T23:59:59Z",
"active_from_from": "2022-01-01T00:00:00Z",
"active_from_to": "2022-12-31T23:59:59Z",
"statuses": ["active",
"pending"
],
"mccs": ["5732",
"6754"
],
"bins": ["411111",
"411312"
],
"caids": ["123456789012",
"983456787012"
],
"descriptors": ["Online Tech Store",
"Gadget World"
],
"psp_names": ["Stripe",
"Adyen"
],
"descriptions": ["caid_QWE1234",
"RTY1234"
]
},
"sort": {"field": "created_at_from",
"direction": "asc"
},
"pagination": {"limit": 100,
"offset": 0
}
}

Response samples

200
400

Content type

application/json

{"data": {"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"created_at": "2022-10-01T14:30:00Z",
"active_from": "2022-10-01T00:00:00Z",
"mcc": "5812",
"bin": "411111",
"caid": "123456789012",
"psp_name": "Stripe",
"description": "caid_QWE12345",
"merchant": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"internal_id": "mid_QWE12345",
"descriptor": "paymentdescriptor.com",
"name": "[Merchant][Descriptor]"
},
"activities": [{"active_from": "2022-08-31T09:47:17Z",
"provider": "cdrn",
"product": "verifi",
"alert_type": "init-refund"
}
],
"required_products": ["oi"
],
"info": {"products": [{"product": "oi",
"status": "enrolled",
"failure_reason": "old-arn",
"date_of_enrollment": "2023-01-01T00:00:00Z",
"date_of_disenrollment": "2023-01-01T00:00:00Z"
}
]
}
}
}

Enrollment

The API facilitates rapid merchant onboarding by enabling batch creation of import MIDs.

Enroll MID batch

This method allows enrolling a batch of MIDs, streamlining the process of registering multiple merchants or card acceptor IDs.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

Array

required_products	Array of strings This parameter specifies the products that enrolled for this CAID. ethoca
merchant_internal_id	string Internal ID or something else that is used to identify the MID (merchant).
card_acceptor_id	string Identification value used by card brands and banks to identify the location of the card acceptor terminal.
acquirer_bin	string Six-digit Bank Identification Number (BIN) issued by the merchant's bank or processor.
psp_name required	string PSP identifier for recognition.
mcc	string Setting merchant category codes.
descriptor required	string Payment descriptor.
description	string Internal ID or something else that is used to identify the MID (caid).
arns	Array of strings [ 3 .. 10 ] items [ items = 23 characters .{1}4.{21} ] Acquirer Reference Number (ARN) is a unique number assigned to a credit card transaction as it moves through the payment flow, facilitating tracking, especially in disputes, refunds, or chargebacks.

Responses

Request samples

Payload

Content type

application/json

Example

ethoca

[{"required_products": ["ethoca"
],
"merchant_internal_id": "PQR9876",
"card_acceptor_id": "998877665544",
"acquirer_bin": "789012",
"psp_name": "Stripe",
"mcc": "5732",
"descriptor": "GadgetEmperia*Purchase",
"description": "PQR9876",
"arns": ["99887766554433221100998",
"77665544332211009988777",
"66554433221100998877666"
]
}
]

Response samples

400

Content type

application/json

{"error": {"code": "validation",
"message": "Validation error",
"constraints": {"field": [{"code": "not_null",
"message": "not_null"
}
]
}
}
}

Get enrollment list

The request facilitates the retrieval of enrollment lists through flexible filtering, sorting, and pagination options. Users have the ability to paginate results and apply filters based on parameters such as statuses and descriptions.

The response contains card_acceptor_id that associated with entity from /api/v2/caids/list.

header Parameters

signature	string <= 500 characters Signature of the request allows verifying whether the request is genuine.
public_key	string <= 500 characters Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json

	object Set of parameters used for detailed filtering. This includes parameters such as merchant internal IDs, statuses, descriptions, etc.
	object Pagination to limit the number of results to help keep network traffic in check.

Responses

Response Schema: application/json

	Array of objects All information about the enrollment lists. This includes parameters such as system ID, merchant internal ID, CAID, status, required products, ARNs, etc.
	object Pagination to limit the number of results to help keep network traffic in check.

Request samples

Payload

Content type

application/json

{"filter": {"merchant_internal_ids": ["mid_QWE1234",
"RTY1234"
],
"statuses": ["new",
"success"
],
"descriptions": ["caid_QWE1234",
"RTY1234"
]
},
"pagination": {"limit": 100,
"offset": 0
}
}

Response samples

200
400

Content type

application/json

{"data": [{"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"merchant_internal_id": "mid_QWE1234",
"caid_id": "4a51f553-6ddd-4098-8550-fe1e9b477693",
"card_acceptor_id": "123456789012",
"status": "new",
"required_products": ["oi"
],
"arns": ["7234567890123456",
"9876543210987654"
],
"mcc": "5732",
"acquirer_bin": "411111",
"descriptor": "HeadphonesStore*Purchase",
"psp_name": "Stripe",
"description": "caid_ QWE1234",
"import_message": "duplicate"
}
],
"pagination": {"limit": 100,
"offset": 100,
"total_count": 999
}
}

Changelog

The changelog documents all modifications, enhancements, and removals to the API. It helps developers and users track changes, understand new features, and adjust their implementations.

It is equally important to stay informed about updates in the broader business guide changelog, which provides comprehensive details on product-level changes specific to chargeback prevention.

28 January 2025

general CAID status deprecated field; use info.products.{}.status in the responses for get CAID, get CAID list, update CAID, and disenroll products by CAID.