Refund Deposit
Use this endpoint to refund a completed deposit, in full or in part. The refund is sent to the customer who paid the deposit as an Interac e-Transfer, and is paid from your available balance.
Send the following in the body:
-
transactionId-[string]thetransactionIdof the deposit you want to refund, as returned when you created the deposit. The deposit must beCOMPLETED. -
amount-[float]optional. The amount to refund in CAD, with up to 2 decimals and a.(dot) as decimal separator (e.g.12.50). Leave it out to refund the full deposit amount.
The refund is sent to the email address and name of the customer who paid the deposit; you do not provide them. The memo on the e-Transfer is refund.
The headers must contain your x-api-key and a unique Idempotency-Key (UUID v4). If you send the same key again, the response of the first request is returned and no new refund is created. If a request with a key is still being processed, you get 409 IDEMPOTENCY_IN_PROGRESS.
If a request is refused with a 400 or 404 error after the key was accepted, use a new Idempotency-Key when you retry.
Rules
-
You can refund a deposit several times (partial refunds), but the total refunded cannot be more than the deposit amount. Refunds that were declined, rejected or cancelled do not count towards this total.
-
Your available balance must cover the refund amount plus the refund fee. Check it with Partner Balance.
-
The amount and the refund fee are taken from your balance when the refund is accepted. If the refund later fails, the amount is returned to your balance; the refund fee is not.
Security question
Every refund is protected by a security question that the customer answers when they claim the funds with their bank. The question is What is the secret code? and the answer is a random 8-character code.
The response contains the answer in securityAnswer, encrypted with AES-256-GCM using your security key (provided by NoLimit staff). Decrypt it on your side and give the answer to the customer. On the sandbox environment the response also contains the answer in plain text in plainPassword; this field is not present in production.
Status
-
PENDING- the refund was accepted and sent. Its final status is sent to your webhook. -
INCOMPLETE- the refund could not be sent. Nothing was taken from your balance and the refund will not be retried; you can create a new refund with a newIdempotency-Key.
When the refund reaches its final status (for example COMPLETED, CANCELLED, REJECTED or DECLINED) we send it to your registered webhooks:
Possible errors:
-
400 INSUFFICIENT_FUNDS- your balance does not cover the amount plus the refund fee, the amount is not greater than 0, or the amount is more than what is left to refund on the deposit. -
400 MISSING_IDEMPOTENCY- theIdempotency-Keyheader is missing. -
401- the API key is invalid. -
404 DEPOSIT_NOT_FOUND- no completed deposit with thistransactionIdbelongs to your account, oramountis more than the deposit amount. -
409- thex-api-keyheader is missing, orIDEMPOTENCY_IN_PROGRESS. -
422 INVALID_TRANSACTION_ID-transactionIdis missing or is not a valid ID. -
500 REFUND_CREATION_FAILED- the refund could not be created, for example becauseamounthas more than 2 decimals. Please check the request and retry with a newIdempotency-Key.
Headers
Request
The transactionId of the completed deposit to refund.