Connecting existing merchants

Use this topic if you’re an AffiniPay partner with customers who are already AffiniPay merchants. 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 are already AffiniPay merchants), you must get their permission and then connect to AffiniPay. You will:

  1. Configure your partner OAuth application.
  2. Request an access token so you can access account details on behalf of your customer.
  3. Request gateway credentials so you can perform transactions on behalf of that merchant.

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.

2: Request an access token

You must get permission from your users to perform transactions on their behalf, using the OAuth 2.0 authorization code flow. Here’s a high-level description of this flow:

  1. In your application, a user (who is an AffiniPay, ClientPay, CPACharge, or LawPay merchant) clicks a Connect button.
  2. The user’s browser is redirected to a page that prompts the user to give your application access to the user's AffiniPay, ClientPay, CPACharge, or LawPay merchant account.

  3. After your application is granted access, the user's browser is redirected to your web server, with a URL that includes an authorization code.
  4. Your application requests an access token in exchange for the authorization code.
  5. Your application receives an access token.

Configure your OAuth client library

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 will help you run the OAuth flows.

Obtain and format a Connect button

Add a button to your application that merchants will click to initiate the authorization code flow. The button must include:

For example:

Connect with AffiniPay

Connect with ClientPay

Connect with CPACharge

Connect with LawPay

Start the authentication flow

Your client OAuth library should provide a convenient method for initiating the authorization code flow.

When a user clicks the button, the user’s browser should link to the URL for authorization redirects:

This link must also include the following parameters:

For example:

<a href=”https://secure.affinipay.com/oauth/authorize?redirect_uri=https://my.partner.redirect.domain/oauth/callback&client_id=f3ebce5fb8d5e0d4d8339d1058d11a8e0997c9943ccbd517c6dce33ab8bbdcc6 &scope=payments&response_type=code>Connect with AffiniPay</a>

Note: This example is for connecting with AffiniPay. To connect with ClientPay, CPACharge, or LawPay be sure to use the correct authorization redirects URL in the request.

The AffiniPay, ClientPay, CPACharge, or LawPay web application will respond by redirecting first to the AffiniPay, ClientPay, CPACharge, or LawPay login screen to authenticate the merchant and solicit their permission to grant you access to their account. Following successful authentication and customer approval for access, the AffiniPay, ClientPay, CPACharge, or LawPay web application will redirect to the specified redirect URL with an OAuth2 authorization code. The URL will be formatted as <partner-redirect-url>?code=<authorization-code>.

Listen for an authorization code

After the user logs in through AffiniPay, ClientPay, CPACharge, or LawPay and authorizes your partner OAuth application, the Authentication API sends an authorization_code to the Redirect URI you specified in your partner OAuth application in the following format: <partner-redirect-url>?code=<authorization-code>. You must configure your server to listen for this authorization code.

Request an access token

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:

You can access merchant account details after you receive an access token.

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",
  "redirect_uri":"https://my.partner.redirect.domain/oauth/callback",
  "code":"EiKvFkJu6rcFwOMWSqW8bWIng6EMFVD93duwn1QhgQKDvmpbA97zWFN2AfC5052R"
}'
Example response
{
  "access_token":"Msp2VL7SEGbLxT8UBWww7WUy33hLsg5Yhf5fFu8znSpPh2BbBMvXPyQkZx5TtWHd",
  "token_type":"bearer",
  "created_at":1464986958
}

3: 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.

Next step

Next, you’ll create a payment form.