> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Third-Party Integrations in Nymble Commerce

> Learn how to connect QuickBooks Online, payment gateways, and other integrations to Nymble Commerce using the integration templates and provider API.

Nymble Commerce's integration system lets you connect payment processors, accounting software, and other third-party services through a unified API. Credentials are stored encrypted and secrets are never returned in API responses. Each integration can be tested independently before you enable it in production.

***

## Available integrations

| Type       | Provider              | Notes                                            |
| ---------- | --------------------- | ------------------------------------------------ |
| Payment    | **Authorize.Net**     | Credit card processing via Authorize.Net's API   |
| Payment    | **WorldPay (Vantiv)** | Credit card processing with hosted payment pages |
| Accounting | **QuickBooks Online** | Two-way sync of orders and invoices via OAuth    |

Additional providers can be added through the template system — contact Nymble Commerce support to request a new provider template.

***

## Integration templates

Before creating an integration, fetch the available templates to discover which fields each provider requires:

```http theme={null}
GET https://api.achievemomentum.com/api/integration-templates
Authorization: Bearer {token}
```

**Response**

```json theme={null}
{
  "templates": [
    {
      "type": "Payment",
      "provider": "AuthorizeNet",
      "displayName": "Authorize.Net",
      "description": "Accept credit and debit card payments via Authorize.Net.",
      "requiresOAuth": false,
      "documentationUrl": "https://developer.authorize.net/",
      "supportedFeatures": ["Payments", "Refunds", "SavedPaymentMethods"],
      "configurationFields": [
        {
          "key": "IsSandbox",
          "displayName": "Sandbox Mode",
          "description": "Use the Authorize.Net sandbox environment for testing.",
          "type": "Boolean",
          "required": false,
          "defaultValue": "false"
        }
      ],
      "secretFields": [
        {
          "key": "ApiLoginId",
          "displayName": "API Login ID",
          "description": "Your Authorize.Net API Login ID.",
          "required": true,
          "isSensitive": true
        },
        {
          "key": "TransactionKey",
          "displayName": "Transaction Key",
          "description": "Your Authorize.Net Transaction Key.",
          "required": true,
          "isSensitive": true
        }
      ]
    }
  ]
}
```

Each template tells you exactly which `configurationFields` (non-sensitive settings) and `secretFields` (sensitive credentials) you need to supply when creating the integration.

***

## Creating an integration

Send a `POST` request to create an integration for your organization. Supply non-sensitive settings in `configuration` and sensitive credentials in `secrets`.

```http theme={null}
POST https://api.achievemomentum.com/api/organizations/{organizationId}/integrations
Authorization: Bearer {token}
Content-Type: application/json
```

### Authorize.Net example

```json theme={null}
{
  "integrationType": "Payment",
  "provider": "AuthorizeNet",
  "displayName": "Authorize.Net (Production)",
  "isEnabled": false,
  "configuration": {
    "IsSandbox": "false"
  },
  "secrets": {
    "ApiLoginId": "YOUR_API_LOGIN_ID",
    "TransactionKey": "YOUR_TRANSACTION_KEY"
  }
}
```

**Response**

```json theme={null}
{
  "integrationId": "int_3c7f9a2e",
  "organizationId": "org_4e9b7f22",
  "integrationType": "Payment",
  "provider": "AuthorizeNet",
  "displayName": "Authorize.Net (Production)",
  "isEnabled": false,
  "createdAt": "2024-06-01T10:00:00Z"
}
```

Note that `secrets` are never included in the response — they are stored encrypted and only referenced internally.

**Key request fields:**

| Field             | Type    | Description                                                               |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `integrationType` | string  | `"Payment"`, `"Accounting"`, `"Shipping"`, etc.                           |
| `provider`        | string  | `"AuthorizeNet"`, `"QuickBooks"`, `"WorldPay"`, etc.                      |
| `displayName`     | string  | A human-readable label for this integration (shown in your dashboard)     |
| `isEnabled`       | boolean | Whether the integration is active; set to `false` until tested            |
| `configuration`   | object  | Non-sensitive settings (e.g., `IsSandbox`, `MarketCode`)                  |
| `secrets`         | object  | Sensitive credentials — stored encrypted, never returned in GET responses |

