Process Payments

Now that you’ve successfully created Merchants objects (Legal Entities and Accounts) using our API, the next step is to process a payment between a merchant and a payer. Be sure to go over and understand our Card Network Rules guide.

By using the Clear API, you’ll be able to abstract away complicated payment details, and use a simple, straightforward API that lets you describe different payment user experience flows, handle returns, fraud, and other risk operations to give better experiences to your end users.


Payment Life Cycle

 

Once a payment is created, it will end in one of the following closing statuses:

  • completed: The payment has processed and is either in the account’s available or reserved balance.
  • canceled: The payment has been canceled by the platform and will not show in the account’s balance.
  • failed: The payment has not processed due to either an error or a decline.

pending is a transitional payment status indicating that the payment is currently processing. It is assumed that a payment is in a pending status after the payments.created notification but before any other payment notifications. Your platform must subscribe to notifications in order to receive them.

Payments will progress through the different statuses according to the Payment Status Flow below:
Payment Life Cycle

Note

Issuing a refund creates a new API object which is separate from the original payment API object. The only change on the original payment API object will be in the amount_refundable parameter.


Payments can go through several different life cycles before arriving in a closing status. Please see our Payment Life Cycles to learn about the different life cycles.


Determine Payment Flows

 

As a precursor to processing payments, it’s important to first think about the user experience for payers paying on your Platform. Are they going to input credit card information every time they wish to pay for a good or service? Or will they add a credit card one-time to your platform, which you’ll then charge for every payment? Does your platform have a recurring monthly payment option? Use the table below as an approximate guide to figure out which payment flow you’ll need.

Payment Experience Payment Flow Store Payment Method Credit Card ACH
One-Time A payer on your platform enters payment information every time they wish to pay for goods or services. All payment information is added, one-time, in the Payments API call, and can be captured immediately, or at a later time. Unlike the other two options, there is no need to create a Payments Method option first. While this means that you won’t have to store the user’s payment method, users will have a less seamless experience. No No additional information is needed. No additional information is needed.
Card On File A payer on your platform enters payment information one time, which you’ll represent as a Payment Method in our API. From there, you can use the ID of the Payment Method to charge payments by calling the Payments endpoint. Yes Use the card_on_file parameter per card network mandates. While ACH payment methods can be stored on file for future payments, no additional information is needed.
Recurring A payer on your platform enters payment information one time. Unlike Card on File, the user will be billed at a fixed time interval. Like Card on File, you will need to represent payment information using the Payment Method first, then call the Payments API. Yes Use the recurring parameter per card network mandates. While ACH payment methods can be used for recurring payments, no additional information is needed.

Be sure to review our Security Certification to ensure that you are prepared to meet the relevant PCI requirements.

Payment Method IDs allows for the creation and execution of payments.

When interfacing with the /payments and /payment_methods endpoints, you have an option to collect data using tokenization, instead of capturing raw information like credit card numbers. We always recommend using Tokenization, but will cover both methods. Note, we currently support credit cards and bank accounts as accepted form of payments.


Process Credit Card Payments

 

When processing credit card payments that will be used again in the future, Tokenization allows you to securely store the card for future use. Here, we’ll go over the two methods of tokenization offered for credit card payments:

Note

If you are approved for a Server to Server Integration, please see our Server to Server version of Process Credit Card Payments and then skip ahead to the next section in this article.

Method 1: Custom UI

 

For this section, we’ll implement the Card on File flow. A more detailed view of the flow is below:

  • Create a Payment Method by calling /payment_methods (via Tokenization), which contains the payer’s credit card or payment bank.
  • Store payment method ID for user.
  • When payer is ready to buy, create a Payment by calling /payments, using payment method ID.

For testing purposes, if you want to use default values and not your Credit Card, simply use the values listed in the testing section here.

First, we’ll create a Payment Method.

WePay.tokens.create({
  "resource": "payment_methods",
  "payment_methods": {
    "type": "credit_card",
    "credit_card": {
      "card_holder": {
        "holder_name": "Test Test",
        "email": "foo@bar.com",
        "address": {
          "country": "US",
          "postal_code": "94025"
        }
      },
      "card_number": "4111111111111111", // Visa test number.
      "expiration_month": 4,
      "expiration_year": 2023,
      "cvv": "007",
      "virtual_terminal_mode": "web",
      "auto_update": false
    }
  }
}, {}, function(response) {
  console.log(response);
});

The response contains various information, including a token, which looks something like payment_methods-f4059a38-5640-41f3-a426-ef915eacaefa.

