Running an Independent Refund

Scenario	Merchant uses the POS to:
Customer bought a hat for $15 and wants to return it. They don't have a receipt for the sale.	Run an independent refund to return $15 to the customer's account.

Scenario

Merchant uses the POS to:

Customer bought a hat for $15 and wants to return it. They don't have a receipt for the sale.

Run an independent refund to return $15 to the customer's account.

Environment	URL
Test	https://api.pit.paygateway.com/transactions/cardpresent/returns
Production	https://api.paygateway.com/transactions/cardpresent/returns

Environment

URL

Test

https://api.pit.paygateway.com/transactions/cardpresent/returns

Production

https://api.paygateway.com/transactions/cardpresent/returns

Object	Parameter	Type	Size	Required?	Description
N/A	reference_id	String	1-50	Required	Unique identifier for the refund. This is an alphanumeric value that the merchant creates, for example, `XAZR863990.`
receipt	clerk_id	String	1-20	Optional	Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, `A1090-John Doe.`
transaction	keyed_entry_mode	String	Explicit	Optional	Indicates if the payment terminal allows the user to enter the card details using the keypad. Send one of the following values: • `default` - Payment terminal uses only keyed entry. • `allowed` - Payment terminal can accept keyed entry and displays it as an option on the payment selection screen. Note: If you don't send a value, the payment terminal doesn't display keyed entry as an option on the payment selection screen.
country_code	String	Explicit	Required	ISO code for the country where the refund originates. For a list of possible values, see the country code enumeration.
language	String	Explicit	Optional	Language for the text that displays on the device and receipts. For a list of possible values, see the language enumeration.
processing_indicators	Object	N/A	Optional	Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.
terminal	Object	N/A	Optional	Object that includes information to identify the payment terminal. For a list of parameters, see the terminal object.
payment	amount	String	1-10	Required	Total dollar amount that you are returning to the customer's account. the value includes two decimal places, for example, `10.00`.
currency_code	String	Explicit	Required	ISO currency code for the refund. For a list of possible values, see the currency code enumeration.
invoice_number	String	1-8	Required	Alphanumeric invoice number or order number that the merchant creates and assigns to the refund.

Object

Parameter

Type

Size

Required?

Description

N/A

reference_id

String

1-50

Required

Unique identifier for the refund. This is an alphanumeric value that the merchant creates, for example, XAZR863990.

receipt

clerk_id

String

1-20

Optional

Clerk ID that the merchant wants to display on the receipt. This is an alphanumeric value that the merchant assigns to a clerk, for example, A1090-John Doe.

transaction

keyed_entry_mode

String

Explicit

Optional

Indicates if the payment terminal allows the user to enter the card details using the keypad. Send one of the following values:
• default - Payment terminal uses only keyed entry.
• allowed - Payment terminal can accept keyed entry and displays it as an option on the payment selection screen.
Note: If you don't send a value, the payment terminal doesn't display keyed entry as an option on the payment selection screen.

country_code

String

Explicit

Required

ISO code for the country where the refund originates. For a list of possible values, see the country code enumeration.

language

String

Explicit

Optional

Language for the text that displays on the device and receipts. For a list of possible values, see the language enumeration.

processing_indicators

Object

N/A

Optional

Object that includes options for additional actions. For a list of parameters, see the processing_indicators object.

terminal

Object

N/A

Optional

Object that includes information to identify the payment terminal. For a list of parameters, see the terminal object.

payment

amount

String

1-10

Required

Total dollar amount that you are returning to the customer's account. the value includes two decimal places, for example, 10.00.

currency_code

String

Explicit

Required

ISO currency code for the refund. For a list of possible values, see the currency code enumeration.

invoice_number

String

1-8

Required

Alphanumeric invoice number or order number that the merchant creates and assigns to the refund.

Parameter	Type	Size	Required?	Description
allow_duplicate	Boolean	Explicit	Optional	If set to `true`, you can send duplicate transactions. The default time frame to block duplicate transactions is 15 minutes.

