Skip to main content

Preauthorized Payments

The payment token retrieved from the wallet provider can be used to initiate preauthorized wallet transactions over the Stitch API. The initiateTransaction API call is used to authorize an initial amount on the user's card. A subsequent continueTransaction API call is used to capture an amount not exceeding the original authorization. Transactions can be automatically voided or manually cancelled using the cancelTransaction API.

Note

An initial validateApplePayMerchant or verifySamsungPay API request is still applicable for web integrations. The subsequent authorisation and capture (or void) flow is identical across both integration shapes.

Preauthorization​

To preauthorize a wallet payment Stitch API initiateTransaction mutation call is required in order to initiate the payment. The mutation must be called in the server-side payment creation API routes for each wallet provider.

The input variable object must be constructed distinctly for each wallet provider. The following fields are required in addition to the variables specified for standard once-off payments.

API Input Fields
  • The paymentMethods.<payment-method>.preAuthorization.enabled field must be set to true.
  • The voidAt field optionally specifies the datetime at which the preauthorization should be voided.

The fingerprint argument supplied to the create payment callback on the client side should be specified in the deviceInformation.fingerprint field. If this is unable to be provided, other fields within the deviceInformation object are required, including all of deviceId, ip and screenDimensions.

Caution For Apple Pay and Google Pay Payments
  • The payment token must be Base64-encoded.
  • The Apple Pay token is a JavaScript object.
  • The Google Pay token is a serialized object. For Apple Pay and Google Pay payments, the payment token must be Base64-encoded. The Apple Pay payment token is a JavaScript object and is a serialised object for Google Pay.

Completion​

To capture the preauthorized amount and complete a transaction, use the continueTransaction API. The continueTransaction API call requires a client token with the scope transaction_initiate.

API Input Fields
  • The id field must contain the transaction ID returned in the initiateTransaction API response.
  • The amount field specifies the final amount to capture, up to the preauthorized value.
danger

The capture amount in the continueTransaction API call must not exceed the original amount that was preauthorized in the initiateTransaction call. Attempting to capture an amount greater than that which was preauthorized will result in an API error being returned.

Cancellation​

To cancel a transaction manually and void the initial authorization, use the cancelTransaction API. The cancelTransaction API call requires a client token with the scope transaction_cancel.

Transaction Cancellation Options
  • Transactions are cancelled by default after 72 hours.
  • A default voidAt for all transaction can be configured on your client.
  • If the voidAt field has been specified in the initiateTransaction API call, then manually cancelling the transaction is not required, but can be actioned before the duration has elapsed.

Transaction Statuses​

The table below describes the possible statuses for a transaction:

StatusDescription
TransactionPendingThe transaction has been initiated, but an interaction is required for the transaction to be successfully completed. An associated reason will be returned with this status e.g. waitingForCapture if the payment is awaiting capture.
TransactionSuccessThe transaction has been successfully completed, and user's card has been charged.
TransactionFailureThe transaction failed to be charged on the user's card. An associated reason will be returned with this status.
TransactionCancelledThe transaction has been cancelled automatically or manually, and the preauthorization has been successfully voided.

Querying Transactions​

Transaction by ID​

For implementing redundancy checks and logic, it is possible to query transaction statuses and details over the Stitch GraphQL API. Note that querying with the Stitch-provided id is the most performant, and the recommended approach.

Transaction by External Reference​

Alternatively, querying by an externalReference is possible, and may be done with a filtering query, as follows:

note

Use the SamsungPayTransaction or GooglePayTransaction to query fields specific to Samsung Pay or Google Pay wallet payments. As an example, a query for an Apple Pay payment is shown.

Webhook Subscriptions​

Wallet payments require that you subscribe to transaction webhooks to receive asynchronous updates on transaction status changes.

If the subscription is successfully created, the body returned by the request will look similar to the sample in the Example Response tab in the widget above.

The webhook will contain important information regarding the transaction, including the selected wallet provider, the transaction retrieval reference number (RRN) (used for reconcilliation), external reference, and nonce.

For more information on receiving webhook events, listing active webhook subscriptions, unsubscribing from webhooks and validating signed webhook subscriptions, please visit the Webhooks page.

Webhook Statuses​

When subscribed to the transaction webhook filter type, webhook updates will be sent whenever a transaction is updated to either of the following statuses:

  • TransactionSuccess
  • TransactionFailure
  • TransactionCancelled