---
title: "Create a Gateway Integration"
method: POST
path: "/gateway_integrations"
tags: ["Gateway Integrations"]
---

# Create a Gateway Integration

`POST /gateway_integrations`

Create a [Gateway Integration](/api/gateway-integrations) that connects a [Merchant](/api/merchants) to a third-party payment gateway. At this time, the only supported gateway is Cybersource.

If subscribed, a [Gateway Integration - Created webhook](/additional-resources/developers/webhooks/webhook-events#gateway-integration-created) is sent when the integration is created with a `Gateway Integration` ›`state` of `PENDING`.

When the `state` changes to `SUCCEEDED` or `FAILED`, a [Gateway Integration - Updated webhook](/additional-resources/developers/webhooks/webhook-events#gateway-integration-updated) is sent.

## Headers

- `Finix-Version` string
- `Content-Type` string

## Request body

- CreateGatewayIntegration
  - `email` string, email — The email address to receive the Cybersource dashboard invitation, which lets you retrieve your Cybersource transacting credentials. If this field is not provided, the invitation will be sent to the email address associated with the merchant's email address defined in [Identity](/api/identities) › `entity.email` field.
  - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - `type` 'CYBERSOURCE', required — The type of `Gateway Integration` to create. At this time, the only supported value is `CYBERSOURCE`.

## Response `201`

A single Gateway Integration

- GatewayIntegration
  - `id` string — The ID of the resource.
  - `created_at` string, date-time — Timestamp of when the object was created.
  - `updated_at` string, date-time — Timestamp of when the object was last updated.
  - `application_id` string — ID of the `Application` the resource was created under.
  - `linked_to` string — The ID of the `Merchant` to which the `Gateway Integration` is linked.
  - `linked_type` 'MERCHANT' — The type of resource to which the `Gateway Integration` is linked.
  - `email` string, email — The email address to receive the Cybersource dashboard invitation, which lets you retrieve your Cybersource transacting credentials. If this field was not provided, the invitation will be sent to the email address associated with the merchant's email address defined in [Identity](/api/identities) › `entity.email` field.
  - `state` 'FAILED' | 'PENDING' | 'SUCCEEDED' — The state of the `Gateway Integration`. The possible values are: - `PENDING`: The `Gateway Integration` is being processed. - `SUCCEEDED`: The `Gateway Integration` was successful. - `FAILED`: The `Gateway Integration` failed.
  - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
  - `_links` object
    - `self` Self — Link to the resource that was used in the request.
      - `href` string

## Other responses

- `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data.
- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted.

---

[API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)