Create Payment Methods

 

In general, there are two steps to processing payments:

  1. Create a payment method
  2. Create a payment

At a high level, credit card iFrames will tokenize a credit card Payment Method by sending PCI data directly to WePay and returning a unique payment method token ID to you. Likewise, the Plaid light box allows tokenization of payers' bank account information in order to use it as a payment method.

All tokenized information is entered and stored on WePay servers, not your platform's, which is why your platform will have a lower PCI scope.

By the end of this article, you will know how to implement WePay's tools to create credit card and ACH Payment Methods.

Tokenize Credit Cards

The process of credit card tokenization follows this journey:

  • Customers of your platform navigate to your checkout page, where they will enter payment method information.
  • You load WePay's Javascript library on that checkout page, and append the desired payment method tools (i.e. credit card iFrame, Plaid light box, etc) to your user interface.
  • Customer enters information, and on submit, you call tokenize.
  • WePay JS returns a payment method token ID in a promise.
  • Use the token ID in a /payment_methods (or /payments) request to store the token as a Payment Method API object

Embed The Credit Card iFrame

Here is an interactive demo of the credit card iFrame, along with the additional billing information that you'll need to collect. To successfully run a test, you'll need the following:

Prerequisites
  • Stage app ID
    • If you don't already have Stage API credentials, then register for them in the Partner Center
    • Insert app ID in the JS file at line 2
  • Test card credentials
    • Use any credentials listed here
    • Paste into the rendered credit card iFrame
Find more information on styling the credit card iFrame in this guide.

Once a payment method token ID is returned, you have two options:

  1. Convert the token into a Payment Method (continue reading this article)
  2. Immediately create a Payment with the token (continue to the Process Payments article)

Whichever route you choose, the token must be used in an API request within 30 minutes of creation, as tokens have a time-to-live of 30 minutes.

Verify Credit Cards

Once you have a payment method, a successful $0 authorization must occur before you can use that payment method to create a payment. The $0 auth occurs automatically when the trigger_verification parameter is set to true (default) on the WePay.tokens.create JS call. Successful authorizations are reflected when the Payment Method API object has "status": "verified".Note: trigger_verification defaults to true, and we strongly discourage sending a false value. Checking the validity of a credit card upon submission offers the payer a chance to submit a different, valid payment method while they are still in your UI, in addition to reducing the overall number of failed payments on your platform.

Convert Credit Card Tokens

To convert the credit card token into a Payment Method API object, use it in a POST /payment_methods request with the following information:
Copy
Copied
{
  "type": "credit_card",
  "credit_card": {
    "card_holder": {
      "holder_name": "Lorem Ipsum",
      "email": "example@example.com",
      "address": {
        "line1": "123 Fake St",
        "region": "CA",
        "postal_code": "90210",
        "country": "US"
      }
    }
  },
  "token": {
    "id": "payment-method-token-id-from-JS-response"
  }
}
Be sure to use the billing address details that the payer submitted on your checkout page in the credit_card object, as the credit card iFrame only tokenizes PCI data.

Tokenize Bank Accounts

Note
When a payment method is created using POST /payment_methods, the last_four variable that is returned will be the last four numbers of the bank account. However, if you have verified your account via Plaid, this might be the last four numbers of your tokenized bank account number (TAN).

The process of bank account tokenization via Plaid follows this journey:

  • Customers of your platform navigate to your checkout page, where they will enter payment method information.
  • You load WePay's Javascript library on that checkout page, and append the desired payment method tools (i.e. credit card iFrame, Plaid light box, etc) to your user interface.
  • Customer enters information, and on submit, you call tokenize.
  • WePay JS returns a payment method token ID in a promise.
  • Use the token ID in a /payment_methods (or /payments) request to store the token as a Payment Method API object
The process od bank account tokenization without Plaid requires an additional step, covered here

Embed the Plaid Light Box

Note

Only banks in the US can be used as bank account payment methods.

Leveraging the Plaid modal allows payers to use their bank account to pay by securely logging in to their online banking portal. The login verification is what we call instant verification.

