Create a Plaid integration

Use the Plaid Auth product to verify customers' bank credentials, and simplify 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 Plaid to Rebilly

1. In your browser, in a new tab, go to Rebilly.
2. In the left navigation bar, click App store, then click Plaid.
3. Enter your Client ID and Secret key, and click Save.

Create 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 a 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 operation, and use the "Try it" console to create your customer.

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.

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

Parameters

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

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.

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

The link will look like this:

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

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:

username: user_good
password: pass_good

4. Submit the form and the hosted form will PATCH the transaction with the service credential from Plaid.

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.