Void 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.
- The merchant requests to void an authorized payment.
- Shopify sends a backend request to the payments app, specifying the void request.
- The app replies with a
201
and an empty response body. - The app finalizes the void request using the
voidSessionResolve
orvoidSessionReject
mutation. - Shopify updates the payment status.
Initiate the flow
Anchor link to section titled "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 the voidSessionResolve
or voidSessionReject
mutation to accept or reject the voiding of funds respectively.
The void flow begins with an HTTP POST request sent from Shopify to the payments app's void session URL provided during app extension configuration:
Shopify must receive an HTTP 201
(Created) response for the void session creation to be successful.
If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the void in the Shopify admin.
Request headers
Anchor link to section titled "Request headers"Header | Description |
---|---|
Shopify-Shop-Domain Required |
The permanent domain of the shop. Can be used to identify which shop is initiating the request. |
Shopify-Request-Id Required |
The unique request ID used to track specific requests for troubleshooting purposes. |
Shopify-Api-Version Required |
The API version selected in the payments app configuration. The version selected defines the response expected by the payments app. |
Request body
Anchor link to section titled "Request body"Attribute | Description | Type |
---|---|---|
id Required |
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 |
gid Required |
Identifies the void when communicating with Shopify (in GraphQL mutations, for example). | String |
payment_id Required |
The ID of the authorized payment that is to be voided. | String |
test Required |
Indicates whether the void is in test or live mode. The test field is only sent if you select API version 2022-01 or higher in the payments app extension configuration in the Partner Dashboard. For more information, refer to Test a payments app.
| Boolean |
merchant_locale Required |
The IETF BCP 47 language tag representing the language used by the merchant. | String |
proposed_at Required |
A timestamp representing when the void request was proposed. | String (ISO-8601) |
Resolve a void session
Anchor link to section titled "Resolve a void session"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.
Reject a void session
Anchor link to section titled "Reject a void session"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:
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.