At this point, the payer has an established payment method, and your platform has a token for the user to create payments.

Now, we’ll send a POST to /payments. Before we get into the body of the call, we’re going to add a unique-key to the header, so that a payment isn’t executed twice during downtime. The value, of course, can be anything, as long as it’s unique.

{
	"account_id": "YOUR-ACCOUNT-ID-HERE",
	"amount": 1000,
	"currency": "USD",
	"payment_method": {
		"token": {
			"id": "payment_methods-YOUR-TOKEN-HERE"
		}
	},
	“fee_amount”: 200
}

Once you execute this call, you’ll have successfully created a payment for the amount of $10, with a fee of $2, for a total of $8 going to the merchant. The $2 fee goes to you, as the platform. If it is not specified, the Merchant receives $10 total.

There are a couple of important things to clarify in this call. First, we did not add auto_capture, because the default is true. The behavior of auto_capture being true means that WePay will execute the payment immediately. If you set this to false, you would use the payment ID and call payments/id/capture, at a later time so that funds would be captured.

The second thing to discuss is the fee_amount. This is the platform setting the fee for processing payment, with a hard limit of 20% of the transaction amount. In the above example, the amount to charge is 1000 ($10), and the fee is 200 ($2). We cap the fee at a maximum of 20% of the total amount. 201 ($2.01) wouldn’t work, but 199 ($1.99) would.

In terms of processing, WePay will take the processing fee from the $2 (the default is 2.9% + $0.30 per transaction, but check with your WePay account manager for the most up to date fees), while the rest is given to your platform.

Method 2: iFrames

 

The iFrame payment method offers you the ability to reduce your PCI scope the most while collecting payments. At a high level, iFrames work like this:

  • Customers of your platform navigate to your checkout page, where they will enter Credit Card information.
  • You load WePay’s Javascript SDK, and append the credit card iFrame to your page.
  • Customer enters information, and on submit, you call tokenize. This returns a token, which you then take to your server, which then can be sent to WePay’s API to execute a payment.

All payment information is entered and stored on WePay servers, and not your platform. While this reduces your PCI burden the most, it gives you less control over the user experience relative to Tokenization.

If you haven’t already, follow the steps laid out here to initialize the Javascript SDK. Once your page has initialized the SDK, the next step is to define the div in which the credit card iFrame will be injected.

<body>
...

<div id="credit-card-iframe">

</div>
...
<div id="token">

</div>
...
</body>

From this, we will call WePay.createCreditCardIframe(). The first argument takes the ID of the div you wish to inject the iFrame, and the second argument takes a Javascript object to customize the CSS. The default for the second argument is null.

Here’s a sample object for customization:

var options = {
	'custom_style' : {
		'styles': {
			'base': {
				'border-color': '#ccc',
				'transition': ' border-color 0.6s linear, border-width 0.6s linear',
				'border-radius': '5px',
				':hover': {
					'border-color': 'black'
					},
					':focus': {
						'border-color': '#969696'
					},
					'::placeholder': {
						'color': '#ccc'
					},
					'::selection':{
						'color': 'red'
					}
			},
			'valid': {
				'border-color': '#5ca96d',
			},
			'invalid': {
				'border-color': '#d26172',
			}
		}
	}
};

Per the example above, you can modify the following three class names:

  • base
  • valid
  • invalid

Which represent the user behavior for default viewing, valid credit card information, and invalid credit card information.

These are the modifiable CSS properties & pseudo-classes:

  • border-radius,
  • border,
  • font-size,
  • font-weight,
  • font-family,
  • font-smooth,
  • font-style,
  • font-variant,
  • letter-spacing,
  • padding,
  • text-decoration,
  • text-shadow,
  • text-transform,
  • border-color,
  • transition,
  • color,
  • appearance,
  • :hover,
  • :focus,
  • ::placeholder,
  • ::selection

In addition, attach a submit handler for your checkout submission form, and, once executed, call the creditCard variable’s tokenize function, and extract the token in the response. The response is a Promise.

creditCard.tokenize()
  .then(function (response) {
    console.log('response', response);
    var node = document.createElement('div');
    node.innerHTML = JSON.stringify(response);
    document.getElementById('token').appendChild(node);
  })
  .catch(function (error) {
    console.log('error', error);
    var node = document.createElement('div');
    node.innerHTML = JSON.stringify(error);
    document.getElementById('token').appendChild(node);
  });

