Sandbox Chargeback Testing

Warning: This testing scenario is only available for users for Facilitators.

Referrers and Merchants are currently unable to create their own “test” chargebacks in the Sandbox environment.

Tip: To create a “test” chargeback for a specific transaction in the sandbox contact the Payrix Implementations Team with your Transaction ID and preferred Chargeback Cycle/Dispute Status.

To better understand different Chargeback statuses, Dispute stages, and response options in real-time, we offer a Chargeback simulation option that allows the user to create a new Chargeback Dispute to simulate what a real Chargeback dispute might look like.

This can be incredibly useful for testing your Chargebacks web alerts, previewing what the Dispute looks like, and how to respond to each type of reason code before being put under pressure to respond in a fixed time frame in a normal Chargeback process.

Before You Begin

Before getting started, we recommend reviewing the Dispute Management section for Disputes, Chargeback, reason codes, and handling steps to familiarize yourself with the different Chargeback process cycles, Dispute stages, major card brand dispute reason codes, and other information that can help you better understand each action and result.

Tip: You can also initiate a chargeback using a Transaction Testing Trigger amount of $5,000.00 in the Sandbox environment to trigger a chargeback dispute message only.

Initiate a new Chargeback Dispute for Testing

Follow the steps below to create a new chargeback to dispute a transaction for testing purposes:

Step 1: Create or locate an existing transaction

In the sandbox environment, you can utilize an existing transaction by copying its id value or create a transaction to generate a new transaction id value for the next step.

Retrieve or Create a Transaction for its Transaction ID.

Retrieve all Transactions - HTTP Request

CODE

GET /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com

Retrieve all Transactions - Example Response Body

CODE

