Process Payments

 

BETA

Link is currently available in stage only.

Once an SMB is onboarded, they can begin processing Chase Integrated Payments. Chase Integrated Payments are accessed through your platform integration with WePay.

This guide covers all the following processing options available to you:


Tokenize Payment Methods

 

At a high level, Tokenization lets you implement the WePay Javascript Library on your front-end to avoid handling raw credit card data. The Library accepts raw payment information, interfaces with the WePay API, and returns a payment method, which you can store at the payee level to abstract payments.

1. Tokenize A Payment Method

Load the WePay Javascript Library on the page where a payer submits raw credit card or payment bank data. Once data is entered, use it to make the tokens JS call (do NOT send the data to your servers):

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);
});

WePay will respond with a payment method ID which can will then be used to process a payment.

2. Process A Payment

The payment method ID can be used to execute a payment at any point in the future in a POST /payments request to WePay:

POST /payments
{
  "account_id": "12345-67890-12345-67890-12345",  // step 5 of Merchant Onboarding
  "amount": 1000,
  "currency": "USD",
  "payment_method": {
    "token": {
      "id": "payment_methods-YOUR-TOKEN-HERE"
		}
	}
}

There is no fee in this API call as the merchant is charged a flat rate of 2.9% + 0.25, so this cannot be modified by your platform.

Be sure to subscribe to payment Notifications in order to align your platform functions with the status of payments.


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

There is no fee in this API call as the merchant is charged a flat rate of 2.9% + 0.25, so this cannot be modified by your platform.

Example Credit Card iFrame Implementation:

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

Credit Card iFrame UI Example 1

Be sure to subscribe to payment Notifications in order to align your platform functions with the status of payments.


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.

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, and WePay will send the payer a notification and UI methodto verify the payment method. The payer can verify the payment method directly through WePay’s UI, or your platform can verify the micro deposits via the API:

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

Once the payment method is verified, the API response will send "status": "verified" and the payment_methods.verified notification will be sent to your platform.

Once a payment bank is in a verified status, you can use it in POST /payments calls to process ACH payments.

Be sure to subscribe to payment Notifications in order to align your platform functions with the status of 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.

Be sure to subscribe to payment Notifications in order to align your platform functions with the status of payments.


Next Up: Now that we’ve covered Processing Payments, you are ready to Manage Payment Operations. Questions? Need help? Visit our support page!