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 us and returning a unique payment method token ID to you. Likewise, the Plaid light box tokenizes the card holder's bank account information in order to use it as a payment method.

All tokenized information is entered and stored on our 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 our tools to create credit card and ACH Payment Methods.

Tokenize Credit Cards

The process of credit card tokenization follows this journey:

1. Customers of your platform navigate to your checkout page, where they will enter payment method information.
2. 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.
3. Customer enters information, and on submit, you call tokenize.
4. WePay JS returns a payment method token ID in a promise.
5. You 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:

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 (TTL) of 30 minutes.

Verify Credit Cards

Convert Credit Card Tokens

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

Tokenize Bank Accounts

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

1. Customers of your platform navigate to your checkout page, where they will enter payment method information.
2. 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.
3. Customer enters information, and on submit, you call tokenize.
4. WePay JS returns a payment method token ID in a promise.
5. You use the token ID in a /payment_methods (or /payments) request to store the token as a Payment Method API object.

Embed the Plaid Light Box

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.

Example of the Plaid light box user experience

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:

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:

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:

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"
}

Convert Plaid Tokens

{
  "token": {
    "id": "{payment-method-token-id-from-JS-response}"
  }
}

Manually Verify Bank Accounts

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

{
  "microdeposits": [10, 55] // Use 10 and 55 in stage
}

Note that only two 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:

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

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