{
  "response": {
    "data": [
      {
        "id": "p1_txn_5a1ef5e55658ea5275a3ec0",
        "created": "2023-10-23T16:08:40.884Z",
        "modified": "2023-10-23T16:08:40.884Z",
        "creator": "string",
        "modifier": "string",
        "ipCreated": "string",
        "ipModified": "string",
        "merchant": "string",
        "token": "string",
        "payment": {
          "method": 0,
          "number": "string",
          "routing": "string"
        },
      ],
    "details": {
      "requestId": "string",
      "page": {
        "current": 0,
        "last": 0
      }
    }
  }
}

Parameter	Type	Description
id	string	The transaction ID.
created	string	The date and time the transaction was created. Format: `YYYY-MM-DDTHH:MM:SS.MSZ` Note: “T” and “Z” are not variables and will not change.
modified	string	The date and time the transaction was last modified. Format: `YYYY-MM-DDTHH:MM:SS.MSZ` Note: “T” and “Z” are not variables and will not change.
creator	string	The login ID for the Merchant user that created the transaction.
modifier	string	The login ID for the Merchant user that last modified the transaction.
ipCreated	string	The incoming IP address from which this Transaction was created.
ipModified	string	The incoming ip address from which this Transaction was last modified.
merchant	string	The Merchant ID for the Merchant entity that processed the Transaction.
token	string	The Payment token used in the transaction (if applicable).
payment	object	An object containing the Payment Method Type, Number, and additional applicable information, such as routing number or expiration. Values will vary depending on payment method chosen.

Create a new Transaction - HTTP Request

CODE

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com

Create a new Transaction (Credit Card) - Example Request Body

CODE

{
  "allowPartial": "0",
  "debtRepayment": "0",
  "origin": 2,
  "platform": "VANTIV",
  "type": 1,
  "unauthReason": "incomplete",
  "currency": "USD",
  "fundingCurrency": "USD",
  "swiped": "0",
  "pin": "0",
  "signature": "0",
  "unattended": "0",
  "payment": {
    "method": 2,
    "number": "4111111111111111",
    "cvv": "111"
  },
  "merchant": "p1_mer_5a1ef5e55656a739a85da21",
  "expiration": "0120",
  "total": 100
}

Parameter		Type	Required	Description
allowPartial		integer	Required	Whether or not to allow partial amount authorizations of this Transaction. Valid Values: `0` - Partial amount authorizations are not allowed. `1` - Partial amount authorizations are allowed. Example: A processor’s set limit for transaction authorizations is $750, but the transaction amount is for $1,000. Enabling this parameter will partially authorize the transaction up to $750.
debtRepayment		integer	Required	Whether or not this transaction is for debt repayment. Valid Values: `0` - Not for Debt Repayment. `1` - For Debt Repayment.
origin		integer	Required	The payment acceptance method that resulted in the transaction. Valid Values: `1` - Originated at a credit card terminal. `2` - Originated through an eCommerce system. `3` - Originated as a mail order or telephone order transaction. `4` - Originated with Apple Pay. `5` - Originated as a Successful 3D Secure transaction. `6` - Originated as an Attempted 3D Secure transaction. `7` - Originated as a recurring transaction on the card. `8` - Originated in a PayFrame.
platform		string	Required	The platform used to process this Transaction. Valid Values: `APPLE` - The Apple Pay processor `ELAVON`: The Elavon processor `FIRSTDATA`: The First Data processor `GOOGLE` - The Google Pay processor `VANTIV`: The WorldPay (aka Vantiv or Litle) eComm (aka VAP) processor `VCORE`: The WorldPay (aka Vantiv) Core processor `WELLSACH` - The Wells Fargo eCheck processor `WELLSFARGO`: The Wells Fargo Merchant Services processor `WFSINGLE` - The Wells Fargo processor
type		integer	Required	The type of transaction. Valid Values: `1` - Credit Card Only: Sale Transaction. Processes a sale and charges the customer. `2` - Credit Card Only: Auth Transaction. Authorizes and holds the requested total on the credit card. `3` - Credit Card Only: Capture Transaction. Finalizes a prior Auth Transaction and charges the customer. `4` - Credit Card Only: Reverse Authorization. Reverses a prior Auth or Sale Transaction and releases the credit hold. `5` - Credit Card Only: Refund Transaction. Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund). `7` - Echeck Only: Echeck Sale Transaction. Sale Transaction for ECheck payment. `8` - Echeck Only: ECheck Refund Transaction. Refund Transaction for prior ECheck Sale Transaction. `11` - Echeck Only: Echeck Redeposit Transaction. Attempt to redeposit a prior failed eCheck Sale Transaction. `12` - Echeck Only: Echeck Account Verification Transaction. Attempt to verify eCheck payment details
unauthReason		string	Required	The reason for the auth reversal. Valid Values: `customerCancelled` - Transaction Cancelled by Customer. (Default) `incomplete` - Transaction Incomplete. `timeout` - Transaction Timeout. `clerkCancelled` - Transaction Cancelled by Clerk. `misdispense` - Misdispense. `hardwareFailure` - Hardware Failure. `suspectedFraud` - Suspected Fraud.
currency			Required	The three-digit customer currency code for the currency used in the transaction. The default is `USD`.
fundingCurrency			Required	The three-digit customer currency code for the currency type used by the Merchant’s account. The default is `USD`.
swiped		integer	Required	Whether the card was swiped during this Transaction. Valid Values: `0` - Not swiped `1` - Swiped Note: This field is set to `1` automatically if track data was received.
pin		integer	Required	Whether this Transaction was verified with a PIN. Valid Values: `0` - No PIN verification `1` - PIN verification
signature		integer	Required	Whether a signature was captured during this Transaction. Valid Values: `0` - Not captured `1` - Captured
unattended		integer	Required	Whether the card was swiped at an unattended terminal during this Transaction. Valid Values: `0` - Attended terminal `1` - Unattended terminal The default is `0` .
payment		object	Required	An object containing the Payment Method Type, Number, and additional applicable information, such as routing number or expiration. Values will vary depending on payment method chosen.
	method	integer	Required	The type of payment method used for a transaction. Valid Values: `0` - Unknown Payment Method `1` - American Express `2` - Visa `3` - MasterCard `4` - Diners Club `5` - Discover `6` - PayPal `7` - Debit card `8` - Checking account `9` - Savings account `10` - Corporate checking account `11` - Corporate savings account `12` - Gift card `13` - EBT (Electronic Benefits Transfer) Card `14` - WIC (Women, Infants and Children) Card
	number	string	Required	The card number.
	cvv	string	Required	The CVV security code shown on the back of the card.
merchant		string	Required	The Merchant ID for the Merchant entity that processed the Transaction.
expiration		string	Required	The month and year expiration shown on the credit card. Format: `MMYY`
total		string		The total transaction amount. Format: `100` = $1.00

Create a new Transaction - Example Response Body

CODE

{
  "payment": {
    ...
  },
  "id": "p1_txn_5a1ef5e55658ea5275a3ec0",
  ...
}

Parameter	Type	Description
`id`	string	The Transaction ID.

Note: There are other parameters available and shown in the response. We will be skipping over them here for the sake of the use case.

Step 2: Create a Chargeback

Using the following endpoint, create a chargeback using the transaction id value from Step 1 as the txn parameter value in the request body below.

Warning: It can take up to 60 seconds for the new chargeback to be fully created and appear on the platform server for Step 3.

Create a Chargeback with the Transaction ID.

HTTP Request

CODE

POST /chargebacks HTTP/1.1
Accept: application/json
Host: apiv2.payrix.com
APIKEY:{{private_api_key}}

Example Request Body

JSON

{ 
  "txn":"t1_txn_5e176fe5465e35613e96ddf"
}

