Refunds

Multiple partial refunds can also be created up to the amount of the original payment.

info

Please note that Capitec Pay VRP refunds are not strictly a reversal. Funds will be paid out of a configured float account 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 Capitec Pay transaction, the following conditions should be met:

• Your API client is configured with a float account.
• The initial 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 endpoint https://api.stitch.money/graphql can be used for all refund requests (test or live).

Creating a Capitec Pay Refund

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

• The transaction ID (originalPaymentId) of the original 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.

Refund Statuses

The table below describes the different statuses of a Capitec Pay 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 paid, due to the associated reason field.
TransactionSuccess	A refund transaction was successfully initiated, and the requested amount will be paid to the initial transaction's source.

note

The final refund status will also be provided via a webhook notification.

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

Capitec Pay 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 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.

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