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 merchant
Since 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:

Copy

Copied

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:

Copy

Copied

{
  "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:

Copy

Copied

{
	"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 the failure_reason object:

Copy

Copied

{
	"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.

Questions? Need help? Visit our support page!