Spreedly Gateways API

openapi: 3.2.0
info:
  title: Spreedly API V1 Gateways API
  version: v1
  description: An OpenAPI specification file for V1 of the Spreedly Core Transactional API
servers:
- url: https://core.spreedly.com/v1
tags:
- name: gateways
paths:
  /gateways.{format}:
    parameters:
    - $ref: '#/components/parameters/format'
    post:
      summary: Create a gateway
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: create-gateways
      description: Create (provision) a gateway to process card data in the authenticated environment. A test gateway is used to [test your integration](https://developer.spreedly.com/docs/testing/) to Spreedly and can only be used with [test payment methods](https://developer.spreedly.com/docs/test-data/). Production gateways process real card data and transactions. Production gateways are created using the credentials required for that gateway, meaning each call is slightly different depending on the gateway's API requirements.
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateway_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gateway'
            examples:
              Create Gateway:
                summary: Create a gateway with gateway credentials
                value:
                  gateway:
                    gateway_type: string
                    description: string
                    gateway_specific_login: gateway_username
                    gateway_secret: gateway_credential
                    merchant_profile_key: string
                    sub_merchant_key: string
                    sandbox: true
          application/xml:
            schema:
              $ref: '#/components/schemas/gateway'
            examples:
              Create Gateway:
                summary: Create a gateway with gateway credentials
                value:
                  gateway:
                    gateway_type: string
                    description: string
                    gateway_specific_login: gateway_username
                    gateway_secret: gateway_credential
                    merchant_profile_key: string
                    sub_merchant_key: string
                    sandbox: true
    get:
      summary: List created gateways
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: list-gateways
      description: Retrieve an ordered and paginated list of all gateways in the environment. This is different from the list of all supported gateways in that this will only return the gateway instances that have been provisioned in the authenticated environment.
      parameters:
      - name: order
        in: query
        description: The order of the returned list. Default is `asc`, which returns the oldest records first. To list newer records first, use `desc`.
        schema:
          type: string
      - name: since_token
        in: query
        description: The token of the item to start from (e.g., the last token received in the previous list if iterating through records)
        schema:
          type: string
      - name: count
        in: query
        description: The number of gateways to return. By default returns 20, maximum allowed is 100.
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_gateways_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/list_gateways_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '422':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
  /gateways/{gateway_token}.json:
    parameters:
    - name: gateway_token
      in: path
      description: The token of the gateway to execute against
      required: true
      schema:
        type: string
    get:
      summary: Show gateway
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: show-gateways
      description: Get a gateway with the given token.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateway_response'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
    put:
      summary: Update gateway
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: update-gateway
      description: 'Update a gateway.


        Update is intended to be used for updating credentials, description, or metadata.

        '
      parameters: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateway_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gateway_update'
          application/xml:
            schema:
              $ref: '#/components/schemas/gateway_update'
  /gateways_options.json:
    get:
      summary: List supported gateways
      tags:
      - gateways
      operationId: list-supported-gateways
      description: Retrieve a list of all gateways, and their properties, supported by Spreedly. This call can be used to dynamically present a gateway credential form to users or to do any sort of dynamic rendering.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateways_options_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateways_options_response'
  /gateways/{gateway_token}/transactions.json:
    parameters:
    - name: gateway_token
      in: path
      description: The token of the gateway to execute against
      required: true
      schema:
        type: string
    get:
      summary: Transactions
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: list-gateway-transactions
      description: Get an ordered and paginated list of transactions executed against a specific gateway.
      parameters:
      - name: order
        in: query
        description: The order of the returned list. Default is `asc`, which returns the oldest records first. To list newer records first, use `desc`.
        schema:
          type: string
      - name: since_token
        in: query
        description: The token of the item to start from (e.g., the last token received in the previous list if iterating through records)
        schema:
          type: string
      - name: state
        in: query
        description: The transaction state on which to filter the returned list. Can be one of `succeeded`, `failed`, `gateway_processing_failed`, `gateway_processing_result_unknown`.
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactions_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/transactions_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '422':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
  /gateways/{gateway_token}/redact.json:
    parameters:
    - name: gateway_token
      in: path
      description: The token of the gateway to execute against
      required: true
      schema:
        type: string
    put:
      summary: Redact gateway
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: redact-gateways
      description: Redact (strip of any sensitive credentials and make inactive) a provisioned gateway.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateway_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
  /gateways/{gateway_token}/retain.json:
    parameters:
    - name: gateway_token
      in: path
      description: The token of the gateway to execute against
      required: true
      schema:
        type: string
    put:
      summary: Retain gateway
      tags:
      - gateways
      security:
      - basic_auth: []
      operationId: retain-gateways
      description: When gateways are created via the API, they are automatically retained. However, gateways created via the unauthenticated API (e.g., from a browser/javascript library) are created in the “cached” state. Only by retaining a cached gateway will it be saved and available for future use.
      parameters: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gateway_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/gateway_response'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
            application/xml:
              schema:
                $ref: '#/components/schemas/errors'
components:
  schemas:
    transactions_response:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/purchase_parameters'
    payment_method:
      type: object
      properties:
        token:
          type: string
          description: The token identifying the payment method in the Spreedly vault
        created_at:
          type: string
          description: The time the payment method token was created
        updated_at:
          type: string
          description: The time the payment method token was last updated
        email:
          type: string
          description: The email address of the customer associated with this credit card
        storage_state:
          type: string
          description: The `storage_state` (retained, redacted, cached, used) of the payment method
        test:
          type: boolean
          description: '`true` if this payment method is a test payment method and cannot be used against real gateways or receivers'
        metadata:
          type: object
          description: metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types
        callback_url:
          type: string
          description: 'The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)'
        last_four_digits:
          type: string
          description: The last four digits of the credit card number. This can be displayed to the user.
        first_six_digits:
          type: string
          description: The first six digits of the credit card number. This can be displayed to the user.
        card_type:
          type: string
          description: The [type](https://developer.spreedly.com/docs/supported-payment-methods), or brand, of the card. Please see the `card_type_mapping` function below for more detail.
        first_name:
          type: string
          description: The first name of the cardholder
        last_name:
          type: string
          description: The last name of the cardholder
        month:
          type: string
          description: The expiration month
        year:
          type: string
          description: The expiration year
        address1:
          type: string
          description: The first line of the billing address
        address2:
          type: string
          description: The second line of the billing address
        city:
          type: string
          description: The city of the billing address
        state:
          type: string
          description: The state of the billing address
        zip:
          type: string
          description: The zip code of the billing address
        country:
          type: string
          description: The country code of the billing address
        phone_number:
          type: string
          description: The phone number of the billing address
        company:
          type: string
          description: The company of the cardholder
        full_name:
          type: string
          description: The full name of the cardholder.
        eligible_for_card_updater:
          type: string
          description: '`true` if this payment method should be included in Account Updater'
        shipping_address1:
          type: string
          description: The first line of the shipping address
        shipping_address2:
          type: string
          description: The second line of the shipping address
        shipping_city:
          type: string
          description: The city of the shipping address
        shipping_state:
          type: string
          description: The state of the shipping address
        shipping_zip:
          type: string
          description: The zip code of the shipping address
        shipping_country:
          type: string
          description: The country code of the shipping address
        issuer_identification_number:
          type: string
          description: The numbers of the PAN required to identify the card issuer.
        click_to_pay:
          type: string
          description: '`true` if the card was tokenized using Click to Pay'
        managed:
          type: string
          description: The value indicating the payment method's management status.
        payment_method_type:
          type: string
          description: The type of this payment method, e.g., `credit_card`, `bank_account`, `apple_pay`, `google_pay`, `third_party_token`, etc…
        errors:
          type: string
          description: If the payment method is invalid (missing required fields, etc…), there will be associated error messages here
        fingerprint:
          type: string
          description: An identifying string that will match all cards in the environment with the same PAN
        verification_value:
          type: string
          description: The obscured verification value (CVV), e.g., XXX or XXXX
        number:
          type: string
          description: The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444
        bin_metadata:
          type: object
          description: BIN metadata is available in the response if the card is enrolled in Advanced Vault. See [BIN metadata](https://developer.spreedly.com/docs/bin-metadata) for more information.
          properties:
            card_brand:
              type: string
            card_category:
              type: string
            card_type:
              type: string
            issuing_bank:
              type: string
            issuing_country_iso_number:
              type: string
            issuing_country_iso_a2_code:
              type: string
            issuing_country_iso_a3_code:
              type: string
            issuing_country_iso_name:
              type: string
            issuing_bank_phone_number:
              type: string
            issuing_bank_website:
              type: string
            bin_type:
              type: string
            regulated:
              type: string
            max_pan_length:
              type: string
            message:
              type: string
        subscribed_to_mastercard_abu:
          type: boolean
          example: false
          description: '`true` if this payment method is subscribed to Mastercard ABU updating service'
        last_successfully_used:
          type: string
          format: date-time
          nullable: true
          description: 'The time (UTC) the payment method was last successfully transacted with. The following transaction types are considered: Authorization, Purchase, Verification, GeneralCredit, OffsiteVerification, or OffsitePurchase'
    protect_fraud_check_response:
      type: object
      description: When a Fraud Check is attempted, provides an overview of the results at the time of the current transaction. For more information on Protection Fraud Checks, see [the guide](https://developer.spreedly.com/docs/protect).
      properties:
        updated_at:
          type: string
          description: The time the fraud check was last updated
        created_at:
          type: string
          description: The time the fraud check was created
        protection_provider_key:
          type: string
          description: The token of the Protection Provider used for this check
        succeeded:
          type: boolean
          description: Whether the fraud check request was successfully executed
        state:
          type: string
          description: The current state of the fraud check
        token:
          type: string
          description: The token uniquely identifying this fraud check at Spreedly
        message:
          type: string
          description: A human-readable message describing the result (if applicable)
        amount:
          type: number
          description: The transaction amount checked
        currency_code:
          type: string
          description: The currency of the funds in ISO format (e.g., USD)
        ip:
          type: string
          description: The IP address associated with the transaction
        email:
          type: string
          description: The email address associated with the transaction
        transaction_type:
          type: string
          description: The type of transaction
        gateway_transaction_key:
          type: string
          description: The Spreedly transaction token of the parent gateway transaction
        callback_url:
          type: string
          description: The URL where Spreedly will attempt delivery of asynchronous results (if provided)
        test_scenario:
          type: string
          description: The test scenario used
        acquiring_bank_fraud_rate:
          type: string
          description: The threshold for bank fraud rate used for exemption requests
        exemption_type:
          type: string
          description: The type of exemption requested (if applicable)
        warning:
          type: string
          description: Any warning messages from the fraud check
        managed_order_token:
          type: string
          description: The token of the fraud check returned by the fraud check provider
        fraud_decision:
          type: string
          description: The fraud decision outcome (e.g., approve, decline, review)
        fraud_recommendation:
          type: string
          description: Additional recommendation information from the fraud provider
        fraud_decision_reason:
          type: string
          description: Reason for the fraud decision
        vendor_response:
          type: object
          description: Detailed response from the fraud protection vendor
          properties:
            forterDecision:
              type: string
              description: The decision returned by Forter
            recommendation:
              type: string
              description: Recommended action from the vendor
            verificationMethod:
              type: object
              description: Methods used to verify the transaction
            decisionReason:
              type: string
              description: Reason for the vendor's decision
            merchantPolicyId:
              type: string
              description: Merchant policy identifier used to make the decision
            orderId:
              type: string
              description: Order identifier in the vendor's system
            linkToEventInDashboard:
              type: string
              description: URL to view the transaction details in the vendor's dashboard
    gateway_properties:
      type: object
      properties:
        token:
          type: string
          description: The token identifying the provisioned gateway at Spreedly
        name:
          type: string
          description: The human readable name of the gateway
        gateway_type:
          type: string
          description: The type (short name) of the gateway. Use this value when provisioning a gateway
        description:
          type: string
          description: The description of the provisioned gateway
        merchant_profile_key:
          type: string
          description: The token of the Merchant Profile associated with the provisioned gateway
        sub_merchant_key:
          type: string
          description: The token of the Sub-merchant associated with the provisioned gateway
        state:
          type: string
          description: The storage state of the gateway (retained, redacted, etc…)
        sandbox:
          type: boolean
          description: If the gateway was created in sandbox mode or not
        redacted:
          type: boolean
          description: If this gateway is redacted or not
        credentials:
          type: array
          description: The non-sensitive credentials used for this gateway
        gateway_settings:
          type: object
          description: The non-credential fields that can be specified at the gateway level, and included in all transactions
        characteristics:
          type: array
          description: A list of operations (such as purchase, capture etc…) that the gateway supports
        payment_methods:
          type: array
          description: A list of payment methods (such as credit_card, apple_pay, google_pay, etc…) that the gateway supports
        gateway_specific_fields:
          $ref: '#/components/schemas/gateway_specific_fields'
        created_at:
          type: string
          description: The time the gateway was created
        updated_at:
          type: string
          description: The time the gateway was last updated
    protection_parameters:
      description: Additional fields that are accepted by the Protection provider, including a `test_scenario` object to indicate valid Protect test flow options. Please refer to our [Protect guide](https://developer.spreedly.com/docs/protect) to learn more.
      type: object
      properties:
        test_scenario:
          type: object
          description: The protection test scenario
          properties:
            scenario:
              type: string
              description: The test scenario to run
              enum:
              - protect_approved
              - protect_sca_recommended_challenge
              - protect_sca_recommended_authenticated
              - protect_sca_recommended_not_authenticated
              - protect_declined
              default: protect_approved
        fraud_token:
          type: string
          description: Forter fraud token. Emitted when running a fraud lifecycle from [the Spreedly iFrame](https://developer.spreedly.com/docs/iframe-api-lifecycle). Required for web transactions only.
        forter_mobile_uid:
          type: string
          description: Mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API. Required for mobile transactions only.
        user_agent:
          type: string
          description: Customer's User agent
        cart_items:
          type: array
          description: A list of all items purchased and shipping details
          items:
            type: object
            properties:
              name:
                type: string
                description: Item name
                maxLength: 500
              quantity:
                type: number
                description: Item quantity
              type:
                type: string
                description: TANGIBLE if physical item, NON_TANGIBLE if any other product
                enum:
                - TANGIBLE
                - NON_TANGIBLE
                default: TANGIBLE
              price:
                type: string
                description: Final amount due for purchase, after all discounts and promotions
            required:
            - name
            - quantity
            - type
            - price
        delivery_type:
          type: string
          description: 'Type of delivery: PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.)'
          enum:
          - PHYSICAL
          - DIGITAL
          default: PHYSICAL
        delivery_method:
          type: string
          description: Delivery method chosen by customer such as postal service, email, in game transfer, etc.
          maxLength: 50
        customer_account_id:
          type: string
          description: Customer's account UID in merchant's site (leave empty if guest)
        customer_account_type:
          type: string
          description: Customer account type
          enum:
          - GUEST
          - PRIVATE
          - BUSINESS
          - VIP
          - MERCHANT_OPERATED
          - TRIAL
          - MERCHANT_EMPLOYEE
          - PREMIUM_PAID
          - SMALL_BUSINESS
          - AGENT
          - BUSINESS_PRIVATE
          - BUSINESS_PREMIUM_PAID
          default: BUSINESS
        customer_account_creation_date:
          type: number
          description: Customer account creation date in seconds since unix epoch (UTC, Jan 1, 1970)
        billing_name:
          type: string
          description: The customer full name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_first_name:
          type: string
          description: The customer first name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_last_name:
          type: string
          description: The customer last name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        email:
          type: string
          description: The customer email address. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_country:
          type: string
          description: The customer billing country. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_address1:
          type: string
          description: The customer billing address line 1. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_address2:
          type: string
          description: The customer billing address line 2. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_city:
          type: string
          description: The customer billing city. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_zip:
          type: string
          description: The customer billing zip code. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_state:
          type: string
          description: The customer billing state. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here.
        billing_phone_number:
          type: string
          description: The customer billing phone number. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spreedly/refs/heads/main/openapi/spreedly-gateways-api-openapi.yml