# Account Boarding API

## Overview <a href="#overview" id="overview"></a>

The Sola Account Boarding API gives ISV partners the ability to board PayFac accounts directly through their system, rather than from the Partner Portal. Using the Account Boarding API, ISVs can build a form within their system for collecting all the necessary merchant data to onboard Sola Go accounts. Once the ISV submits the application via the API, it is passed along to Sola for instant approval.

This page outlines the configuration process for integrating with Sola's Account Boarding API.

{% hint style="info" %}
[See this API on Swagger UI](https://psapi.cardknox.com/boarding/v1/swagger/index.html)

Visualize and interact with the API using Swagger UI. Please note that only sandbox keys may be used when submitting accounts and the `Signature.Token` field is not required.
{% endhint %}

## API Endpoints <a href="#api-endpoints" id="api-endpoints"></a>

### GetTierNames <a href="#gettiers" id="gettiers"></a>

**URL**: <https://psapi.cardknox.com/boarding/v1/GetTierNames>

**Description:** The GetTierNames endpoint gives a list of available tiers that can be passed along to the SubmitGoApp request.

**Method**: POST

**Input**: JSON

#### Request **Body** <a href="#request" id="request"></a>

| **Parameter** | **Type** | **Description**            | **Required** |
| ------------- | -------- | -------------------------- | ------------ |
| ApiKey        | String   | Authentication credentials | True         |

#### Sample Request: <a href="#response" id="response"></a>

```
{
  "apiKey": "0d48f767f1d34d088ae59a214fe11e25"
}
```

#### Response <a href="#response" id="response"></a>

| **Parameter** | **Description**                                    |
| ------------- | -------------------------------------------------- |
| `status`      | <ul><li>Success</li><li>Error</li></ul>            |
| `refnum`      |                                                    |
| `error`       | <ul><li>Error Code</li><li>Error Message</li></ul> |
| `tiers`       | List of available tiers                            |

**Sample Success Response:**

```
{
  "tiers": [
    "123_tier1",
    "123_tier2"
  ],    
  "refnum": "brd258465289",
  "status": "Success"
}
```

**Sample Error Response:**

```
{    
  "refnum": "brd258465289", 
  "status": "Error",   
  "error": {     
    "errorCode": "AccessDenied",    
    "errorMessages": [        
      "Access Denied"       
    ]   
  }
}
```

### SubmitGoApp <a href="#submitgoapp" id="submitgoapp"></a>

**URL**: <https://psapi.cardknox.com/boarding/v1/SubmitGoApp>

{% hint style="info" %}
The SubmitGoApp end point will create a GoPlus Application.
{% endhint %}

**Description:**

The SubmitGoApp endpoint validates the request and generates an application if the account associated with the API key is authorized to board Sola Go accounts. If it is a Sandbox request, the equipment will be created immediately.

**Method**: POST

**Input**: JSON

#### Request <a href="#request.1" id="request.1"></a>

| **Parameter**               | **Type** | **Description**                                                                                                                                                                    | **Required** |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| ApiKey                      | String   | Authentication Key                                                                                                                                                                 | True         |
| TierName                    | String   | Name of tier                                                                                                                                                                       | True         |
| CorporateName               | String   | Business’s legal name                                                                                                                                                              | True         |
| DBAName                     | String   | Business’s DBA Name, if no DBA default to CorporateName                                                                                                                            | True         |
| AnnualCreditCardSales       | Number   | Credit card sales for the last full year                                                                                                                                           | False        |
| OwnershipType               | Enum     | <p>Ownership structure<br></p><p>Valid values are:</p><ul><li>SoleProprietor</li><li>Partnership</li><li>Corporation</li><li>SoleOwnership</li><li>LLC</li><li>NonProfit</li></ul> | True         |
| BusinessStartDate           | Date     | Start date of the business in YYYY-MM-DD format                                                                                                                                    | True         |
| AgentName                   | String   | Full name of primary agent                                                                                                                                                         | False        |
| AgentEmail                  | String   | Email address of primary agent                                                                                                                                                     | False        |
| Website                     | String   | <p>Business website<br><br>\*Required field if Ecommerce tier is being used</p>                                                                                                    | False        |
| TaxId                       | String   | Business EIN / Tax Identification Number                                                                                                                                           | True         |
| BusinessEmail               | String   | Business email address                                                                                                                                                             | True         |
| BusinessPhone               | String   | Business phone number (format: 000-000-0000)                                                                                                                                       | True         |
| BusinessAddress             | Object   | Object containing business address fields                                                                                                                                          | True         |
| MailingAddress              | Object   | Object containing business mailing address fields                                                                                                                                  | True         |
| ProductSold                 | String   | Short description of product sold                                                                                                                                                  | True         |
| BankingInformation          | Object   | Object containing banking information including bank name, routing number, and account number                                                                                      | True         |
| SecondaryBankingInformation | Object   | Object containing banking information including bank name, routing number, and account number                                                                                      | False        |
| SignerInformationList       | Object   | Object containing signer information                                                                                                                                               | True         |
| Signature                   | Object   | <p>Signature Object contains the Token string.<br><br>Token is from the terms and conditions confirmation.</p><p>For production accounts, it must be set to a valid value.</p>     | True         |
| AverageTicket               | Number   | Average value of each sale                                                                                                                                                         | True         |
| MonthlySalesVolume          | Number   | Credit card sales for the last full month                                                                                                                                          | True         |
| HighTicket                  | Number   | Largest ticket size                                                                                                                                                                | True         |

[Click here](/api/account-boarding-api/account-boarding-merchant-agreement.md) for more information on how to obtain tokens.

**BankingDetails**

| **Field Name** | **Description**                                             |
| -------------- | ----------------------------------------------------------- |
| BankName       | String, Required                                            |
| RoutingNumber  | String, Required, must be a valid 9-digit routing number    |
| AccountNumber  | String, Required, numeric value between 6 and 17 characters |

\
**SignerDetails**

| **Field Name**      | **Description**                                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SSN                 | String, Required                                                                                                                                                                          |
| DateOfBirth         | Date, Required, minimum age is 18                                                                                                                                                         |
| FirstName           | String, Required                                                                                                                                                                          |
| LastName            | String, Required                                                                                                                                                                          |
| Address             | Address, Required                                                                                                                                                                         |
| OwnershipPercentage | Decimal, Required                                                                                                                                                                         |
| Title               | <p>String, Required</p><p>Valid Values:</p><ul><li>Treasurer</li><li>Owner</li><li>Partner</li><li>CEO</li><li>Secretary</li><li>Director</li><li>Other</li><li>Sole Proprieter</li></ul> |
| OwnerCellPhone      | String, Required (format: 000-000-0000)                                                                                                                                                   |

\
**Address**

| **Field Name** | **Description**                      |
| -------------- | ------------------------------------ |
| StreetAddress  | String, Required                     |
| City           | String, Required                     |
| State          | String, Required, 2 digit state code |
| Zip            | String, Required, 5 digits           |
| Country        | String, Optional                     |

\
**Signature**

| **Field Name** | **Description**                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Token          | <p>Token from the terms and conditions confirmation, Required</p><p>For production accounts, it must be set to a valid value</p> |

**Sample Request**

```json
{
  "apiKey": "{{API_KEY}}",
  "tierName": "{{TIER}}",
  "corporateName": "Acme Corp",
  "dbaName": "Acme Corporation",
  "annualCreditCardSales": "80000",
  "monthlySalesVolume": 1000,
  "highTicket": 500,
  "averageTicket": 250,
  "ownershipType": "corporation",
  "businessStartDate": "2005-08-01",
  "agentName": "John Smith",
  "agentEmail": "john.smith@test.com",
  "website": "http://www.acmecorporation.com/",
  "taxId": "225555555",
  "businessEmail": "robert@acmecorporation.com",
  "businessPhone": "800-555-1212",
  "businessAddress": {
    "streetAddress": "1213 Main Street",
    "city": "Anytown",
    "state": "AL",
    "zip": "11111",
    "country": "United States"
  },
  "mailingAddress": {
    "streetAddress": "1213 Main Street",
    "city": "Anytown",
    "state": "AL",
    "zip": "11111",
    "country": "United States"
  },
  "productSold": "Convenience Goods",
  "bankingInformation": {
    "bankName": "Chase",
    "routingNumber": "021000021",
    "accountNumber": "454545454545"
  },
  "secondaryBankingInformation": {
    "bankName": "Chase",
    "routingNumber": "121122676",
    "accountNumber": "898989898989"
  },
  "signerInformationList": [
    {
      "ssn": "115668989",
      "dateOfBirth": "1955-07-14",
      "firstName": "Robert",
      "lastName": "Brown",
      "address": {
        "streetAddress": "1213 Main Street",
        "city": "Anytown",
        "state": "AL",
        "zip": "11111",
        "country": "United States"
      },
      "ownershipPercentage": 100,
      "title": "Owner",
      "ownerCellPhone": "222-333-4444"
    }
  ],
  "signature": {
    "token": ""
  }
}
```

#### Response <a href="#response.1" id="response.1"></a>

| **Parameter** | **Description**                                                      |
| ------------- | -------------------------------------------------------------------- |
| Status        | <ul><li>Success</li><li>Error</li></ul>                              |
| Refnum        |                                                                      |
| Error         | <ul><li>Error Code</li><li>Error Messages - List of errors</li></ul> |
| AppId         |                                                                      |

**Sample Success Response**&#x20;

```json
{
  "appId": 9854,
  "refnum": "brd221002160",
  "status": "Success"
}
```

**Sample Error Response:**

```json
{
  "status": "Error",
  "error": {
    "errorCode": "BadRequest",
    "errorMessages": [            
      "BusinessAddress.State: The State field is required.",            
      "SignerInformationList[0].SSN: The SSN field is required."        
    ]    
  }
}
```

### Merchant’s Documents Submission Endpoints

#### **Description**:

In some cases, in order to complete a merchant’s onboarding, additional documentation is required. For such cases we provide two (2) additional endpoints that work together: GetFileUploadData and TransferFile

#### How to use endpoints to submit additional merchant information:

1. Call GetFileUploadData endpoint
2. Encrypt the file using key and IV from GetFileUploadData response
3. Upload the encrypted file using the pre-signed S3 URL returned in step 1
4. Call the TransferFile endpoint

**Sample code to encrypt file:**

```javascript
function encryptFile(file, encryptionKey, encryptionIv) {
    return new Promise(resolve => {
    const reader = new FileReader();
    reader.onload = function(f) {
        const contentBytes = new Uint8Array(reader.result);
        const aesCbc = new AesJs.ModeOfOperation.cbc(encryptionKey, encryptionIv);
        var cipherText = aesCbc.encrypt((AesJs.padding.pkcs7.pad(contentBytes)));
        cipherText = new Uint8Array([...encryptionIv, ...cipherText]);
        const encryptedBlob = new Blob([cipherText])
            const encryptedFile = new File([encryptedBlob], file.name, { type: file.type })
            resolve(encryptedFile)
        }
        reader.readAsArrayBuffer(file);
    })
}
```

***

#### GetFileUploadData

**URL**: <https://psapi.cardknox.com/boarding/v1/GetFileUploadDataAsync>

**Method**: POST

**Input**: JSON

#### Request

| **Parameter** | **Description**  |
| ------------- | ---------------- |
| ApiKey        | String, Required |
| ContentType   | String, Required |
| FileName      | String, Required |

**Sample Request:**

```json
{
  "apiKey": "0d48f767f1d34d088ae59a214fe11e25",
  "contentType": "application/pdf",
  "fileName": "myDoc.pdf"
}
```

#### Response

| **Parameter** | **Description**                                                           |
| ------------- | ------------------------------------------------------------------------- |
| Status        | <ul><li>Success</li><li>Error</li></ul>                                   |
| Refnum        |                                                                           |
| Error         | <ul><li>Error Code</li><li>Error Messages - List of errors</li></ul>      |
| Url           | Temporary Presigned Url to upload your file to                            |
| Iv            | A random initialization vector used for the algorithm to encrypt the file |
| Key           | A generated random key used for the algorithm to encrypt the file         |

**Sample Response:**

```json
{
  "key": [61,224,1,137,248,140,54,146,165,186,104,80,174,88,32,192,234,250,27,24,137,254,84,226,45,85,191,68,114,114,159,164],
  "iv": [10,99,52,138,100,28,168,243,8,250,141,103,223,182,134,108],
  "url": "https://partnerportal-83c5a00e90d54c02b0245ac81bbf79a9-us-east-2-prd.s3.us-east-2.amazonaws.com/0525b1d47a.pdf?X-Amz-Expires=600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaCXVzLWVhc3QtMiJIMEYCIQDI4fDIubPYDH1DlmmlKC2hYNv%2Br9kaM%2BAaKKROLo8FmAIhAMolhwCtPjQFl0BlLPse2T4%2FlKlBAJKW84tKUNlmALFSKpgDCOv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQABoMNjYwODI4MDgyODQwIgw3vCSgTR5iPKo%2FjvQq7ALhNqOYkGO5HeaUdjkpfIcZ2UxgTBjmc5ZPdCc4tul2kjax%2BHdi5lcrkQfLtDKo6UQh4GEC%2BfYpSL0OB8%2FMfDnKMwUn6z7f1omuMNou0X7HGsBEEzXp53rv1r%2BwOkLbG5gpLoCAi9%2Fg2c7GdDp01mSqOgsL74WJ46cUCYN2Wim1ZQyteh%2BldF5ST8P3OHcHrHoxF6m0oO7V7lAZdBD32enWQ7BgT%2B4E%2B1S4ZFuFxcxc2rSVYzcbNsXG4F6uxVc%2BEA%2Fq8WmLIyJ6BE1AQwC0lfQb6pCiWju3TDCcwWPYQlU8E%2BRrRk4MHE2KT2vrWeIQd4bL30FAmodWfv8XdCTWbXZTU%2BWZjN2GLFFderFpmoHnpAqPmsvS9qXusUlmvJog6cz4l5KtfjtSM5STenLq0KL8mjOgeTwn18lXETyuwIXpOJkcVkPCVTb6mUMKmU17kGOpwBpqachqL1llkjTKhIPmijHPJkx3iSd5YrihLLkmvIK6Edr9Phku9pOXh%2FrBuR1xDlHThcmjA5YcNPWecHABSJQsw4H8zJQ2QZ8QO89SbYRVEYHo1x9eBhRPXx8NpjYMoXunD1nyuBHvDA606gp7kGvTRT8H%2Fc0G3wUxiOjWGgKgYfTUDcgpz14RgzqMBbcpROxFUhOfI5EBOyJ4kK&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAZTXDMKKMDZNJ3PWG%2F20241114%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20241114T100046Z&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=a760b50d071ff99284cejkna0a3655e65",
  "refnum": "brd221002160",
  "status": "Success"
}
```

#### TransferFile

**URL**: <https://psapi.cardknox.com/boarding/v1/TransferFileAsync>

**Method**: POST

**Input**: JSON

#### Request

| **Parameter**       | **Description**                                                                                                                                                                                                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ApiKey              | String, Required                                                                                                                                                                                                                                                                                          |
| ParentId            | <p>String, Required</p><p>AppId</p>                                                                                                                                                                                                                                                                       |
| AdditionalParentIds | List of String, Optional                                                                                                                                                                                                                                                                                  |
| FileName            | <p>String, Required</p><p>Name for the uploaded file</p>                                                                                                                                                                                                                                                  |
| FileTag             | <p>String, Required</p><p>Valid values are:</p><ul><li>"SignedMPA",</li><li>"SignaturePages",</li><li>"VoidedCheck",</li><li>"BankingStatement",</li><li>"MerchantStatement",</li><li>"ProofOfAddress",</li><li>"TaxExemption",</li><li>"CorporateDocs",</li><li>"CompanyLogo",</li><li>"Other"</li></ul> |
| FileKey             | <p>String, Required</p><p>File Key used when getting Presigned URL</p>                                                                                                                                                                                                                                    |
| FileDescription     | String, Optional                                                                                                                                                                                                                                                                                          |
| EncryptionKey       | Byte Array, Required                                                                                                                                                                                                                                                                                      |

**Sample Request:**

```json
{
  "apiKey":"0d48f767f1d34d088ae59a214fe11e25",
  "encryptionKey": [61, 224, 1, 177, 248, 138, 54, 146, 165, 196, 104, 80, 174, 88, 52, 192, 234, 250, 27, 24, 137, 254,…],
  "fileKey": "0525b1d47a.pdf",
  "fileName": "65545.pdf",
  "fileTag": "VoidedCheck",
  "parentId": 123456
}
```

#### Response

| **Parameter** | **Description**                                                      |
| ------------- | -------------------------------------------------------------------- |
| Status        | <ul><li>Success</li><li>Error</li></ul>                              |
| Refnum        |                                                                      |
| Error         | <ul><li>Error Code</li><li>Error Messages - List of errors</li></ul> |

**Sample Success Response:**

```
{
  "refnum": "brd221002160",
  "status": "Success"
}
```

### ExecuteAction

ExecuteAction will execute an Action for a given ActionName and Template

**URL**: [https://psapi.cardknox.com/boarding/v1/ExecuteAction](https://psapi.cardknox.com//boarding/v1/ExecuteAction)

**Method**: POST

**Input**: JSON

#### Request

| **Parameter** | **Description**                                                      |
| ------------- | -------------------------------------------------------------------- |
| apiKey        | Credential, Required                                                 |
| actionName    | Name of the Action, Required                                         |
| template      | A json Object containing parameters necessary to complete the Action |

**Sample Request:**

```
{
  "apiKey": "0d48f767f1d34d088ae59a214fe11e25",
  "actionName": "a01_SomeAction_xya123456ae"
}
```

#### Response

| **Parameter** | **Description**                                    |
| ------------- | -------------------------------------------------- |
| status        | <ul><li>Success</li><li>Error</li></ul>            |
| refnum        |                                                    |
| error         | <ul><li>Error Code</li><li>Error Message</li></ul> |

**Sample Success Response:**

```
{
  "refnum": "brd258465289",
  "status": "Success"
}
```

**Sample Error Response:**

```
{    
  "refnum": "brd258465289", 
  "status": "Error",   
  "error": {     
    "errorCode": "AccessDenied",    
    "errorMessages": [        
      "Access Denied"       
    ]   
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.solapayments.com/api/account-boarding-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.