Capturing an authorized payment

A capture describes the process of how merchants capture funds for an authorized payment. A capture 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 capture the funds on an authorized transaction, Shopify sends a capture request to a payments app, and the app can resolve or reject it.

capture steps

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

Requirements

Scopes

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

Initiate the flow

A capture 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 capture request with either CaptureSessionResolve or CaptureSessionReject mutations to either accept or reject the capture of funds.

The capture flow begins with an HTTP request sent from Shopify to the provider's Capture session URL:

Request Body

Request headers

Request attributes

Attribute Description Type
idRequired Unique identifier for the capture attempt. Used as the idempotency key. Assume that requests with a given ID are identical to any previously-received requests with the same ID. string
gidRequired Identifies the capture when communicating with Shopify (in GraphQL mutations, for example). string
payment_idRequired The ID of the authorized payment that is to be captured. string
amountRequired The amount to be captured. string
currencyRequired The three-letter ISO currency code. String (ISO-8601)
merchant_localeRequired The IETF BCP 47 language tag representing the language used by the merchant. Boolean
proposed_atRequired A timestamp representing when the capture request was proposed. String (ISO-8601)

Capture an authorized payment

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

The id argument corresponds to the gid of the capture.

Variables:

View response

JSON response:

Reject a capture

If you don't want to process a capture request, then you should reject it. You might want to reject a capture if authorization has expired or if you suspect that the request is fraudulent or high risk. You should only reject a capture in the case of final and irrecoverable errors. Otherwise, you should re-attempt to resolve the capture.

You can reject a capture using the RefundSessionReject mutation:

Variables:

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

The CaptureSessionRejectionReasonInput.code is a CaptureSessionStatusReasonRejectionCode, which is an enum of standardized error codes.

The CaptureSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the capture 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