***

## Testing an integration

Always test an integration before enabling it. The test endpoint verifies that Nymble Commerce can successfully communicate with the provider using your credentials.

```http theme={null}
POST https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}/test
Authorization: Bearer {token}
```

**Response (success)**

```json theme={null}
{
  "success": true,
  "testStatus": "Success",
  "testedAt": "2024-06-01T10:05:00Z",
  "details": "Connected to Authorize.Net sandbox. Credentials valid."
}
```

**Response (failure)**

```json theme={null}
{
  "success": false,
  "testStatus": "Failed",
  "testedAt": "2024-06-01T10:05:00Z",
  "details": "Authentication failed. Check your ApiLoginId and TransactionKey."
}
```

<Tip>
  Always test integrations in sandbox mode first — set `IsSandbox: "true"` in `configuration` during testing, then create a separate production integration (or update secrets via `rotate-secrets`) with live credentials once you're satisfied.
</Tip>

***

## Managing integrations

### List integrations

```http theme={null}
GET https://api.achievemomentum.com/api/organizations/{organizationId}/integrations
Authorization: Bearer {token}
```

### Get a single integration

```http theme={null}
GET https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}
Authorization: Bearer {token}
```

The response includes `id`, `integrationType`, `provider`, `displayName`, `isEnabled`, `configuration`, `testStatus`, `lastTestedAt`, `createdAt`, and `updatedAt`. Secret values are never returned.

### Enable or update an integration

```http theme={null}
PUT https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "isEnabled": true,
  "displayName": "Authorize.Net (Production)",
  "configuration": {
    "IsSandbox": "false"
  }
}
```

### Delete an integration

```http theme={null}
DELETE https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}
Authorization: Bearer {token}
```

<Warning>
  Deleting an integration permanently removes its encrypted credentials from Nymble Commerce's secret store. This action cannot be undone. If the integration is currently active and processing payments or syncing data, disable it first and confirm no in-flight operations are pending before deleting.
</Warning>

***

## QuickBooks Online

QuickBooks Online uses OAuth 2.0, so the setup flow has an additional authorization step.

<Steps>
  <Step title="Create the QuickBooks integration">
    ```http theme={null}
    POST https://api.achievemomentum.com/api/organizations/{organizationId}/integrations
    Authorization: Bearer {token}
    Content-Type: application/json

    {
      "integrationType": "Accounting",
      "provider": "QuickBooks",
      "displayName": "QuickBooks Online",
      "isEnabled": false,
      "configuration": {},
      "secrets": {}
    }
    ```
  </Step>

  <Step title="Authorize via OAuth">
    After creating the integration, Nymble Commerce returns an OAuth authorization URL. Redirect your admin user to that URL to connect their QuickBooks Online company account. QuickBooks prompts them to sign in and grant access.
  </Step>

  <Step title="Nymble Commerce stores the tokens">
    After the user approves access, QuickBooks redirects back to Nymble Commerce's callback URL. Nymble Commerce exchanges the authorization code for access and refresh tokens and stores them encrypted — you don't handle tokens directly.
  </Step>

  <Step title="Enable the integration">
    Test the integration, then set `isEnabled: true`:

    ```http theme={null}
    PUT https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}
    Authorization: Bearer {token}
    Content-Type: application/json

    {
      "isEnabled": true
    }
    ```

    Nymble Commerce now syncs confirmed orders and paid invoices to QuickBooks Online automatically.
  </Step>
</Steps>

***

## Rotating secrets

If you need to update credentials without deleting and re-creating the integration (for example, when rotating API keys), use the rotate-secrets endpoint:

```http theme={null}
POST https://api.achievemomentum.com/api/organizations/{organizationId}/integrations/{integrationId}/rotate-secrets
Authorization: Bearer {token}
Content-Type: application/json

{
  "newSecrets": {
    "ApiLoginId": "NEW_API_LOGIN_ID",
    "TransactionKey": "NEW_TRANSACTION_KEY"
  }
}
```

The new secrets replace the old ones immediately. Run a test after rotating to confirm the new credentials are valid before re-enabling the integration in production.