Manage Payment Operations

 

When you build payments on your platform, you’ll need to handle operational aspects, like when a Payer returns an item or a dispute is created. The Clear API provides various endpoints to help you manage and resolve operations like chargebacks and disputes.

Use this document to help you build a disputes and refunds flow for your Merchants on your platform. By providing a seamless user experience for challenging and conceding disputes, your Merchants will overcome cash flow issues faster, and gain more predictability and transparency into their funds.


Basics

 

From an operational perspective, you’ll have to handle the following flows:

  • Conceding chargebacks
  • Disputing chargebacks
  • Issuing refunds

As a hypothetical scenario, let’s say a fraudulent charge appears on a payer’s credit card. They can challenge the transaction with their credit card company, which is considered a chargeback. When a payer files a chargeback, WePay is notified. We create a dispute and debit your merchant’s account.

As we notify you through our Notifications system, you’ll need to provide a way for your merchant to concede or challenge the dispute, and pass that information along back to our API. Our operations team reviews the chargeback, and sends a notification containing the status of the chargeback (whether the dispute was won or not).

Outside of fraudulent charges, a payer can also return a good or service bought on your platform. In order to handle this scenario, you’ll need to issue a refund from merchant to payer, using the API.

In order to manage these functions, it is important to use the amount_refunded and amount_disputed response parameters on payment resources. These help give insight into what has already happened with a given payment, and what actions can be taken.

Note

If a partial dispute occurs, it is not possible to issue partial refunds for any remaining balance of that payment.

Here are a few scenarios which the amount_refunded and amount_disputed response parameters can help to navigate:

Scenario amount status amount_refunded amount_disputed
Payment completed $100 completed $0 $0
Payment pending $100 pending $0 $0
Payment failed $100 failed $0 $0
Payment canceled $100 canceled $0 $0
Payment completed and then fully refunded $100 completed $100 $0
Payment completed with full refund pending $100 completed $0 $0
Payment completed and then partially ($10) refunded $100 completed $10 $0
Payment completed and partial refund ($10) pending $100 completed $0 $0
Payment pending and tried refunding $100 pending $0 $0
Payment completed and then fully disputed $100 completed $0 $100
Payment completed and then partially ($10) disputed $100 completed $0 $10
Payment completed and partial ($10) dispute pending $100 completed $0 $0
Payment completed, then partially ($10) refunded, and then partially ($10) disputed $100 completed $10 $10


For more information regarding WePay payment scenarios, please see our Payment Life Cycles article.


Handle Disputes

 

Disputes are the WePay API resource which represent chargebacks and inquiries.

At a high level, disputes occur when a payer disputes a charge with their credit card issuer. When the payer takes this action, the dispute process begins and:

  • The credit card issuer notifies WePay, and WePay debits the Merchant account for the amount.
  • Your platform then receives a Notification, which contains the Dispute ID, Merchant information, and the reason for a dispute. You inform your Merchant.
  • Your platform provides UI for Merchants to upload documentation.
  • When Merchants upload a document, you call the WePay Javascript library to process and store the documents.
  • WePay’s backend stores document, and returns the ID of the document.
  • You call the disputes endpoint, with the IDs, and the Merchant’s explanation for the dispute.
  • WePay returns a notification to your platform at a point later in time, informing you if the dispute has been won or lost.
  • You communicate to your Merchant with the status of the dispute.

When a chargeback or inquiry occurs, WePay automatically generates the disputes API object and sends the disputes.created notification (assuming you’ve subscribed). Note: In most cases, the disputes.created notification will be immediately followed by the disputes.funds_withdrawn notification.

Chargebacks

A chargeback (also known as a reversal) is a form of consumer protection where card holders may file a complaint with their card issuer about a specific transaction on their statement. Once the card holder files a complaint, the issuing bank starts an investigation which includes crediting the funds back to the card holder’s account. Once the credit is requested, WePay debits the merchant account for the required amount.

Essentially, the chargeback life cycle looks like this:

chargeback flow

Additional phases may occur after phase 2, but the above is more typical. For more complex scenarios, please see our Disputes Deep Dive resource.

When a chargeback for a WePay payment occurs:

  • WePay will send a disputes.created and a disputes.funds_withdrawn notification (be sure to subscribe).
    • You, the platform, are then responsible for the required communications about the chargeback with the merchant and payer, per the Notifications guide.
  • All fees are reversed (identical to a full refund).
  • A $15 non-refundable chargeback fee is applied.
  • The chargeback net (full amount less fees) and chargeback fee are deducted from the merchant account.