With this token, you will receive a payment method ID. In order to execute a payment, send a POST to /payments like so:

{
    "amount": 3000,
    "currency": "USD",
    "account_id": "421c10ba-4e57-4dd9-a451-8da80dd62881",
    "payment_method": {
        "token": {
            "id": "payment_methods-8711b0a9-c303-40ee-aaa4-1126f8de7546"
        },
        "credit_card": {
            "card_holder": {
                "address": {
                    "country": "US",
                    "postal_code": "91945"
                },
                "email": "mary_jones@gmail.com",
                "holder_name": "Mary Jones"
            }
        }
    }
}

Example Credit Card iFrame Implementation:

To see a full sample, visit our Gist on Github.

Credit Card iFrame UI Example 1


Process ACH Payments

 

Note

As a reminder, ACH payments are currently only supported for US banks.

ACH payments will be processed by first creating a payment method, then verifying micro deposits, and finally creating a payment. WePay highly recommends tokenizing raw bank account data even though it does not fall within the scope of PCI requirements.

Note

If you are approved for a Server to Server Integration, please see our Server to Server version of Process ACH Payments and then skip ahead in this article to the next section.

First, tokenize the payment_bank_us parameter of a payment method:

WePay.tokens.create({
  "resource": "payment_methods",
  "payment_methods": {
    "type": "payment_bank_us",
    "payment_bank_us": {
      "account_holder": {
        "holder_name": "Test Test",
        "email": "foo@bar.com",
        "address": {
          "country": "US",
          "postal_code": "94025"
        }
      },
      "account_number": "124523092", // Use any 3-17 digit bank account number for testing.
      "routing_number": "021000021", // Testing US routing number
      "account_type": "checking"
    }
  }
}, {}, function(response) {
  console.log(response);
});

Store the token from the API response.

Next, create a payment method using the token parameter on the POST /payment_methods request:

{
  "token": {
    "id": "payment_methods-YOUR-TOKEN-HERE"
  },
  "custom_data": {
    "my_key": "invoice #54321"
  },
  "rbits": [{
    "properties": {
      "report_url": "example.com"
    },
    "receive_time": 1367958263,
    "source": "guidestar",
    "type": "business_report"
  }],
  "type": "payment_bank_us"
}

You’ll notice that the API response will send "status": "unverified".

Once the payment bank has been created, two micro deposits will be sent to the account holder. Provide a method for the account holder to send your platform the amounts of the micro deposits as means of verification.

Next, make a POST /payment_methods/{id}/verify_bank_deposits call using the payment method ID in the endpoint and the amounts in the JSON request body:

{
  "microdeposits": [10, 55]
}

On a success, the API response will send "status": "verified". Once a payment bank is in a verified status, you can use it in POST /payments calls to process ACH payments.


Capture Authorized Payments

 

The above examples showcase payment flows where payment information is submitted and a payment is executed immediately upon the POST /payments call.

There are use cases where you’d like to authorize funds (like a deposit), but finalize payment at a later time. By sending the POST /payments call with the auto_capture parameter set to false, you will delay the payment from moving to an account’s available balance by keeping the status in pending.

In both Tokenization and iFrame payment flows, you’ll need to make a second POST call in order to update the payment status to completed. Using the payment ID, a new Unique-key, and no POST body, the second POST call will look something like this

POST /payments/{id}/capture

On a successful capture call, the payment status will become completed, and the funds will become available for settlement.


Set Notifications for Payments

 

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 payment was canceled payments.canceled Send an email to both merchant and payer that a payment was canceled.
A payment was created payments.created Card network rules and Regulation E governing electronic funds transfers stipulate that payers must always be delivered a receipt upon purchase of goods or services. There are strict requirements around what information must be included in the payer’s receipt. Send notification to payer.
A payment has failed payments.failed The payment is failed by WePay because of risk and fraud, or a possible compliance violation. Notification to the merchant is required, and notification to the payer is recommended. The response to GET /payments/{id} includes a parameter, failure_reason, which contains a reason why the payment was failed. The failure reason provides context for the end user communication. E-check returns occur when an e-check payment (also known as an ACH payment) is unsuccessful and gets “returned” to the customer. E-check returns occur because of (1) bank system errors, (2) suspected fraud, or (3) incorrectly submitted information. Merchants must be notified so they may attempt to collect the payment via another method of payment. Notifying payers of the e-check return is a best practice.

 

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


Now that you can execute payments, let’s figure out how to manage Payment Operations. Questions? Need help? Visit our support page!