A business can only use the services you turn on for it. You turn a service on, then switch on the features it supports. You can turn a service on before the business has everything it needs; PCE then lists what's missing and starts underwriting once nothing is. The services map is a desired state. An omitted service or feature is left untouched; to turn something off, send it with enabled: false. For the codes you can use, see Supported services and features.

Always change services through the services endpoint shown on this page. The business-level PATCH /v1/businesses/{businessId} is for other business data; use the dedicated services route for every service change.

Common use cases

• Enable Accept Payments for a business. See Scenario 1.
• Switch a feature on or off under a service. See Scenario 2.
• Override a service's features at one location. See Scenario 3.
• Open a Treasury deposit account or turn on payouts. See Scenario 4.

Scenarios

Send a service or feature to change it, omit it to leave it untouched, and send enabled: false to turn it off. PCE returns each service's status plus the read-only missingFields, missingDocuments, and errors that say what it still needs.

Before you begin (all scenarios)

• You have a sandbox API key. See Getting started.
• You have the businessId (and a locationId for per-location features).
• You know the service and feature codes you're setting. See Supported services and features.
• The business has the owners, accounts, addresses, and locations the service requires.

Scenario 1: Enable Accept Payments and its features

Write the services map with the service enabled and the features you want. Make a PATCH request to /v1/businesses/{businessId}/services.

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/services \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "payin": {
      "card": {
        "enabled": true,
        "features": {
          "cardNotPresent": {
            "enabled": true
          },
          "mxAdvantage": {
            "surcharge": {
              "enabled": true,
              "data": {
                "type": "PERCENTAGE",
                "value": 3
              }
            }
          },
          "3DSecureAuthentication": {
            "enabled": true
          }
        }
      }
    }
  }'

Response: 200 OK with the full, updated services map.

{
  "payin": {
    "card": {
      "enabled": true,
      "status": "PENDING_UNDERWRITING",
      "features": {
        "cardNotPresent": {
          "enabled": true,
          "status": "IN_PROGRESS"
        },
        "mxAdvantage": {
          "surcharge": {
            "enabled": true,
            "status": "IN_PROGRESS",
            "data": {
              "type": "PERCENTAGE",
              "value": 3
            }
          }
        },
        "3DSecureAuthentication": {
          "enabled": true,
          "status": "IN_PROGRESS"
        }
      }
    }
  }
}

status, missingFields, missingDocuments, and errors are read-only fields PCE computes for you. missingFields, missingDocuments, and errors are left out when there is nothing to report.

Choose the card processor

Set the processor in the data of cardNotPresent. It must be a processor your account offers, and it is fixed once the card account is created. For the values and the default, see Card processor.

{
  "payin": {
    "card": {
      "enabled": true,
      "features": {
        "cardNotPresent": {
          "enabled": true,
          "data": {
            "processor": "tsys"
          }
        }
      }
    }
  }
}

How updates work

• Send only the services and features you change. The others stay as they are.
• Include enabled on each service you send.
• To turn a service or feature off, send it with enabled: false. Leaving it out doesn't turn it off.

Scenario 2: Turn a feature off

Send the feature explicitly with enabled: false; omitting it would leave it unchanged.

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/services \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "payin": {
      "card": {
        "features": {
          "mxAdvantage": {
            "surcharge": {
              "enabled": false
            }
          }
        }
      }
    }
  }'

Change to a different fee program

A business can have one fee program on at a time. To switch, turn the current one off and the new one on in the same request:

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/services \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "payin": {
      "card": {
        "features": {
          "mxAdvantage": {
            "surcharge": {
              "enabled": false
            },
            "convenienceFee": {
              "enabled": true,
              "data": {
                "type": "PERCENTAGE",
                "value": 3
              }
            }
          }
        }
      }
    }
  }'

For each program's data rules, see Fee programs.

Scenario 3: Configure a service for one location

The same business can run different card features at different locations. Per-location settings apply to card processing (payin.card) only; Treasury and payout services are set for the whole business. Set a location's service and features with a PATCH request to /v1/businesses/{businessId}/locations/{locationId}/services/payin.card.

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/locations/loc_1d6b84/services/payin.card \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "features": {
      "3DSecureAuthentication": {
        "enabled": true
      }
    }
  }'

How a location inherits a feature

A feature must be enabled on the business before any location can use it. The business is the top of the hierarchy, and a location sits under it.

• Enabled on the business: each location inherits the feature and can turn it on or off for itself.
• Disabled on the business: no location can inherit or enable it.

So enable a feature once on the business, then use this per-location call to switch it on or off at a given location.

See Locations for the one-business-many-locations model.

Scenario 4: Turn on a Treasury deposit account or payouts

Treasury and payout services take only enabled; they have no features. Make a PATCH request to /v1/businesses/{businessId}/services. This request turns on a business-owned deposit account:

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/services \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "treasury": {
      "owned": {
        "enabled": true
      }
    }
  }'

Response: 200 OK with the full services map. The Treasury part shows what the service still needs:

{
  "treasury": {
    "owned": {
      "enabled": true,
      "status": "PENDING_REQUIREMENTS",
      "missingDocuments": [
        "account_agreement"
      ]
    }
  }
}

Attach the account agreement to clear it. See Documents.

Other Treasury and payout requests

• FBO deposit account: send { "treasury": { "fbo": { "enabled": true } } }.
• Both deposit accounts: send fbo and owned together under treasury.
• Payouts: send { "payout": { "ach": { "enabled": true } } }, or wire or check. Payouts are paid from the business-owned deposit account when the business has one, otherwise from the FBO deposit account.

Read the services

Read the whole services map with a GET request to /v1/businesses/{businessId}/services.

curl https://sandbox-api.prioritycommerce.com/v1/businesses/bus_8f3a2c/services \
  -H "x-api-key: <your-key>"

Request reference

The PATCH accepts an optional idempotency-key header so a retried change is not applied twice.

An enabled service reports its own status as underwriting reviews it. See Service lifecycle for the service statuses, and resolve a service that can't activate on Underwriting exceptions.

Next steps

See also

• Locations: set features per location
• Status lifecycle: the business-level boarding flow
• Underwriting exceptions: resolve a service that can't be enabled