Inquiries

An inquiry is a pre-chargeback phase specific to AmericanExpress. This phase allows AmericanExpress to investigate prior to crediting the card holder. That said, WePay preemptively debits the merchant until the inquiry is resolved. The inquiry life cycle is the same as the chargeback life cycle.

Inquiries should be responded to just like chargebacks; this is a chance for the merchant to explain the charge before AmericanExpress requires a credit, and the process of returning inquiry funds to a merchant is much smoother.

If AmericanExpress determines that the payment should be credited back to the payer, then the inquiry will be closed and a dispute with "type": "charegeback" will be issued. When an inquiry rolls into a chargeback, it goes through the chargeback life cycle again.


Responding to Disputes

 

When a merchant receives a dispute, they can respond to it in one of two ways:

You must build out UIs enabling your merchants to respond to disputes.

Challenge a Dispute

A merchant will challenge a dispute when they feel the payment should not be credited back to the payer. This process requires supporting documentation, and acceptable forms are listed here and explained below:

Documentation Type Notes
cancelation_request  
charge_back  
contract The contract between the merchant and payer showing the agreed-upon amount of payment and services/goods.
correspondence Communication between the merchant and payer.
item_description The public item description which was available prior to purchase.
itemized_receipt An itemized receipt showing the components of the total purchase amount.
invoice The invoice sent to the payer describing services/goods and the total payment amount and date.
ip_logins Logs with the payer’s IP to determine whether an account takeover occurred.
proof_of_credit If a refund/credit was already provided to the payer, provide credit documentation.
return_policy A copy of the merchant’s return policy which must be presented prior to purchase and publicly available.
refund_policy A copy of the merchant’s refund policy which must be presented prior to purchase and publicly available.
signed_contract The contract between the merchant and payer showing the agreed-upon amount of payment and services/goods, signed by the payer.
tracking For shipped goods, provide the tracking number.
written_rebuttal  

Important

The supporting documentation for a challenge must be submitted to WePay for review within 5 days of the chargeback.

Step 1: Gather Information

Create a WePay document object for each document the merchant wishes to submit. Load the WePay JS on the page where you present your document upload UI to the merchant. Call WePay.documents.create for each .jpg, .jpeg, .png, or .pdf file being uploaded. Note that each file has a size limit of 10MB, and a null file cannot be created.

Your WePay.documents.create request should look like this:

WePay.documents.create(body, headers
		,function(response){
		 console.log(response); // You can see response in the console
	});

The console response will contain document IDs to use in the next step.

At some point in your chargeback challenge UI, provide a text input for the merchant to submit their written statement explaining the challenge.

Step 2: Submit Information

To challenge a dispute, use the update dispute API request with an array of document IDs and the merchant’s written statement:

curl -X POST \
/disputes/47521346-c054-11e7-abc4-cec278b6b50a \
 -H "App-Id: 121212" \
 -H "App-Token: prod_MTAwXzk5OWIwZT666LWYwNWItNDU4MS1iZjBiL" \
 -H "Api-Version: 3.0" \
 -H "Content-Type: application/json" \
 -d '{
 	"documentation": {
 		"documents": ["docu-abc123", "docu-efg456", "docu-hij789"],
 		"explanation": "lorem ipsum dolores umbridge"
   }
 }'

Once the challenge has been submitted, the dispute status will return as pending_wepay_review.

Typically, reviews will be completed within 10 days at which point WePay will either fight the chargeback or close it for the payer.

  • If WePay fights the chargeback, evidence will be forwarded to back-end processors and the card networks. The dispute status will become awaiting_chargeback_decision.
  • If we decide to close the chargeback for the payer, the dispute status will become resolved with a resolution.type of lost.

Once WePay submits evidence to fight a dispute, issuers have 30-45 days to make a decision – although some cases may take as long as 120 days to resolve.

Concede to a Dispute

A merchant will concede a dispute when they feel it is warranted. Once a dispute has been conceded, it cannot be challenged. Experienced merchants will already know about the chargeback process and will most likely understand the terminology, but it’s important to offer education and ask for confirmations in your UI when a merchant requests to concede a chargeback.

The concede API request does not require documentation or explanation, and will look like this:

