Connecting new merchants with our sign-up flow

Use this topic if you’re an AffiniPay partner with customers who aren’t already AffiniPay merchants and you want refer those customers via the AffiniPay, ClientPay, CPACharge, or LawPay sign-up flow, using a sign up button. Otherwise, see the Quickstart to decide how to connect based on your integration type.

Before you can perform transactions on behalf of 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. Start the sign-up flow.
  3. Request gateway credentials so you can perform transactions on behalf of that merchant.
  4. Let your merchant know you’re running transactions on their behalf.

Note: Before you begin, see the best practices for AffiniPay partners.

1: Configure 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. For current merchants, this is the name your customers see when they authorize your partner OAuth application to interact with their AffiniPay, ClientPay, CPACharge, or LawPay 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, ClientPay, CPACharge, or LawPay 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: Start the sign-up flow

Add a button to your application to initiate the sign-up flow.

Run the OAuth client credentials flow

Before you can submit information to our branded sign-up flow, you must use the OAuth client credentials flow to request an access_token. This access_token will provide you access to the necessary API resources. This is not the same OAuth flow that’s used for the Connect button for current merchants.

Download an OAuth client library (such as one of these https://oauth.net/code/) and configure it using the following values:

Your OAuth client library should provide a convenient way to send a POST request with the these 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":"client_credentials",
  "scope":"tenant"
}'
Example response
{
  "access_token":"IE83NL7SEGbLxT8UBWww78CSREhLsg5Yhf5fFu8znSpPh2BbBMvXPyQkZx5BU10C",
  "token_type":"bearer",
  "scope":"tenant",
  "created_at":1550789541
}

Use this access token to start the sign-up flow.

Obtain and format a Sign Up button

Add a button to your application that users will click to initiate the sign-up flow. The button must include:

For example:

Sign Up with AffiniPay

Sign Up with ClientPay

Sign Up with CPACharge

Sign Up with LawPay

Start the sign-up flow

There are brand-specific endpoints for the sign-up flow.

To start the sign-up flow, POST the following information to the appropriate brand-specific endpoint after the user clicks the Sign Up button in your application:

Note: You can also include user and business information that you already have in your application. This data will pre-populate the sign-up flow, so the user will not have to enter it themselves. See the API Reference for additional information.

The following example is for signing up users with AffiniPay. To sign up users with ClientPay, CPACharge, or LawPay be sure to use the correct endpoint.

Example request
curl -X POST -H "Content-Type:application/json" -H "Authorization: Bearer <access_token>" https://secure.affinipay.com/api/v1/merchant_applications/sign_up
{
  "reference": "1941",
  "email": "diana@example.com",
  "plan": "superplan"
}
Example response
{
    "merchant_application": {
        "id": 1941
    },
    "redirect_uri": "https://secure.affinipay.com/sso/merchant_applications/registrations?token=512..."
}

The POST returns a redirect URI for a page that is specific to you (the partner), the user, and the brand. It is available for five minutes and for one-time use only. After users are redirected to the URI, they must start the brand-specific merchant application sign-up flow, fill in any required information that has not been pre-populated, and submit their application. Afterward, they will be redirected to a thank you page.

Configure 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.

Event details include the reference used in the POST to /v1/merchant_applications/sign_up.

Testing the sign-up flow and webhooks

To test the sign-up flow and webhooks, submit an application.

  1. Send a note to AffiniPay Dev Support to let us know that you will be testing your integration.
  2. Start the sign-up flow and submit a merchant application that includes <Partner-Name> - TEST as the business name. For example, if the partner’s name is Arden Associates, the business name for the application is Arden Associates - TEST.
  3. AffiniPay Dev Support will provision the application, which will fire the webhook. Then, they will delete this test merchant.

DO NOT submit multiple applications. Instead, use this test as a final check of the sign-up portion of your integration.

3: Request gateway credentials

After the merchant application is submitted successfully, you must obtain an access token and gateway credentials so you can make transactions on behalf of the merchant.

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

Use the access token to request gateway credentials

Your OAuth access token allows your application to make calls to the Authentication API at https://secure.affinipay.com/api/v1/ and the Payment Portal API at https://api.affinipay.com. The AffiniPay Payment Gateway API, however, requires separate credentials for access.

To request credentials to access the AffiniPay Payment Gateway API, send a GET request to the https://api.affinipay.com/gateway-credentials endpoint using your access_token.

Example request

curl -X GET -H "Authorization: Bearer <access_token>" https://api.affinipay.com/gateway-credentials

Example response

{
    "application": "Example App",
    "user": {
        "first_name": "Dave",
        "last_name": "Bowen",
        "email": "devsupport@affinipay.com",
        "owner": true,
        "abilities": [
            "admin",
            "charge",
            "schedule_charge",
            "refund",
            "tag_transactions",
            "view_reports"
        ]
    },
    "merchant": {
        "name": "Themyscira Associates",
        "address": "123 Main Street",
        "additional_address": "Suite 300",
        "city": "Austin",
        "state": "TX",
        "postal_code": "02360",
        "country": "US",
        "phone": "9789879878",
        "timezone": "Eastern Time (US & Canada)",
        "website": "http://www.example.com",
        "support_email": "support@example.com",
        "support_phone": "(978) 987-9878",
        "email_success_to": "admin@example.com",
        "email_failure_to": "admin@example.com",
        "reference_required": true,
        "reference_label": "New Reference Label Name"
    },
    "test_accounts": [
        {
            "name": "Operating",
            "type": "MerchantAccount",
            "currency": "USD",
            "recurring_charges_enabled": false,
            "id": "_DVA8TyeQ9qreE_a0vpv5w",
            "public_key": "m_7LwaBGj6T52TyR60xvjgzg",
            "secret_key": "tccsidx6bf3e15blzlbtztvkx6m2v39ulrstbg5c1fgtaykf9lyzkz9nb1fcavx",
            "trust_account": "false"
        },
        {
            "name": "Trust",
            "type": "MerchantAccount",
            "currency": "USD",
            "recurring_charges_enabled": false,
            "id": "Icw6sdURR_CGF3ch3zbfrQ",
            "public_key": "m_7LwaBGj6T52TyR60xvjgzg",
            "secret_key": "tccsidx6bf3e15blzlbtztvkx6m2v39ulrstbg5c1fgtaykf9lyzkz9nb1fcavx",
            "trust_account": "true"
        },
        {
            "name": "eCheck",
            "type": "AchAccount",
            "currency": "USD",
            "recurring_charges_enabled": false,
            "id": "P4L8ytrISoKp39xecKa_Nw",
            "public_key": "m_7LwaBGj6T52TyR60xvjgzg",
            "secret_key": "tccsidx6bf3e15blzlbtztvkx6m2v39ulrstbg5c1fgtaykf9lyzkz9nb1fcavx",
            "trust_account": "false"
        }
    ],
    "live_accounts": []
}

This API returns a list of the test and live accounts associated with the authenticated user’s merchant account. Included in this information are the keys you’ll use to make calls to the AffiniPay Payment Gateway API. Save these credentials securely so your application can manage transactions on behalf of this merchant.

4: Notify users

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

Next step

Next, you’ll embed a payment form or create a payment form.