Loading...
Note: To run an independent refund without a linked sale or to run a refund on a debit sale, see Running an Independent Refund.
To return the dollar amount of a sale to a customer’s account, send a POST request to the relevant endpoint.
| Scenario | Merchant uses the POS to: |
|---|---|
| Customer bought a t-shirt for $10 and wants to return it. The sale for the t-shirt is in a closed batch. | 1. Find the sale. 2. Run a refund to return $10 to the customer’s account. |
You can’t refund a sale that is in an open batch. If the sale is in an open batch, you must void the transaction. For more information, see Running a Void on a Credit Sale or Running a Void on a Debit Sale.
The endpoint you use depends on whether you identify the original transaction using the creditsale_id or the reference_id.
| Object | Parameter | Type | Size | Required? | Description |
|---|---|---|---|---|---|
| customer | id | String | N/A | Optional | Customer's ID from the Customer Experience (CX) application. |
| title | String | 1-10 | Optional | Customer’s title. You can send an alphanumeric value. Note: If the customer is a business, do not send this parameter. Send the business_name parameter. | |
| first_name | String | 1-50 | Optional | Customer’s first name. Note: If the customer is a business, do not send this parameter. Send the business_name parameter. | |
| middle_name | String | 1-50 | Optional | Customer’s middle name. Note: If the customer is a business, do not send this parameter. Send the business_name parameter. | |
| last_name | String | 1-50 | Optional | Customer’s last name. Note: If the customer is a business, do not send this parameter. Send the business_name parameter. | |
| business_name | String | 1-50 | Optional | Business name. Note: If the customer is not a business, send a value for each of the following parameters: • title • first_name • middle_name • last_name | |
| String | 1-50 | Optional | Customer’s email address. You can send an alphanumeric value. | ||
| phone | String | 2-50 | Optional | Customer’s phone number. | |
| note | String | 1-40 | Optional | Note that the merchant adds about the customer. You can send an alphanumeric value. | |
| billing_address | Object | N/A | Optional | Object that includes the customer’s billing address. For a list of parameters, see the billing_address object. | |
| payment | amount | String | 1-9 | Required | Total dollar amount that you are returning to the customer’s account. The value includes two decimal places, for example, 10.00. |
| invoice_number | String | 1-25 | Optional | Alphanumeric invoice number or order number that the merchant creates and assigns to the refund. | |
billing_address object
| Parameter | Type | Size | Required? | Description |
|---|---|---|---|---|
| line1 | String | 1-50 | Optional | First line of the customer’s address. You can send an alphanumeric value. |
| line2 | String | 1-50 | Optional | Second line of the customer’s address. You can send an alphanumeric value. |
| city | String | 1-50 | Optional | City of the customer’s address. You can send an alphanumeric value. |
| state | String | 1-50 | Optional | State or province of the customer’s address. You can send an alphanumeric value. |
| country | String | 1-50 | Optional | Country of the customer’s address. You can send an alphanumeric value. |
| postal_code | String | 1-20 | Optional | Postal code of the customer’s address. You can send an alphanumeric value. Note: This is also known as the zip code. |
processing_indicators object
| 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. |
| generate_receipt | Boolean | Explicit | Optional | If set to true, the POS generates a customer receipt and a merchant receipt for the refund. |
| Object | Field | Type | Description |
|---|---|---|---|
| N/A | creditreturn_id | String | Unique identifier that our gateway generated for the transaction. Note: This is the creditreturn_id that you can include in the endpoint URL for follow-on transactions. |
| N/A | status | String | Indicates the status of the refund. For a list of possible values, see the Transaction status enumeration. |
| N/A | approval_code | String | Approval code for the refund from the processor. |
| N/A | reference_id | String | Unique identifier for the sale that the merchant created. Note: This is the reference_id parameter that you can include in the endpoint URL for follow-on transactions. |
| card | masked_card_number | String | Masked card number of the card that the customer used for the refund. We mask all digits except the first six and the last four. |
| expiry_month | String | Month that the card expires in MM format. | |
| expiry_year | String | Year that the card expires in YY format. | |
| type | String | Name of the card brand that issued the card. For a list of possible values, see the Card type enumeration. | |
| payment | amount | String | Total dollar amount for the transaction. |
| invoice_number | String | Invoice number for the transaction. | |
| type | String | Type of payment for the transaction. For a list of possible values, see the Payment type enumeration. | |
| transaction | batch_amount | String | Total dollar amount of the batch. |
| batch_number | String | Unique identifier of the batch. | |
| receipt | id | String | Unique alphanumeric value that our gateway assigns to the receipt. |
| text | Object | Object that contains text for the customer copy and merchant copy of the receipt. For a list of fields, see the text object. | |
| attributes | Object | Object that contains details of text that the receipt can include. For a list of fields, see the attributes object. | |
| labeled_attributes |
text object
| Field | Type | Description |
|---|---|---|
| customer_receipt | String | Text for the customer's receipt. Our gateway creates this text using the details of the sale. |
| merchant_receipt | String | Text for the merchant's receipt. Our gateway creates this text using the details of the sale. |
attributes object
| Field | Type | Description |
|---|---|---|
| authorization_agreement | String | Text that describes the merchant's authorization agreement, for example, I agree to pay the total amount according to the card issuer agreement. |
| call_issuer | String | Text that displays if the merchant needs to call the issuing bank, for example, CALL ISSUER. |
| copy_label_customer | String | Text that identifies the receipt as the customer's copy. |
| copy_label_merchant | String | Text that identifies the receipt as the merchant's copy. |
| merchant_address | String | Address of the merchant's store. |
| merchant_footer | String | Text that appears on the footer of the receipt. |
| merchant_header | String | Text that appears on the header of the receipt. |
| merchant_name | String | Name of the merchant's store. |
| merchant_phone | String | Phone number of the merchant's store. |
| merchant_policy | String | Text that describes the merchant's policies, for example, a return policy. |
| verbiage | String | Additional text that the merchant can include on the receipt, for example, Approved - Thank You. |
labeled_attributes object
We return a label field and a value field for each object. For example, for amount, we return the following:
"amount":
{
"label": "Total Amount",
"value": "$99.45 USD"
}
| Object | Description |
|---|---|
| amount | Total dollar amount of the transaction. |
| approval_code | Approval code for the transaction from the processor. |
| authorization_response_code | Response code for an authorization. |
| avs_response_code | Response code that indicates the result of an AVS check. |
| batch_number | Unique identifier of the batch. |
| card_balance | Remaining balance of a prepaid card. |
| card_type | Type of card the customer used for the transaction. |
| cardsecurity_response_code | 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 enumerations. |
| clerk_id | 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, Al090-John Doe. |
| entry_legend | Indicates how the payment terminal read the card details. The value is one of the following: • CHIP READ• MAGSTRIPE• MANUAL |
| entry_method | Indicates how the customer or merchant entered the card details. The value is one of the following: • Contact• Contactless• Manual• Swipe |
| gratuity_amount | Dollar amount that was tip in the original transaction. |
| masked_card_number | Masked card number of the card that the customer used for the transaction. We mask all digits except the first six and the last four. |
| merchant_id | Unique identifier for the merchant. |
| original_auth_code | The authorization code of the original sale. |
| payment_type | Type of payment for the sale. For a list of possible values, see the payment type enumeration. |
| number | Number of the receipt. |
| reference_id | Unique identifier that the merchant created for the sale. Note: You can include the reference_id in the endpoint URL for follow-on transactions. |
| subtotal_amount | Dollar amount for the subtotal of the sale. We return either a value or a blank line. |
| total_amount | Total dollar amount of the sale. We return either a value or a blank line. |
| transaction_datetime |
creditreturn_id object
| Field | Type | Description |
|---|---|---|
| href | String | Endpoint URL for the follow-on transaction using the creditreturn_id. |
| relation | String | Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • return - The transaction uses a returns endpoint.• self - The transaction uses the same type of endpoint as the original request.• void - The transaction uses a voids endpoint. |
| method | String | HTTP method for sending the transaction. The value is one of the following: • GET• PATCH• POST• PUT |
| description | String | Text that describes the follow-on transaction, for example, get a sale transaction using sale id. |
reference_id object
| Field | Type | Description |
|---|---|---|
| href | String | Endpoint URL for the follow-on transaction using the reference_id. |
| relation | String | Relationship between the endpoint you sent the original request to and the endpoint for the follow-on transaction. The value is one of the following: • return - The transaction uses a returns endpoint.• self - The transaction uses the same type of endpoint as the original request.• void - The transaction uses a voids endpoint. |
| method | String | HTTP method for sending the transaction. The value is one of the following: • GET• PATCH• POST• PUT |
| description | String | Text that describes the follow-on transaction, for example, get a sale transaction using sale id. |
| transaction |
| soft_descriptor |
| String |
| 1-17 |
| Optional |
| Alphanumeric description that shows on the customer’s card statement. |
| processing_indicators | Object | N/A | Optional | Object that includes options for additional actions. For a list of parameters, see the processing_indicators object. |
| 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, Al090-John Doe. |
| Object |
| Object that contains details of the sale. For a list of fields, see the labeled_attributes object. |
| links | creditreturn_id | Object | Object that includes HATEOAS links for follow-on transactions using the creditreturn_id. For a list of fields, see the creditreturn_id object. |
| reference_id | Object | Object that includes HATEOAS links for follow-on transactions using the reference_id. For a list of fields, see the reference_id object. |
Date and time of the transaction that the processor returns in YYYY-MM-DDThh:mm:ssZ format, for example, 2019-12-15T13:00:00Z. |
| transaction_id | Unique ID our gateway assigned to the original transaction. |
| transaction_type | Type of transaction you ran. |
| validation_code | Validation code from the issuing bank. |
| application_cryptogram | Application cryptogram (AC) for an EMV transaction. |
| application_identifier | Application identifier (AID) for an EMV transaction. |
| application_label | Application label for an EMV transaction. |
| application_preferred_name | Name of the application in the cardholder’s local language. |
| application_transaction_counter | Application transaction counter (ATC) for an EMV transaction. |