Issue Unreferenced Refunds
Prerequisites
- This feature is a closed BETA, and requires configuration from your WePay integration team
- Existing payment from the bank account being credited to the merchant issuing the credit
- Merchant must be US-based
- Sufficient balance in the WePay Account to cover the Unreferenced Refund
Use our unreferenced refund feature, known in the industry as credit notes. Credit notes are a common method for a merchant to repay their customer in a B2B (business to business) scenario. This means that your merchants onboarded to WePay are most likely wholesalers, while their clients (payers in our system) are most likely retailers. Our unreferenced refunds feature supports the following use cases:
- Return funds due to partial delivery, partial return, etc.
- Return funds as part of a discount program
Construct The API Request
1. Use a recent Payment ID from the payer to the merchantSince we do not onboard payers, unreferenced refunds can only be issued to a method of payment that has already transacted with the merchant. To enforce this, we require a recent Payment ID on the unreferenced refund request, but the refund will not be issued against the payment. We will simply use that Payment ID to identify the associated Payment Method. To accomplish this, we recommend logging the latest payment between a payer and merchant in order to provide recent payments on these requests. As a note, race conditions will sometimes prevent you from sending the most recent payment, but we will handle these cases without throwing an error.
Conveniently, the API version the payment was created on does not matter; even if you use a payment created on 3.0, you can use it in your Unreferenced Refund request on version 3.2. Additionally, since the payment is not actually being refunded itself, the standard 7-day ACH hold does not apply.
2. Always set
fee_refund_amount
to 0
No fees should ever be returned on an unreferenced refund as there is no original payment being refunded.
3. Set the
Api-Version
header to 3.2
While the version must be
3.2
for all unreferenced refund requests, earlier versions like 3.1
and 3.0
can be used on any other requests and the version variance will not cause request failures.You can create an unreferenced refund with a request to
POST /refunds
with the following headers:curl -i -X POST \
https://stage-api.wepay.com/refunds \
-H 'Api-Version: 3.2' \
-H 'App-Id: {YOUR_API_KEY_HERE}' \
-H 'App-Token: {YOUR_API_KEY_HERE}' \
-H 'Content-Type: application/json' \
And the following JSON body:
{
"is_unreferenced_refund": true,
"amounts" : {
"total_amount" : 100,
"currency" : "USD",
"fee_refund_amount" : 0
},
"payment_id" : "{payment-id}",
"refund_reason" : "example refund reason",
"reference_id": "reference_id_0"
}
Consume The API Response
Unreferenced refunds can always be identified by the response when"payment" : null
and "is_unreferenced_refund": true
. The response will look something like this:{
"amounts" : {
"total_amount" : 100,
"currency" : "USD",
"fee_refund_amount" : 0
},
"create_time" : 1509140695,
"custom_data" : null,
"failure_reason" : null,
"id" : "021f2604-ef1e-4254-959b-54babd066830",
"order" : null,
"owner" : {
"id" : "40200612-e849-4172-8308-657cf3a0de27",
"path" : "/accounts/40200612-e849-4172-8308-657cf3a0de27",
"resource" : "accounts"
},
"path" : "/refunds/021f2604-ef1e-4254-959b-54babd066830",
"payment" : null,
"payment_method" : {
"id" : "00000000-6363-0000-0000-0000c27db2f3",
"path" : "/payment_methods/00000000-6363-0000-0000-0000c27db2f3",
"resource" : "payment_methods"
},
"pending_reasons" : null,
"refund_reason" : "example refund reason",
"resource" : "refunds",
"status" : "completed",
"txnr_app_fee_refund" : null,
"txnr_merchant_refund" : {
"id" : "3afd82e3-714d-4c5d-a43b-6446ed6689cd",
"path" : "/transaction_records/3afd82e3-714d-4c5d-a43b-6446ed6689cd",
"resource" : "transaction_records"
},
"is_unreferenced_refund": true,
"api_version": "3.2",
"reference_id": "reference_id_0"
}
Consume Asynchronous Errors
Note that you may receive the following error asynchronously on thefailure_reason
object:{
"reason_code": "DENY",
"reason_message": "Unable to issue Refund",
"details": []
}
This error may return if the WePay Account balance will not cover the Unreferenced Refund amount. That said, Unreferenced Refunds will not always result in error when the WePay Account balance is insufficient.