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, and other related details. 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

	object Contains all details related to the alert. It includes the alert publication date, amount with currency, type, and other relevant details.
	object Contains data associated with the alert transaction, used to match the alert to the transaction. It includes the transaction creation date, amount with currency, transaction type, and other relevant information.
	object Contains all details related to the Merchant Identification (MID). It includes the merchant's unique identifier, internal ID, payment descriptor, and other relevant information.

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 response codes. Required to promptly send a valid response when receiving a webhook alert. Only the initial response is accepted unless set to `pending`. No changes are allowed after submission.
	object Contains all details related to the order. It includes the order ID, creation date, amount with currency, and other relevant information.
	object Contains all details related to the customer. It includes the customer ID, personal data, device information, and other relevant details.
	Array of objects Contains all details related to the transactions. It includes the order ID, creation date, amount with currency, and other relevant information.
	Array of objects Contains all details about the purchased products. It includes the product name, SKU, description, and other relevant information.
	object Contains all details related to the merchant. It includes the merchant's payment terms, refund policy, warranty terms, and other relevant information.

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 response codes. Required to promptly provide a valid response upon receiving a webhook alert, 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

Contains detailed information about a specific alert.

It includes 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. It includes parameters such as system account IDs, merchant IDs, transaction IDs, alert dates, and other relevant details.
	object Contains parameters used for sorting. Once indexed, you can select the 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 Contains detailed information about a specific alert. It includes 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",
"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

	object Contains all details related to the alert. It includes the alert publication date, amount with currency, type, and other relevant details.
	object Contains data associated with the alert transaction, used to match the alert to the transaction. It includes the transaction creation date, amount with currency, transaction type, and other relevant information.
	object Contains all details related to the Merchant Identification (MID). It includes the merchant's unique identifier, internal ID, payment descriptor, and other relevant information.

Responses

Response Schema: application/json

One of

outcome required	string Default: "acknowledged" Standard response codes.
	object Contains all details related to the order. It includes the order ID, creation date, amount with currency, and other relevant information.
required	object Contains all details related to the customer. It includes the customer ID, personal data, device information, and other relevant details.
	Array of objects Contains all information about the related transactions. It includes the transaction ID, creation date, amount, currency, and other relevant details.
required	Array of objects Contains all details about the purchased products. It includes the product name, SKU, description, and other relevant information.
	object `Cardholder/Issuer Experience` Contains information about the merchant, including their contacts, policies, and more, which can be provided by default during MID enrollment. If the merchant does not transmit these parameters, Chargebackhit will send them 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

Contains all details related to the Merchant Identification (MID).

It includes the merchant's unique identifier, internal ID, payment descriptor, and other relevant information.

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

Contains all details related to the Merchant Identification (MID).

It includes the merchant's unique identifier, internal ID, payment descriptor, and other relevant information.

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. It includes parameters such as system account IDs, internal IDs, payment descriptors, and other relevant details.
	object Contains parameters used for sorting. Once indexed, you can select the 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 Contains all details related to the Merchant Identification (MID). It includes the merchant's unique identifier, internal ID, payment descriptor, and other relevant information.
	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": "name",
"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

Contains information about retrieving individual CAID details.

It includes parameters such as system CAID ID, creation date, active status, and merchant details.

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

Contains information about retrieving individual CAID details.

It includes parameters such as system CAID ID, creation date, active status, and merchant details.

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 disenrolled for the CAID.

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

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

Responses

Response Schema: application/json

object

Contains information about retrieving individual CAID details.

It includes parameters such as system CAID ID, creation date, active status, and merchant details.

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

This method retrieves a list of CAIDs with filtering, sorting, and pagination options, providing key details such as PSP identifiers, BINs, and merchant 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. It includes parameters such as system account IDs, merchant IDs, creation dates, update dates, statuses, and other relevant details.
	object Contains parameters used for sorting. Once indexed, you can select the 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 Contains information about retrieving individual CAID details. It includes parameters such as system CAID ID, creation date, active status, and merchant details.
	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",
"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, optimizing 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 Specifies the products enrolled for the 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 Numbers (ARNs) are unique numbers assigned to credit card transactions as they move through the payment flow. ARN helps track transactions, 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 retrieves enrollment lists with filtering, sorting, and pagination options. You can paginate results and filter by status, description, and other parameters.

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. It includes parameters such as merchant internal IDs, statuses, descriptions, and other relevant details.
	object Contains the `direction` parameter used for sorting. Once indexed, you can sort the results.
	object Pagination to limit the number of results to help keep network traffic in check.

Responses

Response Schema: application/json

	Array of objects Contains all details about the enrollment lists. It includes parameters such as system ID, merchant internal ID, CAID, status, required products, ARNs, and other related data.
	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"
]
},
"sort": {"direction": "asc"
},
"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.