Terminal

Refund Interac Payments

This topic describes how to use the Terminal API to request a refund of Interac payments processed on a Square Terminal in Canada to Canadian sellers.

Use a Square Terminal and the Terminal API to request a refund of Interac payments on a Square Terminal for Canadian sellers. All other payment types are refunded using the Refunds API.

Overview Permalink Get a link to this section

Interac card payments in Canada can only be refunded when the payment card is present and the original payment is no more than 120 days old. This means that an integration must use a connected Square Terminal to process an Interac refund.

This guide walks you through the development steps necessary to refund an Interac payment with a Square Terminal.

Did you know?

You can test your Terminal API integration in the Square Sandbox. Use Sandbox test values to test your integration against successful and failed Terminal refunds.

Terminal refund webhooks Permalink Get a link to this section

To get notification of status changes on a Square Terminal Interac refund request, you should configure your application to receive the following webhook events:

  • terminal.refund.created

  • terminal.refund.updated

  • payment.updated

When a refund request is created or the state of the request is updated, a full copy of the TerminalRefund object is sent to your application at the URL you specify.

Verify that the payment requires an in-person refund Permalink Get a link to this section

The Payment.CardPaymentDetails object has a refund_requires_card_presence boolean field that when set to true requires that any refunds occur in-person and on a Square Terminal. To get the Payment object to be refunded, review the TerminalCheckout.payment_ids collection to get the payment IDs used in the checkout. Any payments that must be refunded in person are requested with the Terminal API. Other payments must use the Refunds API.

Search for a Terminal checkout payment Permalink Get a link to this section

Completed Terminal checkout requests are only held for 30 days. To refund an older Interac payment, you should provide a list of completed Payment objects for the seller to select from.

The following example lists all payments for a seller location within a time range and in descending order:

List Payments
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/payments?begin_time=2020-01-26T02%253A25%253A34Z&end_time=2020-01-26T05%253A25%253A34Z&sort_order=DESC&location_id={{LOCATION_ID}} \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

An Interac payment refund can be completed when the following requirements are met:

  • The status of the payment must be COMPLETED.

  • The CardPaymentDetails.refund_requires_card_presence must be true.

  • The payment card processed by the payment must be an Interac payment card and the transaction must be in Canadian dollars (CAD).

  • The requested refund amount is not greater than the initial payment minus the sum of completed refunds.

Important

Refunds must be requested from the seller who took the original Interac payment but can be requested from any of the seller's locations.

Create a Terminal refund Permalink Get a link to this section

Request a refund using the following example. The TerminalCheckout might have been completed with multiple payment cards, which results in multiple payment IDs. Payment cards are refunded individually, which requires a refund request for each card.

Note that the amount of a refund request is not the Terminal checkout total. Instead, it is the Payment.total_money minus Payment.refunded_money for each payment to be refunded.

Create Terminal Refund
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareup.com/v2/terminals/refunds \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "blart34343432",
    "refund": {
      "amount_money": {
        "amount": 2610,
        "currency": "CAD"
      },
      "payment_id": "rXnhZzywrEk4vR6pw76fPZfgvaB",
      "device_id": "DEVICE ID",
      "reason": "Purchased item was the wrong size"
    }
  }'

After a Terminal refund is created, it is in a PENDING state for a short period of time while the Square Terminal device receives the refund request and starts the process with the buyer.

When the Square Terminal device starts interacting with the buyer, the Terminal refund moves to the IN_PROGRESS state.

When the buyer is done with the refund flow, the Terminal refund moves to the COMPLETED state. The buyer might also cancel the flow from the Square Terminal device interface, in which case it moves to the CANCELED state.

When a Terminal refund is in the COMPLETED state, it includes a refund ID that you can reference when calling the Refunds API (that is, to call GetRefund).

Webhook notifications Permalink Get a link to this section

If your application is accepting the terminal.refund.updated and payment.updated webhook notifications, the application receives a notification when the refund request is completed and then a notification when the payment is refunded. The Payment.refunded_money field is incremented with the refunded amount.

Get a Terminal refund Permalink Get a link to this section

To check the status of your Terminal refund, you can issue a GET request with the ID returned from your initial POST request.

Terminal refund objects are specified by appending a Terminal refund ID to the GetTerminalRefund endpoint url:

https://connect.squareupsandbox.com/v2/terminals/refunds/{{TERMINAL_REFUND_ID}}

Get Terminal Refund
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/terminals/refunds/{terminal_refund_id} \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The response includes a TerminalRefund.

{
  "terminal_refund": {
    "id": "08YceKh7B3ZqO",
    "refund_id": "UNOE3kv2BZwqHlJ830RCt5YCuaB",
    "amount_money": {
      "amount": 2610,
      "currency": "CAD"
    },
    "reason": "Item returned",
    "device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003",
    "status": "COMPLETED",
    "created_at": "2020-04-06T16:39:32.545Z",
    "updated_at": "2020-04-06T16:39:323.001Z",
    "app_id": "APP_ID",
    "deadline_duration": "PT10M"
  }
}

Cancel a Terminal refund Permalink Get a link to this section

You can cancel a Terminal refund request as long as the status of the request is PENDING. The following is an example of a cancel refund request:

Cancel Terminal Refund
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareup.com/v2/terminals/refunds/123/cancel \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Webhook notifications Permalink Get a link to this section

If your application is accepting the terminal.refund.updated webhook notification, the application receives a notification when the refund request is canceled and then a notification when the payment is refunded. The Payment.refunded_money field is incremented with the refunded amount.

Search for Terminal refunds Permalink Get a link to this section

You can retrieve a filtered list of Terminal refund requests created by the seller making the request.

In this example, a list of completed Terminal refunds is requested:

Search Terminal Refunds
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareup.com/v2/terminals/refunds/search \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 2,
    "query": {
      "filter": {
        "status": "COMPLETED"
      }
    }
  }'

Requirements and limitations Permalink Get a link to this section

  • Applications must have the following OAuth permissions: PAYMENTS_WRITE to process refunds and PAYMENTS_READ to retrieve refunds.

  • You cannot refund non-Interac payments with the Terminal API.