Parameter

Type

Size

Required?

Description

allow_duplicate

Boolean

Explicit

Optional

If set to true, you can send duplicate transactions. The default time frame to block duplicate transactions is 15 minutes.

Parameter	Type	Size	Required?	Description
terminal_id	String	8-10	Optional	Unique numeric value that we assign to the payment terminal, for example, `90030234`.

Parameter

Type

Size

Required?

Description

terminal_id

String

8-10

Optional

Unique numeric value that we assign to the payment terminal, for example, 90030234.

Object	Field	Type	Description
N/A	invoice_number	String	Invoice number for the refund.
N/A	amount	String	Total dollar amount that the merchant returned to the customer.
N/A	status	String	Indicates the status of the refund. For a list of possible values, see the transaction status enumeration.
N/A	currency_code	String	ISO currency code for the refund. For a list of possible values, see the currency code enumeration.
transactions	tender_type	String	Type of payment card that the customer used for the refund. The value is one of the following: • `credit` • `debit`
entry_type	String	Indicates how the user entered the card details. The value is one of the following: • `Contact` • `Contactless` • `Manual` • `Swipe`
id	String	Unique identifier that our gateway generated for the refund. Note: This is the creditreturn_id or debitreturn_id that you can include in the endpoint URL for follow-on transactions.
reference_id	String	Unique identifier for the refund that the merchant created. Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.
status	String	Indicates the status of the refund. For a list of possible values, see the transaction status enumeration.
status_code	String	Indicates the status of the request. For a list of status codes, see Handling Responses.
transaction_datetime	String	Date and time of the refund that the processor returns in YYYY-MM-DDThh:mm:ssZ format, for example, `2019-12-15T13:00:00Z`.
credit_attributes	Object	Object that we return if the customer uses a credit card. See the credit_attributes object.
debit_attributes	Object	Object that we return if the customer uses a debit card. See the object.

Object

Field

Type

Description

N/A

invoice_number

String

Invoice number for the refund.

N/A

amount

String

Total dollar amount that the merchant returned to the customer.

N/A

status

String

Indicates the status of the refund. For a list of possible values, see the transaction status enumeration.

N/A

currency_code

String

ISO currency code for the refund. For a list of possible values, see the currency code enumeration.

transactions

tender_type

String

Type of payment card that the customer used for the refund. The value is one of the following:
• credit
• debit

entry_type

String

Indicates how the user entered the card details. The value is one of the following:
• Contact
• Contactless
• Manual
• Swipe

String

Unique identifier that our gateway generated for the refund.
Note: This is the creditreturn_id or debitreturn_id that you can include in the endpoint URL for follow-on transactions.

reference_id

String

Unique identifier for the refund that the merchant created.
Note: This is the reference_id that you can include in the endpoint URL for follow-on transactions.

status

String

Indicates the status of the refund. For a list of possible values, see the transaction status enumeration.

status_code

String

Indicates the status of the request. For a list of status codes, see Handling Responses.

transaction_datetime

String

Date and time of the refund that the processor returns in YYYY-MM-DDThh:mm:ssZ format, for example, 2019-12-15T13:00:00Z.

credit_attributes

Object

Object that we return if the customer uses a credit card. See the credit_attributes object.

debit_attributes

Object

Object that we return if the customer uses a debit card. See the object.

Object	Field	Type	Description
N/A	approval_code	String	Approval code for the sale from the processor.
N/A	avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
N/A	avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
N/A	cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the credit card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total dollar amount for the sale.
type	String	Type of payment for the sale. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the credit card that the customer used for the sale. We mask all digits except the first six and the last four.
cardholder_name	String	Name that appears on the customer’s credit card.
expiry_month	String	Month that the credit card expires in MM format.
expiry_year	String	Year that the credit card expires in YY format.
type	String	Name of the card brand that issued the credit card. For a list of possible values, see the card type enumeration.
balance	String	Dollar amount that remains on the credit card.
postal_code	String	Postal code that the credit card is registered to.
rfmiq	String	Unique token that tracks the customer’s spending habits.
emv	amount	Object	Object that contains details about the dollar amount of the sale. See the amount object.
icc	Object	Object that contains details about the integrated circuit card (ICC). See the icc object.

