Versions Compared

Old Version 2

changes.mady.by.user Miles Graves

Saved on

compared with

New Version Current

changes.mady.by.user Miles Graves

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt

How To - Use this guide provides step-by-step instructions on how to use the API to submit a refund or void transaction using the Payrix API as a Payrix Partner.

Cancel vs Refund vs Void

A refund, cancel or void transaction request can be submitted via the API using the /txns endpoint. You can look up additional information about the /txns endpoint see more information in theAPI Reference guide.

Submitting a Refund or Void a Payment via the API

The process of submitting a card payment (sale) refund, an eCheck refund, or voiding an approved transaction is virtually the same. The only difference between these three options is the type value included in the request.

A refund can be issued when the transaction status is “3” (captured) or “4” (settled), but payments with these statuses cannot be voided or canceled. A payment can only be voided or canceled if the transaction status is “1” (approved).

All API transaction statuses:

...

Refund a Card Payment via the API

A partial or full refund/void is submitted in the API by sending .

Cancel

Void

Refund

Removes the approved payment from the Merchant’s daily batch, but does not reverse the authorization.

Removes the approved payment from the Merchant’s daily batch AND reverses the authorization.

Refunds a prior Capture or Sale Transaction, total may be specified for a partial refund.

Transaction Type: 4

Transaction Type: 4

Transaction Type: 5 or 8

Transaction Status Code: 1

Transaction Status Code: 1

Transaction Status Code: 3 or 4

Must be done before batching.

Must be done before batching.

May be done anytime.

Info

About Refund Timeframes

All transactions may be voided before they are batched. If the transaction has already been batched (frequency dependent on Referrer configuration), it will required a refund.

  • Note that there is no technical time limit on when a refund can be issued after a transaction has already been batched. The only limit is the refund policy of individual merchants.

For more info on Transaction Type see the expandable content below:

Transaction Types

Expand
titleTransaction Types Description

Transaction Type

Transaction Code

Note

Reverse Authorization

4

Credit Card Only.

Reverses a prior Auth or Sale Transaction and releases the credit hold.

Refund Transaction

5

Credit Card Only.

Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund).

eCheck Refund Transaction

8

Echeck Only:

Refund Transaction for prior ECheck Sale Transaction.

Transaction Statuses

Expand
titleTransaction Statuses Description

Transaction Status

Status Code

Note

Pending

0

Approved

1

Payments can be voided or cancelled.

Failed

2

Captured

3

Payments can be refunded.

Settled

4

Payments can be refunded.

Returned

5

Payment has been successfully refunded.

...

Refund Payments via the API

Getting Started

Step 1: Check the desired refund payment’s transaction status - 3 for Captured or 4 for Settled.

Step 2: Enter required parameters to the request body

  • fortxn-The Payrix Transaction ID (TXN ID) of the original payment to refunded

  • type - 5 = Card Payments or 8 = eChecks (ACH).

When finished, send the request body in a POST request to the /txns endpoint and including the Transaction ID of the payment that is being refunded/voided. By default, if no amount is set when submitting a refund/void via the API it will be a full refund for the entire amount of the original transaction (excluding .

See examples below of different payment refund use cases after setup:

Refund a Full Card Payment

Unless specified, refunds without amounts listed will be treated as a refund of the entire transaction amount.

  • Note: Full refunds exclude any funds that have been previously partially refunded).

Code Block
{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "5"
}

Refund a Partial Card Payment

You can enter specify a partial amount to be refunded (amount values by using the optionaltotal parameter.

Values are in cents USD - in the code snippet below a .

  • Example: $1.00

...

  • = 100, $100 = 10000, etc.

Code Block
{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "5",
    "total": "100"
}

At a minimum, the only fields required to submit a refund/void are:

...

type - In the case of a card payment refund this field should be set with the value “5”.
...
Refund an eCheck Payment
...
For eCheck refunds, the type field should be set to “8”. Additionally, you must submit the customer’s (whom you are sending the eCheck refund to) first namefirst name of the receiving/refunded customer under a first parameter. 
 Code Block
{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "58",
    "first": "John"
    "total": "100"
}
...
Void 
...
Payments via the API
...
To void an approved (but not captured/settled) payment, the type should be set to “4”.
Getting Started
Step 1: Check the desired payment’s transaction status is:1 for Captured 
Step 2: Enter required parameters to the request body: 
  • fortxn-The Payrix Transaction ID (TXN ID)of the original payment to voided.
  • type - 4 = Card Payments.
When finished, send the request body in a POST request to the /txns endpoint.
Void a Payment
 Code Block
{
    "fortxn": "t1_txn_5f1841b4b1200ea4d1af843",
    "type": "4"
}
...
...
Cancel an approved payment via the API
 Info
cancel payment vs. void payment:
  • cancel -  Removes the approved payment from the Merchant’s daily batch, but does not reverse the authorization. 
  • void - Removes the approved payment from the Merchant’s daily batch AND reverses the authorization.
...
Getting Started
Step 1: Check the desired payment’s transaction status is:1 for Captured 
Step 2: Enter required parameters to the request body: 
  • batch-null
Step 3: Add the following path parameter:
  • {txn_ID} - The Payrix Transaction ID (TXN ID) of the original payment to cancelled.
When finished, send the request body in a PUT request to the /txnsendpoint and include the relevant Payrix Transaction ID (TXN ID) in the request string (i.e. PUT/txns//{txn_ID). In the code body, simply send a request to nullify the batch associated with the approved payment.} endpoint.
Cancel a Payment
 Code Block
{
    "batch": null
}
...