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 want to sign those customers using the AffiniPay, LawPay, or CPACharge 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 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. 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, 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: 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 a merchant application, 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 LawPay

Sign Up with CPACharge

Start the sign up flow

To start the sign-up flow, POST the following information to the appropriate brand-specific endpoint:

In addition, you can POST 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.

Brand-specific endpoints include:

The POST returns a redirect URI for a page that is specific to you (the partner), the user, and the brand and is available for five minutes and for one-time use only. Send users to this page, where 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.

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.

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.

In addition, event details include the reference used in the POST to /v1/merchant_applications/sign_up.

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/. 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": "Acme Inc.",
        "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 create a payment form.