Object

Field

Type

Description

N/A

approval_code

String

Approval code for the sale from the processor.

N/A

avs_response

String

Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.

N/A

avs_response_description

String

Text that describes the response code that the processor returned in the avs_response field.

N/A

cardsecurity_response

String

Indicates if the card security code (CSC) that the customer entered matches the CSC of the credit card. For a list of possible values, see the card security response enumeration.

payment

amount

String

Total dollar amount for the sale.

type

String

Type of payment for the sale. For a list of possible values, see the payment type enumeration.

card

masked_card_number

String

Masked card number of the credit card that the customer used for the sale. We mask all digits except the first six and the last four.

cardholder_name

String

Name that appears on the customer’s credit card.

expiry_month

String

Month that the credit card expires in MM format.

expiry_year

String

Year that the credit card expires in YY format.

type

String

Name of the card brand that issued the credit card. For a list of possible values, see the card type enumeration.

balance

String

Dollar amount that remains on the credit card.

postal_code

String

Postal code that the credit card is registered to.

rfmiq

String

Unique token that tracks the customer’s spending habits.

emv

amount

Object

Object that contains details about the dollar amount of the sale. See the amount object.

icc

Object

Object that contains details about the integrated circuit card (ICC). See the icc object.

Object	Field	Type	Description
N/A	approval_code	String	Approval code for the sale from the processor.
N/A	avs_response	String	Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.
N/A	avs_response_description	String	Text that describes the response code that the processor returned in the avs_response field.
N/A	cardsecurity_response	String	Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.
payment	amount	String	Total dollar amount for the sale.
type	String	Type of payment for the sale. For a list of possible values, see the payment type enumeration.
card	masked_card_number	String	Masked card number of the debit card that the customer used for the sale. We mask all digits except the first six and the last four.
cardholder_name	String	Name that appears on the customer’s debit card.
expiry_month	String	Month that the debit card expires in MM format.
expiry_year	String	Year that the debit card expires in YY format.
type	String	Name of the card brand that issued the debit card. For a list of possible values, see the card type enumeration.
balance	String	Dollar amount that remains on the debit card.
postal_code	String	Postal code that the debit card is registered to.
debit_trace_number	String	Unique number that banks can use to track transactions. We return this for debit transactions.
rfmiq	String	Unique token that tracks the customer’s spending habits.
emv	amount	Object	Object that contains details about the dollar amount of the sale. See the amount object.
icc	Object	Object that contains details about the integrated circuit card (ICC). See the object.

Object

Field

Type

Description

N/A

approval_code

String

Approval code for the sale from the processor.

N/A

avs_response

String

Response code from an address verification service (AVS) lookup. For a list of possible values, see the AVS response enumeration.

N/A

avs_response_description

String

Text that describes the response code that the processor returned in the avs_response field.

N/A

cardsecurity_response

String

Indicates if the card security code (CSC) that the customer entered matches the CSC of the card. For a list of possible values, see the card security response enumeration.

payment

amount

String

Total dollar amount for the sale.

type

String

Type of payment for the sale. For a list of possible values, see the payment type enumeration.

card

masked_card_number

String

Masked card number of the debit card that the customer used for the sale. We mask all digits except the first six and the last four.

cardholder_name

String

Name that appears on the customer’s debit card.

expiry_month

String

Month that the debit card expires in MM format.

expiry_year

String

Year that the debit card expires in YY format.

type

String

Name of the card brand that issued the debit card. For a list of possible values, see the card type enumeration.

balance

String

