Create Chargeback

Create a new chargeback record against a specific transaction.

POSThttps://api.zenpayz.com/merchant/api/v1/chargebacks

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation
Content-Type REQUIRED	application/json
X-Merchant-Id REQUIRED	Merchant identifier
X-Request-Id REQUIRED	Unique request identifier

Body Parameters

Parameter	Type	Description
transactionId REQUIRED	string	ID of the original transaction being disputed
amount REQUIRED	number	Chargeback amount
currency REQUIRED	string	ISO 4217 currency code
reason REQUIRED	string	Reason for the chargeback
source REQUIRED	string	Source of the chargeback (e.g. card_network, customer, bank)
reasonCode OPTIONAL	string	Standard reason code from the card network
reasonDescription OPTIONAL	string	Detailed description of the reason
externalChargebackId OPTIONAL	string	External chargeback identifier from the payment network
disputeDeadline OPTIONAL	string	Deadline to respond to the dispute (ISO 8601)
evidenceDeadline OPTIONAL	string	Deadline to submit evidence (ISO 8601)
priority OPTIONAL	string	Priority level: low, medium, high, urgent

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "chargebackId": "cb_a1b2c3d4e5f6g7h8",
    "transactionId": "txn_f8e7d6c5b4a39281",
    "amount": 150.00,
    "currency": "USD",
    "reason": "fraudulent",
    "source": "card_network",
    "reasonCode": "10.4",
    "reasonDescription": "Other Fraud - Card-Absent Environment",
    "externalChargebackId": "ext_cb_12345",
    "status": "initiated",
    "outcome": "pending",
    "priority": "high",
    "disputeDeadline": "2024-02-15T23:59:59.000Z",
    "evidenceDeadline": "2024-02-10T23:59:59.000Z",
    "evidence": [],
    "merchantResponse": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Chargeback created successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processing_time_ms": 45,
    "api_version": "v1",
    "endpoint": "POST /chargebacks",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid request parameters
UNAUTHORIZED	401	Invalid API key
TRANSACTION_NOT_FOUND	404	Referenced transaction does not exist
DUPLICATE_CHARGEBACK	409	A chargeback already exists for this transaction

Examples

cURL

curl -X POST https://api.zenpayz.com/merchant/api/v1/chargebacks \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: merch_xxxxx" \
  -H "X-Request-Id: req_xxxxx" \
  -d '{
    "transactionId": "txn_f8e7d6c5b4a39281",
    "amount": 150.00,
    "currency": "USD",
    "reason": "fraudulent",
    "source": "card_network",
    "reasonCode": "10.4",
    "priority": "high",
    "disputeDeadline": "2024-02-15T23:59:59.000Z",
    "evidenceDeadline": "2024-02-10T23:59:59.000Z"
  }'

JavaScript

const response = await fetch('https://api.zenpayz.com/merchant/api/v1/chargebacks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
    'X-Merchant-Id': merchantId,
    'X-Request-Id': requestId,
  },
  body: JSON.stringify({
    transactionId: 'txn_f8e7d6c5b4a39281',
    amount: 150.00,
    currency: 'USD',
    reason: 'fraudulent',
    source: 'card_network',
    reasonCode: '10.4',
    priority: 'high',
    disputeDeadline: '2024-02-15T23:59:59.000Z',
    evidenceDeadline: '2024-02-10T23:59:59.000Z',
  }),
});

const result = await response.json();
console.log(result.data.chargebackId); // cb_a1b2c3d4e5f6g7h8

SDK

const chargeback = await zenpays.chargebacks.create({
  transactionId: 'txn_f8e7d6c5b4a39281',
  amount: 150.00,
  currency: 'USD',
  reason: 'fraudulent',
  source: 'card_network',
  reasonCode: '10.4',
  priority: 'high',
  disputeDeadline: '2024-02-15T23:59:59.000Z',
  evidenceDeadline: '2024-02-10T23:59:59.000Z',
});

console.log(chargeback.chargebackId); // cb_a1b2c3d4e5f6g7h8

Related Endpoints

• List Chargebacks
• Get Chargeback
• Submit Evidence
• Add Response