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:

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 (TTL) 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 reduces the overall number of failed payments on your platform and offers the payer a chance to submit a different, valid payment method while they are still in your UI.

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.

Designate Or Identify A Card's Funding Source

BETA

Disabling the creation of debit or credit card payment methods is currently a closed BETA offering on API version 3.1.rc.1.3.

We offer a method of allowing only a credit or debit card funding source during payment method creation. Alternatively, you can simply read the value on the payment method after creation to identify its funding source.

Designate A Funding Source

When creating a new payment method with a token from the credit card iframe on POST /payment_method or POST /payments, you can set the optional field card_funding to debit or credit. The debit value will only successfully create a payment method if the card's funding source is debit, while the credit value will only successfully create a payment method if the card's funding source is credit.
Test credentials

In our stage environment, use the following test credentials in the credit card iFrame:

  • 4242424242424242 for credit
  • 4000056655665556 for debit

Your request may look like this:

Copy
Copied
{
  "type": "credit_card",
  "credit_card": {
    "card_holder": {
      "holder_name": "John Doe",
      "address": {
        "postal_code": "94122",
        "country": "US"
      }
    },
    "token": {
      "id": {"token-id"}
    },
    "card_funding": {"debit / credit"}
  }
}
If you set card_funding and card details with funding other than the specified value is sent, the error PREPAID_VALIDATION_MISMATCH will be returned and a payment_method_id will not be created.

Identify A Funding Source

Once a card has been created, you can identify its funding source on the card_funding response parameter even if you did not set the parameter during creation. Note that the value can be null, but this is a rare edge case that will only occur on very new card types / offerings that have not been incorporated in our bin lookups.

Disable Prepaid/Gift Card Payment Methods

BETA

Disabling the creation of prepaid card payment methods is currently a closed BETA offering on API version 3.1.rc.1.3.

We offer you a way to ensure that payment methods aren't being created with prepaid type cards including but not limited to: gift cards, reloadable, virtual, etc.

When creating a new payment method with a token on POST /payment_method or POST /payments, you can set the optional field bin_details.is_prepaid to false, indicating that you do not want a payment_method_id to be created if we validate that the card information submitted is a prepaid type card. Below is an example request:
Copy
Copied
{
  "type": "credit_card",
  "credit_card": {
    "card_holder": {
      "holder_name": "John Doe",
      "address": {
        "postal_code": "94122",
        "country": "US"
      }
    },
    "token": {
      "id": {"token-id"}
    },
    "bin_details": {
      "is_prepaid": false
    }
  }
}
If you set is_prepaid to false and prepaid card information is sent, the error PREPAID_VALIDATION_MISMATCH will be returned and a payment_method_id will not be created to make payments.

Reminder: This is an optional field. If is_prepaid is not specified in your API request, the default value will be null and this will allow a payment_method_id to be created regardless if it is a prepaid card or not.
Note
If is_prepaid is set to true, a payment_method_id will be created for prepaid type cards only.

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:

  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.
The process of 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 TTL of 30 minutes.

Use Plaid In A Native Mobile App

If you have our iFrame in your native mobile app, you'll need to implement some additional logic for the authentication of certain institutions. For instance, Chase no longer supports in-process webview traffic, meaning the authentication for Plaid must now occur on the Chase website/app. It is expected for more banking institutions to follow suit, but we will use Chase as the example in this section.

You'll need to implement these lines of code in your Android or iOS app to support leaving your app. The requirement to leave your app for authentication is handled by Plaid during institution selection.

Note that we do not currently support app2app or universal links, which would automatically bring the user back to your app once authentication in the banking institution app is complete. Instead, users will see a screen like the one below:

example screen once authentication flow in banking institution app is complete and user must manually navigate back to ISV app
example screen once authentication flow in banking institution app is complete and user must manually navigate back to ISV app

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, 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.

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

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 two-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.