Card Refunds

Card Refunds allow the reversal of any transactions initiated using Card, regardless of integration and processing style. Multiple partial refunds can also be created up to the amount of the original payment.

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

• The initial card 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 Card Refund

The https://graphql.org/learn/queries/#mutations shown below should be used to create card refunds, and includes the following input values:

• The transaction ID (originalPaymentId) of the original card 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 a Card transaction ID, as well as a Card payment request ID (for once-off payments initiated via our Hosted UI).

Refund Statuses

The table below describes the different statuses of a card refund transaction:

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

Card 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 the card being expired or restricted for processing.
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.

Subscribe to Webhooks

Card 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 card 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 card 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

Querying Refunds

For redundancy handling on your integration, it is possible to query card refund transaction statuses and details over the Stitch GraphQL API.

Refund by ID

Card refund transactions may be looked up uniquely by the Stitch card refund transaction id value, as shown below:

Refund by External Reference

Alternatively, querying by your specified externalReference may be done with a filtering query, as shown below.

note

This query returns an array of transactions, in case multiple card refund transactions have been initiated with the same externalReference.

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 (when not successful)
401	TransactionFailure	paymentRefundFailed
402	TransactionFailure	downstreamProviderError
403	TransactionFailure	invalidCardError
405	TransactionPending -> TransactionSuccess (after approximately 20 seconds)	waitingForDownstreamProvider
Other	TransactionSuccess	-

Postman Collection

Card 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.