Initiate the refund
refundId
to uniquely identify this refund.
This is so that you always have a reference to the refund you are initiating, even if you do not receive a response from us due to network errors.
This allows you to always reconcile all payments between your system and pawaPay.
You should store this refundId in your system before initiating the refund with pawaPay.The depositId
refers to the deposit you are looking to refund.You will receive a response for the initiation.status
shows whether this payout was ACCEPTED
for processing or not.
We will go through failure modes later in the guide.The refund will be processed
Get the final status of the payment
status
which is COMPLETED
indicating that the refund has been processed successfully.And done!
Partial refund
amount
and the currency
of how much should be refunded.
Otherwise everything stays the same. The request should be ACCEPTED
and you will receive a callback once it’s processed.Multiple refunds
REJECTED
.amount
specified) is initiated after a successfully processed partial refund, the remaining amount will be refunded.For example:amount
not specified on initiation): 100 - 20 - 20 = 60 RWFAnd done!
One refund at a time
PROCESSING
, initiating a new refund will be rejected.Maximum amount
Decimals in amount
decimalsInAmount
property shows whether the specific provider supports decimals in the amount when doing refunds.
The possible values for it are TWO_PLACES
and NONE
.
You can dynamically round the amount if decimals are not supported (NONE
).Checking if the provider is operational
OPERATIONAL
- the provider is available and processing refunds normally.DELAYED
- the provider is having downtime and all refund requests are being enqueued in pawaPay.CLOSED
- the provider is having downtime and pawaPay is rejecting all refund requests.DELAYED
) or is not possible at the moment and they can try again later (CLOSED
).You can validate the status of the provider and delay initiating refunds while the provider is unavailable (CLOSED
).Handling delayed processing
DELAYED
will be ACCEPTED
on initiation.
They will then be moved to the ENQUEUED
status.
Our 24/7 payment operations team will be monitoring the provider for when their refunds service becomes operational again.
When that happens, the refunds will get processed as usual.To find out whether a refund is enqueued, you can check refund status.Handling HTTP 500 with failureCode UNKNOWN_ERROR
UNKNOWN_ERROR
failureCode indicates that something unexpected has gone wrong when processing the payment.
There is no status
in the response in this case.It is not safe to assume the initiation has failed for this refund.
You should verify the status of the refund using the check refund status endpoint.
Only if the refund is NOT_FOUND
should it be considered FAILED
.We will take a look later in the guide, how to ensure consistency of payment statuses between your system and pawaPay.And done!
Handling failures during processing
status
of the refund is FAILED
you can find further information about the failure from failureReason
.
It includes the failureCode
and the failureMessage
indicating what has gone wrong.failureMessage
from pawaPay API is meant for you and your support and operations teams.
You are free to decide what message to show to the customer.UNSPECIFIED_FAILURE
code indicates that the provider indicated a failure with the payment, but did not provide any specifics on the reason of the failure.In case there is a general failure, the UNKNOWN_ERROR
failureCode would be returned.And done!
Defensive status handling
Handling network errors and system crashes
refundId
for each payment is to ensure that you can always ask us what is the status of a payment, even if you never get a response from us.You should always store this refundId
in your system before initiating a refund.ACCEPTED
by pawaPay.Implementing an automated reconciliation cycle
IN_RECONCILIATION
.
This means that there was a problem determining the correct final status of a payment.
When using pawaPay all payments are reconciled by default and automatically - we validate all final statuses to ensure there are no discrepancies.
When encountering payments that are IN_RECONCILIATION
you do not need to take any action.
The payment has already been sent to our automatic reconciliation engine and it’s final status will be determined soon.
The reconciliation time varies by provider. Payments that turn out to be successful are reconciled faster.