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 all Transactions - HTTP Request

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

Retrieve all Transactions - Example Response Body

{ "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

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

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

Parameter

Type

Required

Description

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

Parameter

Type

Description

Parameter

Type

Description

id

string

The Transaction ID.

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.

HTTP Request

Example Request Body

Parameter

Type

Required

Description

Parameter

Type

Required

Description

txn

string

Required

The Transaction ID for the payment being disputed.

Example Response Body

Parameter

Type

Description

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.

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

Parameter

Type

Required

Description

txn

string

Required

The Transaction ID for the payment being disputed.

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.

Additional Info JSON Request Body Example

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.