Simulating Cardholder Disputes
You can simulate cardholder disputes in the sandbox.
Create a payment using a specific, reserved card number. Set payment_method_options.3d_required to false. See Create Payment.
The following asynchronous webhooks provide information about the dispute object:
Reserved Card Numbers
To simulate a specific type of dispute, use one of the following card numbers in the payment_method object of the Create Payment request:
Card Number | Type of Cardholder Dispute |
|---|---|
4539922288211219 | Goods or services not provided. |
4556028624137080 | Subscription canceled. |
4556942399248726 | Counterfeit merchandise. |
5374500863109043 | Credit not processed. |
5132803130357186 | Cardholder dispute - miscellaneous. |
Example Disputed Transaction Request
curl -X post 'https://sandboxapi.rapyd.net/v1/payments/' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
"amount": 26.49,
"currency": "USD",
"merchant_reference_id": "0426202214",
"payment_method": {
"type": "is_visa_card",
"fields": {
"number": "4539922288211219",
"expiration_month": "11",
"expiration_year": "29",
"cvv": "123",
"name": "John Doe"
}
},
"ewallets": [
{
"ewallet": "ewallet_e67c8ad63200d781470a04107fbd7c59",
"percentage": 100
}
],
"metadata": {
"merchant_defined": "created"
},
"capture": true,
"payment_method_options": {
"3d_required": false
}
}'Example Disputed Transaction Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "068a6722-1d5e-4175-bbb4-405acf8409ee"
},
"data": {
"id": "payment_3961cadf5fd7deda16a4d35dc6b5b9de",
"amount": 26.49,
"original_amount": 26.49,
"is_partial": false,
"currency_code": "USD",
"country_code": "IS",
"status": "CLO",
"description": "",
"merchant_reference_id": "0426202214",
"customer_token": "cus_6d2c342e1ed1c44fc23ff685f68f9d23",
"payment_method": null,
"payment_method_data": {
"id": null,
"type": "is_visa_card",
"category": "card",
"metadata": null,
"image": "",
"webhook_url": "",
"supporting_documentation": "",
"next_action": "not_applicable",
"name": "John Doe",
"last4": "1219",
"acs_check": "unchecked",
"cvv_check": "unchecked",
"bin_details": {
"type": "CREDIT",
"brand": "VISA",
"level": "GOLD",
"issuer": "UNION BANK OF INDIA",
"country": "IN",
"bin_number": "453992"
},
"expiration_year": "29",
"expiration_month": "11",
"fingerprint_token": "ocfp_f63d2a47a4ccca8613e8b00dc481d461",
"network_reference_id": "123456",
"payment_account_reference": "V001HTBU7TAUCDEJEYTS6L8914YUE"
},
"auth_code": null,
"expiration": 1752656505,
"captured": true,
"refunded": false,
"refunded_amount": 0,
"receipt_email": "",
"redirect_url": "",
"complete_payment_url": "",
"error_payment_url": "",
"receipt_number": "",
"flow_type": "",
"address": null,
"statement_descriptor": "Doc Team",
"transaction_id": "",
"created_at": 1752051705,
"metadata": {
"merchant_defined": "created"
},
"failure_code": "",
"failure_message": "",
"paid": true,
"paid_at": 1752051705,
"dispute": {
"id": "5771ee12-ec84-41d9-8c36-3c016a1d8856",
"token": "dispute_61c346fada6c8f9043f4ddf2ea33be53",
"status": "ACT",
"amount": 26.49,
"currency": "USD",
"dispute_category": "Cardholder Dispute",
"dispute_reason_description": "Goods or Services Not Provided",
"original_transaction_currency": "USD",
"original_transaction_amount": 26.49,
"original_dispute_amount": 26.49,
"original_dispute_currency": "USD",
"original_transaction_id": "payment_3961cadf5fd7deda16a4d35dc6b5b9de",
"ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59",
"central_processing_date": 1752051705,
"created_at": 1752051705,
"updated_at": 1752051705,
"due_date": 1752829305,
"payment_method": "card_f97fb7ebd1519e126a2927f957ad6f6c",
"payment_method_data": {
"id": "card_f97fb7ebd1519e126a2927f957ad6f6c",
"type": "is_visa_card",
"category": "card",
"metadata": null,
"image": "",
"webhook_url": "",
"supporting_documentation": "",
"next_action": "not_applicable",
"name": "John Doe",
"last4": "1219",
"acs_check": "unchecked",
"cvv_check": "unchecked",
"bin_details": {
"type": "CREDIT",
"brand": "VISA",
"level": "GOLD",
"issuer": "UNION BANK OF INDIA",
"country": "IN",
"bin_number": "453992"
},
"expiration_year": "29",
"expiration_month": "11",
"fingerprint_token": "ocfp_f63d2a47a4ccca8613e8b00dc481d461"
},
"rate": 0,
"evidence": null,
"evidence_reason_code": null,
"pre_dispute": false,
"arn": null,
"claim_id": null
},
"refunds": null,
"order": null,
"outcome": null,
"visual_codes": {},
"textual_codes": {},
"instructions": [
{
"name": "instructions",
"steps": [
{
"step1": ""
}
]
}
],
"ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59",
"ewallets": [
{
"ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59",
"amount": 26.49,
"percent": 100,
"refunded_amount": 0
}
],
"payment_method_options": {
"3d_required": false
},
"payment_method_type": "is_visa_card",
"payment_method_type_category": "card",
"fx_rate": 1,
"merchant_requested_currency": null,
"merchant_requested_amount": null,
"fixed_side": "",
"payment_fees": null,
"invoice": "",
"escrow": null,
"group_payment": "",
"cancel_reason": null,
"initiation_type": "customer_present",
"mid": "",
"next_action": "not_applicable",
"error_code": "",
"remitter_information": {},
"save_payment_method": false,
"merchant_advice_code": null,
"merchant_advice_message": null,
"transaction_link_id": null
}
}