Wallet Refunds

Wallet Refunds allow the reversal of payments made using Wallet payment methods. Multiple partial refunds can also be created up to the amount of the original payment.

info

Please note that refunds can only be made for Wallet pay-ins, and will be to the same destination from which the pay-in originated. The destination for a refund cannot be changed.

To issue a refund for a particular wallet transaction, the following conditions should be met:

• The initial wallet transaction must be in the TransactionSuccess state.
• The refund amount must be less than or equal to the original transaction amount.
• The refund amount (if partial) must not exceed the original transaction amount less any previously processed partial refund amounts.

Refund creation is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_refund scope.

The GraphQL API URL https://api.stitch.money/graphql can be used for all refund requests (whether on test or live clients).

Creating a Wallet Refund

The GraphQL mutation shown below should be used to create wallet refunds, and includes the following input values:

• The transaction ID (originalPaymentId) of the original wallet transaction being refunded,
• The requested refund amount (refundInput.amount), that should be less than, or equal to, the original transaction amount,
• An appropriate refund reason (refundInput.reason),
• A nonce value (refundInput.nonce) that uniquely identifies the refund request, and
• An optional reference (refundInput.externalReference) to associate to the refund.

Open in IDE ↗

tip

The originalPaymentId input in the mutation accepts either a Apple Pay, Samsung Pay or Google Pay™ transaction ID.

Refund Statuses

The table below describes the different statuses of a wallet payment:

Status	Description
TransactionPending	A refund transaction is initialised and awaiting processing, due to a timeout or delay in status confirmation downstream from Stitch.
TransactionFailure	A refund transaction failed to be initiated, and funds were not reversed, due to the associated reason field.
TransactionSuccess	A refund transaction was successfully initiated, and the requested amount will be reversed to the initial transaction's source.

note

Wallet refund transactions are typically processed immediately by Stitch, with a final status being returned immediately in the response. The TransactionPending status may occur in rare edge cases, soon after which the final status will be provided via a webhook notification.

Failure Reasons

The TransactionFailure status indicates that the refund failed to be initiated, and includes a reason explaining the cause. Potential failure reasons are detailed below:

Reason	Description
blockedByFraudChecks	The transaction was blocked due to fraud checks.
downstreamProviderError	The transaction could not be processed due to downstream error.
exceedsOriginalAmount	The refund amount exceeds the original transaction amount, or outstanding refundable amount (after previously processed partial refunds).
internalServerError	The transaction could not be processed due to a server error.
invalidCardError	The transaction was declined due to an expired card.
invalidConfigurationError	The client has invalid or missing configuration.
invalidTransactionError	The refund transaction was declined for processing, or the original transaction was not completed..
paymentRefundFailed	The refund transaction could not be processed.

Querying Refunds

Refund by ID

For implementing redundancy checks and logic, it is possible to query refund 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.

Refund by External Reference

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

Webhook Subscriptions

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

note

If you are already subscribed to transaction webhooks for wallet pay-ins, you will automatically receive refund transactions as part of the same webhook subscription.

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 final statuses:

• TransactionSuccess
• TransactionFailure

Simulating Refund Statuses

For testing purposes, specific amounts can be used to simulate different scenarios when using a test client. The table below shows the mapping between amounts and transaction statuses:

Amount	Status	Reason
401	FAILURE	paymentRefundFailed
402	FAILURE	downstreamProviderError
403	FAILURE	invalidCardError
Other	SUCCESS	-

Postman Collection

Wallet refunds can be created and tested using the Postman collection available here. These can be used by specifying your client credentials and supplying the custom request variables where required.