Plaid instant verification also allows your platform to have a customized user experience. The Plaid light box displays the name of your application based on the appID you provide in line 2 of the JS below. Here is a preview of what the Plaid light box would look like:Example of the Plaid light box user experience
Example of the Plaid light box user experience
Prerequisites
  • Stage app ID
  • Stage login credentials:
    • username: user_good
    • password: pass_good

Note: Due to the nature of the Plaid modal UI, it's best to click through this pen and view it on the CodePen site.

To start integrating the Plaid modal, initialize the WePay JS library like so:
Copy
Copied
var myAppId = "{your_app_id}"; //insert your app ID
var apiVersion = "3.0";
var error = WePay.configure("stage", myAppId, apiVersion);
if (error) {
    console.log(error);
}

To force payers through the Plaid flow (rather than the manual payment bank verification flow), create the Plaid modal with the "avoid microdeposits" option like so:

Copy
Copied
var paymentBankLightBox =
    WePay.createPaymentBankLightBox(
      function(data) {
          console.log('plaid event:', data);
      },
      {'avoid_micro_deposits': true});

if (paymentBankLightBox.error_code) {
	// error, light box could not be created.
      console.error(paymentBankLightBox);
}

Next, tokenize the Plaid response:

Copy
Copied
paymentBankLightBox
    .tokenize()
    .then(
        function(response) {
	      // payment method token created successfully.
            console.log('payment method token:', response);
        })
    .catch(
        function(error) {
            // something went wrong while creating the token.
            console.log('error:', error);
        });

On a successful login through Plaid, the WePay JS will return the following information in a promise:

Copy
Copied
var response = {
    "id":"payment_methods-{token-id}",
    "resource":"tokens",
    "path":null,
    "owner": {
        "id":"145948",
        "resource":"applications",
        "path":null
    },
    "create_time":12345, //UNIX timestamp
    "expire_time":1234530, //UNIX timestamp + 30 days
    "api_version":"3.0"
}
Note

Payment Method tokens have a time-to-live (TTL) of 30 minutes.

Convert Plaid Tokens

To convert the bank account token into a Payment Method API object, use it in a POST /payment_methods request with the following information:
Copy
Copied
{
  "token": {
    "id": "{payment-method-token-id-from-JS-response}"
  }
}
The API response will contain "status": "verified", along with an id. That Payment Method ID can now be used to create a Payment.

Manually Verify Bank Accounts

If you configure the Plaid light box with avoid_micro_deposits: false, then users may opt for the manual verification flow. You can test this flow yourself:
Prerequisites

Once the payment bank has been created, WePay will send two micro deposits will to the account. It can take 2-5 business days for these amounts to appear in a bank account's statement. Provide a method for the account holder to send your platform the amounts of the micro deposits as means of verification.

Once the user has submitted the micro deposit amounts to you, make a POST /payment_methods/{id}/verify_bank_deposits request. You'll use the payment method ID in the endpoint, and the micro deposit amounts in the JSON request body:
Copy
Copied
{
  "microdeposits": [10, 55] // Use 10 and 55 in stage
}
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.

Note that only 2 attempts to verify a Payment Method can be made before the object will block further attempts. After the 2nd failed attempt to verify, the following error will return:

Copy
Copied
{
  "error_code": "INVALID_PARAMS",
  "error_message": "Invalid parameter(s).",
  "details": [{
    "target": ["payment_methods"],
    "target_type": "HTTP_REQUEST_PATH",
    "reason_code": "ID_NOT_FOUND",
    "message": "ID 00000000-6261-5553-0000-00000003557c not found."
  }]
}
Additionally, the payment_methods.microdeposit_verification_failed Notification event topic will fire, so long as you've subscribed to the topic.The 2-attempt constraint exists to protect against fraud in the ACH/Echeck sphere. If this occurs, the payer should double check their bank account credentials and resubmit payment. To this end, send a DELETE /payment_methods/id request to remove the abandoned Payment Method.

Now that you have a payment method token, you can process a payment.