Skip to main content

Documentation

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'
-d '{
    "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
    }
}