curl -X POST \
/disputes/47521346-c054-11e7-abc4-cec278b6b50a/concede \
 -H "App-Id: 121212" \
 -H "App-Token: prod_MTAwXzk5OWIwZT666LWYwNWItNDU4MS1iZjBiL" \
 -H "Api-Version: 3.0" \
 -H "Content-Type: application/json" \

The API response will contain a status of resolved and a resolution structure like this:

{
	"resolution": {
		"resolution_time": 1566932448, // Unix timestamp of resolution
		"type": "lost"
	}
}

Please see our Disputes Deep Dive resource article for more information on:


Issue Refunds

 

Another operational flow you can expect to handle is the issue refund flow. With the refunds endpoint, it’s possible to perform partial refunds or full refunds. Please note that WePay and platform fees are refunded only in full refunds; if a partial refund is issued and your platform has not explicitly opted to refund platform fees, then the amount sent in the refund call will come from the merchant.

If you’ve subscribed to refund notifications, WePay will send a notification to your platform when a refund occurs.

When a refund occurs, you’ll need to make sure you have a few things handy:

  • Payment ID
  • Refund Reason
  • Amount (could be a partial of the whole transaction, up to the whole transaction value itself)
  • Fee amount to return
  • Currency

Send a POST, with a Unique-Key, similar to the one below:

{
  "payment_id": "00000000-0000-0000-0000-000006fcd875",
  "refund_reason": "delayed shipping",
  "amounts": {
	"total_amount": 100,
	"currency": "USD",
	"fee_refund_amount": 0
  }
}

Send a POST like this (including a Unique-Key) to issue a partial refund of the net and to include all or some of the platform fees in that refund:

{
  "payment_id": "00000000-0000-0000-0000-000006fcd875",
  "refund_reason": "delayed shipping",
  "amounts": {
	"total_amount": 100,
	"currency": "USD",
	"fee_refund_amount": 50
  }
}

As a note, if your Merchant’s account is below $0, WePay will attempt to execute a recovery to bring the account back up to $0. We’ll send a notification to your platform if we execute a Recovery.

Note

It is the merchant’s responsibility to post their refund policy. WePay recommends that your platform provides a method for merchants to post their refund policy through your UI.


Manage Administrative Questions

 

As the primary payments contact for your merchants, you’ll need to be prepared to manage administrative questions. This can range from providing clarity on where a specific Payment is in the payment lifecycle, to offering reconciliation support, to updating the email address on file, and much more.

Let’s start by looking at identifying where Payment is in it’s lifecycle. Merchants may ask about a specific Payment if it is pending manual review by WePay, or if it’s simply pending capture. In order to provide information about the payment, you’ll need to look it up by making a GET /payments/{id} call to look at the status.

The status may be any one of: cancelled, failed, pending, or completed.

  • For more information on cancelled or failed Payments, examine the returned failure reasons from the previous GET call.
  • More information on pending Payments can be found in the returned pending reasons. Please note that if the pending reason is pending capture, then you’ll want to identify why and then either capture a POST /payments/{id}/capture call, or cancel with a POST /payments/{id}/cancel call as appropriate.
  • When a payment is completed and the merchant reports that it has not yet been settled, you’ll want to take a look at the Account’s outgoing pending balance. If there is an outgoing pending balance equal to or greater than the amount of the Payment(s) in question, then you can identify which pending Payout the Payment got batched with by calling GET /payouts with appropriate Payment ID like so:
{
  "payment_id": "30a5b562-9f00-4c7e-9b10-686adfc08c71"
}

Using an Account’s balances structure can be extremely useful in identifying where Payments are in the payment lifecycle.


Set Notifications for Payment Operations

 

Notifications are WePay’s way of communicating important status information with your platform in real time. The table below shows use cases where you must send communication to your merchants, once you receive a notification from WePay.

Use Case Topic What To Do
A dispute was created disputes.created A payment collected by the merchant is disputed and the payer’s credit card provider seeks to require the merchant to make good the loss on the disputed transaction. The response to GET /disputes/{id} contains a parameter, reason, which contains a reason why the dispute was created. The dispute reason provides context for the merchant communication. Merchant communication required.
A dispute was resolved disputes.resolved A dispute is resolved. The response to GET /disputes/{id} includes a parameter, resolution, which contains information about whether the merchant or payer won the dispute. The resolution field provides context for the merchant communication. Merchant communication required.

 

For a full list of notifications to set for your platform and users, please visit the Platform Setup article.


At this point, you are ready to move towards final testing and launch. Questions? Need help? Visit our support page! Questions? Need help? Visit our support page!