Parameter	Type	Required	Description
`txn`	string	Required	The Transaction ID for the payment being disputed. Warning: The transaction must be in a settled state to be considered valid. If the transaction used here is not settled, you must set `forceSettle` to `true`.

You can optionally add additional parameters (shown below) to the request to make the response and chargeback creation more realistic.

Example Response Body

JSON

{
    "status": "success",
    "data": {
        "id": 3,
        "created": "2020-01-08T23:27:46.460Z",
        "processed": null,
        "txn": "t1_txn_5e176fe5465e35613e96ddf",
        "cycle": "first",
        "status": "open",
        "amount": 1200,
        "reason_code": "10.4",
        "reason_code_desc": "Allocation Flow - Fraud - Card Absent Environment"
    }
}

Parameter	Type	Description
`id`	string	The new Chargeback ID.
`created`	string	The date and time that the Chargeback was created. Format: `YYYY-MM-DDTHH:MM:SS.MSZ` Note: “T” and “Z” are not variables and will not change.
`processed`	string	The Chargeback amount that has been processed and debited from the Merchant’s balance. Default is `null`
`txn`	string	The Transaction ID for the payment being disputed. Warning: The transaction must be in a settled state to be considered valid. If the transaction used here is not settled, you must set `forceSettle` to `true`.
`cycle`	string	The current chargeback process cycle. Valid Values: `retrieval` - Retrieval Cycle / Dispute Stage `first` - First Chargeback Dispute Stage (Default) `pre-arbitration` - Pre-Arbitration Dispute Stage `arbitration` - Arbitration Dispute Stage `reversal` - Transaction Reversal back to Merchant.
`status`	string	The overall chargeback process status. Valid Values: `open` - The Chargeback is open. `won` - The Chargeback was lost. `lost` - The Chargeback was won.
`amount`	string	The amount being disputed in the Chargeback. The Default is the full transaction amount (i.e. full chargeback) in basis points format. Example: `10000` = $100.00 For partial chargebacks, provide an amount value less than the full transaction amount.
`reason_code`	string	The reason code supporting the chargeback. The default value is `10.4` See Handing Specific Dispute Types for a full list of Major Card Brand Chargeback Codes and their Valid Values.
`reason_code_desc`	string	The description associated with the chargeback reason code provided. The default value is `Allocation Flow - Fraud - Card Absent Environment` See Handing Specific Dispute Types for a full list of Major Card Brand Chargeback Code Descriptions and their Valid Values.

Optional Request Parameters

Parameter	Type	Required	Description
`txn`	string	Required	The Transaction ID for the payment being disputed. Warning: The transaction must be in a settled state to be considered valid. If the transaction used here is not settled, you must set `forceSettle` to `true`.
`cycle`	string	Optional	The current chargeback process cycle. Valid Values: `retrieval` - Retrieval Cycle / Dispute Stage `first` - First Chargeback Dispute Stage (Default) `pre-arbitration` - Pre-Arbitration Dispute Stage `arbitration` - Arbitration Dispute Stage `reversal` - Transaction Reversal back to Merchant.
`status`	string	Optional	The overall chargeback process status. Valid Values: `open` - The Chargeback is open. `won` - The Chargeback was lost. `lost` - The Chargeback was won.
`amount`	string	Optional	The amount being disputed in the Chargeback. The Default is the full transaction amount (i.e. full chargeback) in basis points format. Example: `10000` = $100.00 For partial chargebacks, provide an amount value less than the full transaction amount.
`reason_code`	string	Optional	The reason code supporting the chargeback. The default value is `10.4` See Handing Specific Dispute Types for a full list of Major Card Brand Chargeback Codes and their Valid Values.
`reason_code_desc`	string	Optional	The description associated with the chargeback reason code provided. The default value is `Allocation Flow - Fraud - Card Absent Environment` See Handing Specific Dispute Types for a full list of Major Card Brand Chargeback Code Descriptions and their Valid Values.
`forceSettle`	integer	Optional	Whether or not force the transaction to settle if it is still processing. Valid Values: `true` - Force the transaction to settle immediately. `false` - Do not force the transaction to settle. Warning: If the transaction used in this request is not settled, you must set `forceSettle` to `true`.

Additional Info JSON Request Body Example

CODE

{
  "txn": "t1_txn_5e176fe5465e35613e96ddf",
  "cycle": "first",
  "status": "open",
  "amount": 1200,
  "reason_code": "10.4",
  "reason_code_desc": "Allocation Flow - Fraud - Card Absent Environment",
  "forceSettle": true
}

Step 3: Monitor the Chargeback and Respond

Using the steps available in the Respond to Chargeback Dispute using the API article, view the Chargeback and respond accordingly with additional API requests.

You can also monitor and respond to the Chargeback as needed from the Portal view. Click here to read the applicable guide.