Payments

6.3. Refunds Early Access

Note

This chapter includes information about features or aspects of the platform that are deemed Early Access.

Early Access features has added stability and will not encounter breaking changes, offering a backward compatible API Schema.

Certain Early Access features may not be accessible to all Stitch users by default. These features can be enabled on a per-client basis on request.

Refunds allow the reversal of payments made using Payment Requests. Multiple partial refunds may also be created up to the amount of the original payment. This feature is currently only available to South African customers.


Creating a refund

To issue a refund for a particular payment, you'll need to ensure that the following conditions are met:

  1. Refund must be associated with a Stitch payment request (you will need the payment request ID).
  2. The payment must be in the completed state.
  3. The refund amount must be less than or equal to the original payment amount.

Note: Though a refund may be created at any point in time, Stitch will only process them once the original payment amount has cleared. In some cases it could take up to 3 days for money to reflect in the destination account.

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.

To create the request, a GraphQL mutation is used to specify the requested amount, the refund reason, a nonce to determine uniqueness, a reference that the beneficiary of the refund will see on their statement, and the id of the PaymentRequest being refunded. An example of this can be found below:

You will need the refund id from the response, in order to look up the status of the request in the API, and so should be retained for later usage. The refund id will also be included in the subscription payload. See an example of that below.



Retrieving the refund status

When receiving a callback from the refund creation, you will likely want to check the status of the refund. Using the query below you can retrieve the status of a given refund by id.

To retrieve the status of a refund, as described above, you'll need a client token with the client_refund scope.



Subscribing to refund webhooks

To create a webhook subscription, you submit a GraphQL query like the one seen below. To learn more about implementing Webhooks with the Stitch API, please visit the Webhooks page.

If the subscription is successfully created, the body returned by the request will look like the following, with data being null, and the subscriptionId being contained with the extensions field:

1{
2 "data": null,
3 "extensions": {
4 "subscriptionId": "c3ViL2YxYzVjMTZkLWE0NjQtNDgxYS05NTUyLWUyMjhiYjQzNGE0NAo="
5 }
6}

Visit the Webhooks page for information on receiving webhook events, unsubscribing from webhooks and validating subscriptions.



Error handling for refunds

An example response of a failed refund creation can be found below:

1{
2 "errors": [
3 {
4 "message": "The payment associated with this refund is pending. The payment must be completed before a refund can be issued.",
5 "locations": [
6 {
7 "line": 77,
8 "column": 3
9 }
10 ],
11 "path": [
12 "clientRefundInitiate"
13 ],
14 "extensions": {
15 "code": "PAYMENT_INCOMPLETE",
16 "reason": "PENDING"
17 }
18 }
19 ],
20 "data": null
21}

Most errors have one of the codes: NOT_FOUND, PAYMENT_INCOMPLETE, BAD_USER_INPUT or NONCE_DUPLICATE.

Errors with the code PAYMENT_INCOMPLETE will have an additional field reason which could either be PENDING or CANCELLED.

The message field further elaborates on the error.

This table describes the errors you may encounter when trying to initiate a refund:

Refund Error Reasons
CodeMessage
NOT_FOUNDCould not find paymentRequest for this refund
PAYMENT_INCOMPLETEreason: PENDING
The payment associated with this refund is pending. The payment must be completed before a refund can be issued.
PAYMENT_INCOMPLETEreason: CANCELLED
The payment associated with this refund was marked as cancelled. The payment must be completed before a refund can be issued.
BAD_USER_INPUTExpected clearing time to be two days since payment was marked as completed
BAD_USER_INPUTExpected refund amount to be less than or equal to the original payment amount.
BAD_USER_INPUTExpected total requested refund amount to be less than or equal to the original payment amount.
BAD_USER_INPUTRefunds cannot be created for payments made directly to client account. This error would occur if you have moved into the flow of funds, and attempt to initiate a refund on a payment that was completed prior to being in the flow of funds. Please contact the Stitch team if you encounter this error.
NONCE_DUPLICATEA refund request with this nonce has already been issued. Expected nonce to be unique.