Voiding an authorized payment

A void describes the process of how merchants void funds for an authorized payment. A void is the second part of a two-part payment flow, and occurs after an authorized payment is finalized. Finalized payments have kind set to authorization. When a merchant wishes to cancel the order for an authorized transaction, Shopify sends a void request to a payments app, and the app can resolve or reject it.

void processing steps

  1. The merchant requests to void an authorized payment.
  2. Shopify sends a backend request to the payments app, specifying the void request.
  3. The app replies with a 201 and an empty response body.
  4. The app finalizes the void request using either voidSessionResolve or voidSessionReject mutations.
  5. Shopify updates the payment status.

Requirements

Scopes

To use the GraphQL mutations, your app must be aware of access scopes for payments apps.

Initiate the flow

A void can only be performed when the payment initiated by Shopify has a kind property with a value of authorization. With an authorization you place a hold on funds and then reply to Shopify's void request with either VoidSessionResolve or VoidSessionReject mutations to either accept or reject the voiding of funds.

The void flow begins with an HTTP request sent from Shopify to the provider's URL as provided during app extension configuration:

Request Body

Request headers

Request attributes

Attribute Description Type
idRequired Unique identifier for the void attempt. Used as the idempotency key. It can be assumed that requests with a given ID are identical to any previously-received requests with the same ID. String
gidRequired Identifies the void when communicating with Shopify (in GraphQL mutations, for example). String
payment_idRequired The ID of the authorized payment that is to be voided. String
merchant_localeRequired The IETF BCP 47 language tag representing the language used by the merchant. String
proposed_atRequired A timestamp representing when the void request was proposed. String (ISO-8601)

Response

Shopify must receive a HTTP 201 response for the void session creation to be successful.

If the request fails, then it is retried several times. If the request still fails, then the merchant needs to manually retry the void in the Shopify admin.

Resolve a void request

After you've successfully processed the void request, you can resolve it by using the voidSessionResolve mutation:

The id argument corresponds to the gid of the void.

Variables:

View response

JSON response:

Reject a void request

If you can't process a void request, then you should reject it. You should only reject a void in the case of final and irrecoverable errors. Otherwise, you can re-attempt to resolve the void.

You can reject a void using the voidSessionReject mutation:

Variables:

As part of the rejection, you need to include a reason why the void was rejected as part of VoidSessionRejectionReasonInput.

The VoidSessionRejectionReasonInput.code is a VoidSessionStatusReasonRejectionCode, which is an enum of standardized error codes.

The VoidSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the void was rejected.

View response

JSON response:

Retry policy

If there's a Shopify service disruption (or if 5xx status codes are being returned), then requests must be retried. It is suggested to follow the guidelines in the retry policy section.

Additional information