Dollar amount that remains on the debit card.

postal_code

String

Postal code that the debit card is registered to.

debit_trace_number

String

Unique number that banks can use to track transactions. We return this for debit transactions.

rfmiq

String

Unique token that tracks the customer’s spending habits.

emv

amount

Object

Object that contains details about the dollar amount of the sale. See the amount object.

icc

Object

Object that contains details about the integrated circuit card (ICC). See the object.

Field	Type	Description
amount_authorized	String	Dollar amount that was approved for the refund.
amount_other	String	Dollar amount that was cashback.

Field

Type

Description

amount_authorized

String

Dollar amount that was approved for the refund.

amount_other

String

Dollar amount that was cashback.

Field	Type	Description
dedicated_file_name	String	Name of the EMV Dedicated File for receipts. For more information, refer to the EMVCo website.
application_label	String	Application label for an EMV transaction.
application_expiry_date	String	Date the application expires.
application_effective_date	String	Date the application was released.
application_interchange_profile	String	Indicates the card’s functions.
application_version_number	String	Version number of the application.
application_transaction_counter	String	Application transaction counter (ATC) for an EMV transaction.
application_usage_control	String	Indicates the geographic and service restrictions that the issuer has placed on the card.
application_preferred_name	String	Name of the application in the cardholder’s local language.
application_display_name	String	Name of the application to display.
application_pan_sequence_number	String	Sequence number to identify cards with the same PAN in a transaction.
application_cryptogram	String	Application cryptogram (AC) for an EMV transaction.
application_cryptogram_type	String	Type of cryptogram that the application uses. The value is one of the following: • `TC` - Transaction Certificate • `AAC` - Application Authorization Cryptogram • `ARQC` - Authorization Request Cryptogram
cardholder_verification_method_results	String	Result of the last card verification.
issuer_application_data	String	Information for sending the transaction request to the issuer.
terminal_verification_results	String	Terminal verification results (TVR) for an EMV transaction.
unpredictable_number	String	Value that the terminal uses to generate a cryptogram.
pos_entry_mode	String	Indicates how the device read the card details.
terminal_type	String	Details of the terminal that sent the transaction.
ifd_serial_number	String	Serial number of the terminal or device.

Field

Type

Description

dedicated_file_name

String

Name of the EMV Dedicated File for receipts. For more information, refer to the EMVCo website.

application_label

String

Application label for an EMV transaction.

application_expiry_date

String

Date the application expires.

application_effective_date

String

Date the application was released.

application_interchange_profile

String

Indicates the card’s functions.

application_version_number

String

Version number of the application.

application_transaction_counter

String

Application transaction counter (ATC) for an EMV transaction.

application_usage_control

String

Indicates the geographic and service restrictions that the issuer has placed on the card.

application_preferred_name

String

Name of the application in the cardholder’s local language.

application_display_name

String

Name of the application to display.

application_pan_sequence_number

String

Sequence number to identify cards with the same PAN in a transaction.

application_cryptogram

String

Application cryptogram (AC) for an EMV transaction.

application_cryptogram_type

String

Type of cryptogram that the application uses. The value is one of the following:
• TC - Transaction Certificate
• AAC - Application Authorization Cryptogram
• ARQC - Authorization Request Cryptogram

cardholder_verification_method_results

String

Result of the last card verification.

issuer_application_data

String

Information for sending the transaction request to the issuer.

terminal_verification_results

String

Terminal verification results (TVR) for an EMV transaction.

unpredictable_number

String

Value that the terminal uses to generate a cryptogram.

pos_entry_mode

String

Indicates how the device read the card details.

terminal_type

String

Details of the terminal that sent the transaction.

ifd_serial_number

String

Serial number of the terminal or device.

Running an Independent Refund

Endpoints

Request parameters

Response fields

Code samples

Request sample for a Credit refund

Response sample for a Credit refund

Request sample for a Debit refund

Response sample for a Debit refund