Create a Plaid integration

Plaid's Auth product allows merchants to verify a customer's bank credentials, and simplifies the process of providing these credentials for the customer.

Prerequisites

  • A gateway account configured in Rebilly that supports ACH. For the purpose of this guide, we will be using the TestProcessor.

Setting up Plaid

  1. Sign in to your Plaid Dashboard.
  2. In the top navigation bar, click Team settings > Application.
  3. Add your application information, then click Save changes.
  4. In the top navigation bar, click Customize > Application.
  5. Customize your Plaid link. For guidance, see Link best practices.
  6. In the top navigation bar, click Team settings > Keys. Use these credentials in the next step.

Connect your Plaid to Rebilly

  1. In your browser, in a new tab, go to Rebilly.
  2. In the left navigation bar, click automations icon, click Integrations, and then click Apps.
  3. In the list of available integrations, on the right of Plaid, click Settings.
  4. Enter your Client ID and Secret key, and click Save.

Creating a Plaid transaction

In this guide, we'll interact with the API to collect ACH credentials and complete a transaction in 3 steps:

  • Upsert a customer
  • Create a transaction
  • Follow the approval URL to complete the transaction

This guide will take about 10 minutes.

Upsert customer

First, we will upsert the customer. It is a best practice to upsert the customer. In the case of a duplicate customer ID, the customer record will be updated.

You'll need:

  • Your websiteId
  • Your organizationId
  • Your secret API key - Note: this will be pre populated if you are logged into the Rebilly app in the sandbox environment.

Go to the upsert a customer with a predefined ID API, and use the "Try it" console to create your customer.

Try it console

Body

Only a few pieces of information are required at this point. In this example, we are using Redocly as our organization, and our customer is Benjamin Franklin.

Replace "redocly.com" with your own website ID.

Copy
Copied
{
  "websiteId": "redocly.com",
  "primaryAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin"
  }
}

Parameters

In the parameters tab, add your customerId and the organizationId.

upsert customer parameters

attention

Before you click send, be sure that your target is set to the correct environment. The target is set as the sandbox server by default.

Click send to submit your request.

Response

We created our customer. Now, let's inspect that API response.

The customer has an id, and that should match what we supplied in the path parameter of the PUT request to upsert the customer.

Create a transaction

Next, we'll create a pending transaction using the ACH method that will be completed using the hosted form in the last step.

You'll need:

  • Your websiteId
  • Your organizationId
  • The customerId you created in the first step

Go to the create a transaction API and use the "Try it" console to create a transaction.

Enter your websiteId and customerId.

You can create the transaction for any amount, and any currency that is supported by your TestProcessor that is configured to support ACH. For this example, we'll use $75 USD as our amount and currency.

Under the payment instruction we will supply the method of payment we would like to accept using the hosted payment form, ACH.

Enter a billing address for your customer, Benjamin Franklin.

The requestId can be any string of values, but it must be unique for each transaction created. If you create multiple transactions, enter a unique requestId for each request.

The notificationURL and redirectURL are important for supporting this offsite payment. For this example, we will leave the default URLs, http://example.com.

Copy
Copied
{
  "websiteId": "redocly.com",
  "customerId": "benjaminfranklin",
  "currency": "USD",
  "amount": 75,
  "paymentInstruction": {
    "methods": ["ach"]
  },
  "billingAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": null,
    "address": "123 Main St.",
    "address2": null,
    "city": "Boston",
    "region": "MA",
    "country": "US",
    "postalCode": "02101"
  },
  "requestId": "1234",
  "notificationUrl": "http://example.com",
  "redirectUrl": "http://example.com",
  "isProcessedOutside": false,
  "type": "sale"
}

Parameters

Under the parameters tab, enter your Organization-Id.

Then, click send.

Response

You have created a transaction with an unknown result and a waiting-approval status.

Scroll to near the bottom of the response, locate the _links. In this section, you will find the approval URL. This link will be used to complete the payment.

approval URL

The link will look like this:

https://sandbox.secure-payments.app/payments/approval/91b8e739-f333-47ea-8d92-176cbc247e1a/b9ebd7b3261842daba15fffc65ba992a/

attention

This is an expired link

Copy this URL to your clipboard.

Complete the transaction

Now, we will complete the payment using the hosted payment form.

You'll need:

  • The approval URL generated in the previous step.
  • A test log in (provided below).

Follow the approval URL:

  1. Paste the approvalURL into a new browser window or tab.
  2. Select any bank.
  3. Enter the test credentials below:
Copy
Copied
username: user_good
password: pass_good
  1. Submit the form and the hosted form will PATCH the transaction with the credential hash from Plaid.

Plaid user journey

Plaid user journey select bank

Plaid user journey enter credentials

Your transaction is now complete!

Check the customer record in the Rebilly app, and you will see all of the steps recorded in the customer timeline.