Cardstream Authentication

generated: '2026-07-24'
method: searched
source: https://guides.gitbook.io/integrationguide/getting-started/setting-up-your-integration/authentication
docs: https://guides.gitbook.io/integrationguide/getting-started/setting-up-your-integration/authentication
note: >-
  Cardstream's Gateway is a form-post API with no OAuth2, OpenID Connect or
  mTLS/FAPI surface (probes for /.well-known/openid-configuration and
  /.well-known/oauth-authorization-server return 404). There are no OAuth scopes,
  so no scopes/ artifact is produced. Auth is a layered model of merchant
  identification plus optional integrity, credential and network controls
  configured per Merchant Account in the Merchant Management System (MMS).
summary:
  types: [merchantID, password, message-signing, ip-allowlist]
  api_key_in: [form-body]
  transport: HTTP POST application/x-www-form-urlencoded over TLS 1.2+
schemes:
  - name: merchantID
    type: apiKey
    in: form-body
    field: merchantID
    required: true
    description: >-
      Every request must carry the merchantID identifying which Merchant Account
      the transaction is for. This is the base identity credential.
  - name: merchantPwd
    type: apiKey
    in: form-body
    field: merchantPwd
    required: false
    description: >-
      Optional per-account password. Discouraged for browser-posted forms because
      the password can appear in client-side code. An incorrect password aborts
      the transaction with an error response.
  - name: signature
    type: message-signing
    in: form-body
    field: signature
    algorithm: SHA-512
    required: conditional
    description: >-
      HMAC-style message signing. A signing secret phrase is configured per
      Merchant Account in the MMS. The client sorts request fields by ascending
      ASCII field-name order, serialises them (URL-encoded), appends the secret,
      and hashes with SHA-512; the resulting hash is sent in the signature field.
      The Gateway re-generates and compares the hash to detect tampering, and
      returns a signed response plus signed callback POSTs. Signing may be
      mandatory on some accounts (secret can be changed but not removed).
  - name: ip-allowlist
    type: network
    required: false
    description: >-
      Per-account IP allow-lists configured in the MMS, with separate lists for
      standard requests (e.g. sales) and advanced requests (e.g. refunds,
      cancellations). Requests from other addresses are aborted.