# Create an Integration

Create an integration with a third-party service provider, including  payment processors, tokenization services, and other payment services.

Endpoint: POST /v1/integrations
Version: 1.0.0-beta.27
Security: ApiKeyAuth

## Security:

  - `ApiKeyAuth` (unknown)
    apiKey in header Api-Key

## Header parameters:

  - `Client-Id` (string, required)

  - `X-Acting-As-Client-Id` (string)
    The child client this request acts on behalf of. A reseller still authenticates as itself — `Api-Key` and `Client-Id` stay the reseller's — and names the child here.

This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations.

## Request fields (application/json):

  - `client` (string | null)
    The client ID to associate with this integration. Defaults to the caller's client if omitted.

  - `is_active` (boolean, required)
    Whether the integration should be active immediately upon creation.

  - `processor` (string, required)
    The payment processor or service provider for the integration. Send the value exactly as spelled here. On the integration operations the gateway parses this field case-sensitively, so `TSYS` is rejected.
    Enum: "Tsys", "Vericheck"

  - `integration_details` (any, required)

  - `integration_details.name` (string, required)
    Client legal name as registered with TSYS.

  - `integration_details.dba` (string | null)
    Doing Business As (DBA) name, if different from legal name.

  - `integration_details.url` (string, required)
    URL of processor server.

  - `integration_details.phone_number` (integer, required)
    Merchant contact phone number, as digits only. `TsysHostDetailsRequest` binds this as a 64-bit integer, so punctuation and a leading `+` are not accepted.

  - `integration_details.fax_number` (any)
    Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading `+` symbol (when used with a country  code), and the special characters `(`, `)`, `-`, and `.`. Alphabetical  characters are not allowed.

  - `integration_details.mid` (string, required)
    Merchant ID (MID) assigned by the payment processor.

  - `integration_details.amex_number` (string, required)
    American Express identification number for the merchant.

  - `integration_details.association` (string, required)
    Association or network identifier for the merchant.

  - `integration_details.bin` (string, required)
    Bank Identification Number (BIN) for the acquiring bank.

  - `integration_details.discover_number` (string, required)
    Discover network identifier for the merchant.

  - `integration_details.mcc` (string, required)
    Merchant Category Code (MCC) — four-digit ISO 18245 code classifying the business type.

  - `integration_details.bank_number` (string, required)
    Acquiring bank number assigned by TSYS.

  - `integration_details.industry` (string, required)
    Industry type identifier for the merchant (processor-specific).
    Enum: "0", "A", "B", "D", "H", "L", "O", "P", "R"

  - `integration_details.amex_opt_blue` (boolean, required)
    Whether the merchant participates in the American Express OptBlue program.

  - `integration_details.agent_chain` (string | null)
    Agent chain identifier associated with the merchant account.

  - `integration_details.store_number` (string, required)
    Store number for the merchant location, if applicable.

  - `integration_details.mvv` (string, required)
    Merchant Verification Value — unique identifier for the merchant's POS system.

  - `integration_details.terminal_number` (string, required)
    Terminal number associated with the merchant account.

  - `integration_details.agent_bank_number` (string, required)
    Agent bank number assigned by TSYS.

  - `integration_details.agent_chain_number` (string, required)
    Agent chain number assigned by TSYS.

  - `integration_details.descriptor_postal` (string, required)
    ZIP code shown on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_city` (string, required)
    City shown on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_state` (string, required)
    State shown on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_country` (string | null)
    Country shown on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_phone` (integer | null)
    Phone number shown on the cardholder's billing statement descriptor, as digits only. `TsysHostDetailsRequest` binds this as a nullable 64-bit integer, so punctuation and a leading `+` are not accepted.

  - `integration_details.descriptor_store_number` (string | null)
    Store number shown on the cardholder's billing statement descriptor.

  - `integration_details.address1` (string, required)
    Primary street address of the merchant.

  - `integration_details.address2` (string | null)
    Secondary address line of the merchant.

  - `integration_details.descriptor_line3` (string | null)
    Third line of the billing statement descriptor.

  - `integration_details.terminal_id` (string, required)
    Terminal ID assigned by the processor for the merchant's POS device.

  - `integration_details.v_number` (string, required)
    Visa-assigned number for the merchant.

  - `integration_details.settlement_time` (string, required)
    Daily batch settlement time in HH:MM format (24-hour, local to merchant).

  - `integration_details.merchant_area_code` (integer, required)
    Area code of the merchant's primary phone number.

  - `integration_details.descriptor_area_code` (integer | null)
    Area code shown on the cardholder's billing statement descriptor.

  - `integration_details.sharing_group` (string, required)
    Visa-assigned sharing group identifier specifying which direct debit and EBT networks the merchant's POS device can access.

  - `integration_details.merchant_aba_number` (string, required)
    Merchant's ABA routing number for settlement.

  - `integration_details.merchant_settlement_agent_number` (string, required)
    Settlement agent number assigned to the merchant by TSYS.

  - `integration_details.reimbursement_attribute` (string, required)
    Reimbursement attribute code for interchange qualification.

  - `integration_details.fcsid` (string | null)
    FCS ID — Fiserv/TSYS internal identifier for the merchant configuration.

  - `integration_details.metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

  - `integration_details.client_id` (string, required)
    Merchant's Client Id provided by Vericheck for API authentication.

  - `integration_details.client_secret` (string, required)
    Merchant's password provided by Vericheck for API authentication.

## Request examples:

  - `Onboard a TSYS merchant integration` (unknown)
    A complete TSYS host configuration for the merchant. Twenty-nine of these fields are required — the gateway enforces them in `TsysHostDetailsValidator` — so this payload is close to the minimum a real onboarding needs rather than a generous illustration. The processor-specific identifiers here are illustrative placeholders.

## Response 200:

  - `200` (unknown)
    Integration created successfully

## Response 200 fields (application/json):

  - `id` (string | null)
    Unique identifier for this integration configuration.

  - `is_active` (boolean, required)
    Whether the integration is currently active.

  - `client` (string | null)
    The client ID associated with this integration.

  - `processor` (string, required)
    The payment processor or service provider for the integration. Send the value exactly as spelled here. On the integration operations the gateway parses this field case-sensitively, so `TSYS` is rejected.
    Enum: "Tsys", "Vericheck"

  - `integration_details` (object, required)
    Processor-specific integration details returned in responses. Shape varies by processor.

  - `integration_details.created_by` (integer | null)
    Internal ID of the user who created this integration.

  - `integration_details.created_at` (string | null)
    ISO 8601 timestamp of when the integration was created.

  - `integration_details.modified_by` (integer | null)
    Internal ID of the user who last modified this integration.

  - `integration_details.modified_at` (string | null)
    ISO 8601 timestamp of the last modification to this integration.

  - `integration_details.name` (string | null)
    Merchant legal name as registered with TSYS.

  - `integration_details.dba` (string | null)
    Doing Business As (DBA) name.

  - `integration_details.url` (string | null)
    Merchant website URL.

  - `integration_details.phone_number` (integer)
    Merchant contact phone number, as digits only. `TsysHostDetailsResponse` returns this as a 64-bit integer, so it carries no punctuation and no leading `+`.

  - `integration_details.fax_number` (string | null)
    Merchant fax number.

  - `integration_details.mid` (string | null)
    Merchant ID (MID) assigned by the payment processor.

  - `integration_details.amex_number` (string | null)
    American Express identification number for the merchant.

  - `integration_details.association` (string | null)
    Association or network identifier for the merchant.

  - `integration_details.bin` (string | null)
    Bank Identification Number (BIN) for the acquiring bank.

  - `integration_details.discover_number` (string | null)
    Discover network identifier for the merchant.

  - `integration_details.mcc` (string | null)
    Merchant Category Code (MCC) classifying the business type.

  - `integration_details.bank_number` (string | null)
    Acquiring bank number assigned by TSYS.

  - `integration_details.industry` (string | null)
    Industry type identifier for the merchant.

  - `integration_details.amex_opt_blue` (boolean | null)
    Whether the merchant participates in the American Express OptBlue program.

  - `integration_details.agent_chain` (string | null)
    Agent chain identifier associated with the merchant.

  - `integration_details.store_number` (string | null)
    Store number for the merchant location.

  - `integration_details.mvv` (string | null)
    Merchant Verification Value for the merchant's POS system.

  - `integration_details.terminal_number` (string | null)
    Terminal number associated with the merchant account.

  - `integration_details.agent_bank_number` (string | null)
    Agent bank number assigned by TSYS.

  - `integration_details.agent_chain_number` (string | null)
    Agent chain number assigned by TSYS.

  - `integration_details.descriptor_postal` (string | null)
    ZIP code on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_city` (string | null)
    City on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_state` (string | null)
    State on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_country` (string | null)
    Country on the cardholder's billing statement descriptor.

  - `integration_details.descriptor_phone` (integer | null)
    Phone number shown on the cardholder's billing statement descriptor, as digits only. `TsysHostDetailsResponse` returns this as a nullable 64-bit integer, so it carries no punctuation and no leading `+`.

  - `integration_details.descriptor_store_number` (string | null)
    Store number on the cardholder's billing statement descriptor.

  - `integration_details.address1` (string | null)
    Primary street address of the merchant.

  - `integration_details.address2` (string | null)
    Secondary address line of the merchant.

  - `integration_details.descriptor_line3` (string | null)
    Third line of the billing statement descriptor.

  - `integration_details.terminal_id` (string | null)
    Terminal ID for the merchant's POS device.

  - `integration_details.v_number` (string | null)
    Visa-assigned number for the merchant.

  - `integration_details.settlement_time` (string | null)
    Daily batch settlement time in HH:MM format.

  - `integration_details.merchant_area_code` (integer, required)
    Area code of the merchant's primary phone number.

  - `integration_details.descriptor_area_code` (integer | null)
    Area code on the cardholder's billing statement descriptor.

  - `integration_details.sharing_group` (string | null)
    Visa-assigned sharing group identifier for direct debit and EBT network access.

  - `integration_details.merchant_aba_number` (string | null)
    Merchant's ABA routing number for settlement.

  - `integration_details.merchant_settlement_agent_number` (string | null)
    Settlement agent number for the merchant.

  - `integration_details.reimbursement_attribute` (string | null)
    Reimbursement attribute code for interchange qualification.

  - `integration_details.fcsid` (string | null)
    FCS ID — internal identifier for the merchant configuration.

  - `integration_details.metadata` (object | null)
    Key-value pairs for storing additional information on the transaction. Send `null` to clear all metadata.
At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

  - `integration_details.client_id` (string, required)
    Merchant's Client Id provided by Vericheck for API authentication.

  - `integration_details.client_secret` (string)
    Merchant's secret at Vericheck, returned masked. The real value is write-only — send it on the request and do not expect to read it back.

  - `correlation_id` (string)
    Identifier the gateway assigns to the request and carries across the services that handled it. Quote it when reporting a problem.

## Response 200 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 400 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 401:

  - `401` (unknown)
    Not authenticated

## Response 401 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 401 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 403 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 409:

  - `409` (unknown)
    Conflict

## Response 409 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 409 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 500:

  - `500` (unknown)
    Internal server error

## Response 500 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 500 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 200 examples:

  - `TSYS merchant integration created` (unknown)
    The stored configuration, echoing back what was submitted and adding the `id` to reference it, the network identifiers TSYS assigns during onboarding (`amex_number`, `discover_number`, `association`, `bin`), and the audit fields.

## Response 400 examples:

  - `Invalid field value in the request body` (unknown)

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

  - `Authenticated but not authorized for this action` (unknown)

## Response 409 examples:

  - `Duplicate or state-conflicting action` (unknown)

## Response 500 examples:

  - `Unhandled server fault or downstream processor error` (unknown)