Connecting new merchants

Before you can generate and send Quick Bills for your customers (who aren’t already AffiniPay merchants), you must add them as AffiniPay merchants and connect to AffiniPay. You’ll:

  1. Configure your partner OAuth application.
  2. Request an access token so you can access account details for your merchant.
  3. Test your integration.
  4. Let your merchant know you’re running transactions on their behalf.

1: Configuring your partner OAuth application

To configure your partner OAuth application:

  1. Log in to the web application that corresponds to the product you’re integrating into your application.
  2. In the web application, click your name in the top-right corner and click Developers. (This part of the web application is available only to users with the Administrator or Developer role and to the merchant owner.)

  3. The My Partner Applications section on the right lists your partner OAuth applications. Locate the partner OAuth application that corresponds to your application and click Edit.
    app Note: If you don’t see any partner OAuth applications, ask AffiniPay Support to create one for you.
  4. Set the application name. This is the name your customers see when they authorize your partner OAuth application to interact with their AffiniPay, LawPay, or CPACharge account.
  5. Ensure that OAuth Enabled is selected. OAuth is required for all integrations. Do not uncheck this checkbox.
  6. Set the Redirect URI. Per the OAuth 2.0 specification, the Redirect URI is the URI to which the AffiniPay, LawPay, or CPACharge web application will redirect after successful authorization. Your web server must handle redirects to this URI.

  7. Set the Event URL, which is the endpoint on your server to which AffiniPay sends notifications and event details, such as merchant application disposition.

2: Requesting an access token

You must add your customer as an AffiniPay merchant.

Building the merchant application object

Gather information from your customer through your application and build a merchant_application JSON object.

Note: You should ask users to verify their information before submitting the merchant application. Business information that doesn’t match IRS records can have serious consequences for the merchant.

Submitting a merchant application

In your application, use the OAuth client credentials flow to request an access_token. This access_token will provide you access to the necessary API resources.

Use this jQuery plugin to capture an applicant’s signature and submit it in the merchant application JSON object. The plugin generates the value for the signature parameter in the required JSON format. See the plugin documentation for implementation instructions.

Then, POST the merchant_application JSON object to the endpoint that corresponds to the product you’re integrating into your application.

Click here to see an example.

Configuring a webhook to watch for an authorization code

As soon as AffiniPay determines whether the application is approved or declined, we’ll send an event to the redirect URL you specified in your partner OAuth application. Configure a webhook to watch for this event.

Event details include an authorization_code, which you’ll need to exchange for an access_token that will allow your application to access merchant account details and manage transactions on the merchant’s behalf.

Requesting an access token with an authorization code

Your application server needs to use the <authorization_code> to request an <access_token>. Your OAuth client library should provide a convenient way to send a POST request with the following parameters to the https://api.affinipay.com/oauth/token endpoint:

Example request
curl -X POST -H "Content-Type:application/json" https://api.affinipay.com/oauth/token -d '
{
  "client_id":"Y4QLWPO6wZag2ia8Abw7nbeLUAOgebDlfZGF1KyzgBaqAllzMtYFfP58jRxg5rp5",
  "client_secret":"4EG357enIs4m2SWKi9yfC3fQzIeOZmBTWr96ay47tqN4GUtRPYrWwxwCxwlZJbiC",
  "grant_type":"authorization_code",
  "scope":"payments",
  "redirect_uri":"https://my.partner.redirect.domain/oauth/callback",
  "code":"EiKvFkJu6rcFwOMWSqW8bWIng6EMFVD93duwn1QhgQKDvmpbA97zWFN2AfC5052R"
}'
Example response
{
  "access_token":"Msp2VL7SEGbLxT8UBWww7WUy33hLsg5Yhf5fFu8znSpPh2BbBMvXPyQkZx5TtWHd",
  "token_type":"bearer",
  "scope":"payments",
  "created_at":1464986958
}

3: Testing your integration

You can add a test attribute to the merchant application JSON object to test your application. The test attribute has two possible values:

The short delays mentioned previously are for testing purposes only. In live deployment scenarios, these delays will be many hours (or days) long as the merchant application goes through underwriting.

Since test mode doesn’t actually create a merchant application, merchant, or user in the AffiniPay system, the “fake” authorization_code cannot be exchanged for an access_token.

Tip: You should use test mode until you’re ready to process live merchant applications. Processing merchant applications may require human involvement to finalize an underwriting decision.

4: Notifying users

Send an email to the new merchant letting them know Quick Bill have been activated for their account.

Next step

Next, you’ll create a Quick Bill.