Create Payment Methods
In general, there are two steps to processing payments:
- Create a payment method
- 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:
- 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.
- 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
Once a payment method token ID is returned, you have two options:
- Convert the token into a Payment Method (continue reading this article)
- 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 thetrigger_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 aPOST /payment_methods
request with the following information:{
"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"
}
}
credit_card
object, as the credit card iFrame only tokenizes PCI data.Tokenize Bank Accounts
Note
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.
- 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
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 theappID
you provide in line 2 of the JS below. Here is a preview of what the Plaid light box would look like:

Prerequisites
- Stage app ID
- Stage login credentials:
- username:
user_good
- password:
pass_good
- username:
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.
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"
}
Note
Payment Method tokens have a TTL of 30 minutes.
Convert Plaid Tokens
To convert the bank account token into a Payment Method API object, use it in aPOST /payment_methods
request with the following information:{
"token": {
"id": "{payment-method-token-id-from-JS-response}"
}
}
"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 withavoid_micro_deposits: false
, then users may opt for the manual verification flow. You can test this flow yourself:Prerequisites
- Stage app ID
- Select "Manually enter account & routing info" at the bottom of the Plaid light box
- Test payment bank credentials
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 aPOST /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:{
"microdeposits": [10, 55] // Use 10 and 55 in stage
}
"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:
{
"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."
}]
}
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.