Genome Authentication

generated: '2026-09-12'
method: searched
source: https://developers.genome.eu/merchants/host-to-host-api/ + https://developers.genome.eu/psd2-api/ + https://developers.genome.eu/merchants/hosted-payment-page/ + https://developers.genome.eu/webhooks/
docs: https://developers.genome.eu/
provider: Genome
providerId: genome
description: >-
  Genome does not run one authentication model — it runs four, one per product surface, and none of
  them is declared in a machine-readable contract. The harvested OpenAPI carries no
  components.securitySchemes at all, so every scheme below was read out of the documentation prose
  and, where noted, confirmed against a live unauthenticated request.
note: >-
  The dominant model on the merchant surface is credentials IN THE REQUEST BODY: merchant_account and
  merchant_password are ordinary form/JSON fields, not an Authorization header. That has real
  consequences for an agent — the secret is in the payload on every call, it appears in any body log,
  and there is no header-level scheme for a proxy or gateway to strip. It also means the OpenAPI
  cannot express the auth model with a securityScheme, which is why the spec has none.
schemes:
- id: merchant-credentials
  type: apiKey
  in: body
  names:
  - merchant_account
  - merchant_password
  applies_to:
  - Host-to-Host API (https://api.genome.eu/api/pf/host-to-host)
  - Payout API (https://api.genome.eu/api/pf/payout)
  - Query on Demand API (https://api.genome.eu/api/pf/qod)
  - SEPA Payout API (https://api.genome.eu/api/mp/payout)
  - CHECK transaction API (https://api.genome.eu/api/mp/transaction)
  - Verification of Payee API (https://api.genome.eu/api/mp/payee/verification)
  format: merchant_account string(6-32), merchant_password string(6-32)
  issued_by: Genome integration team, after merchant account approval
  docs: https://developers.genome.eu/merchants/host-to-host-api/
  failure:
    envelope_code: 2001
    envelope_message: Incorrect value in merchant account or pass field
    also: 2013 Bad API credentials
    http_status: 200
    note: >-
      Authentication failures are NOT signalled with HTTP 401. Probed 2026-09-12: an unauthenticated
      POST to https://api.genome.eu/api/pf/host-to-host returns HTTP 200 with
      {"status":"error","code":1004,"message":"Invalid request"} in the body. An agent that reads the
      HTTP status alone will treat a rejected call as a success.
- id: ip-allowlist
  type: network
  applies_to:
  - SEPA Payout API
  - Merchant Platform APIs (/api/mp/*)
  docs: https://developers.genome.eu/list-of-response-codes/
  failure:
    envelope_code: 2008
    envelope_message: Access from this IP-address is not available
  evidence: >-
    Probed 2026-09-12 — an unauthenticated POST to https://api.genome.eu/api/mp/payout returned
    code 2008 before any credential check, which is what establishes that a source-IP allowlist
    gates this surface.
- id: psd2-oauth2
  type: oauth2
  flow: authorization_code
  applies_to:
  - PSD2 Account Information Services (AIS)
  - PSD2 Payment Initiation Services (PIS)
  - PSD2 Confirmation of Funds (PIIS)
  authorization_endpoint: https://my.genome.eu/oauth2/authorize
  token_endpoint: https://my.genome.eu/oauth2/token
  token_endpoint_auth_method: client_secret_basic
  token_request_content_type: application/x-www-form-urlencoded
  bearer: Authorization Bearer {access_token}
  access_token_lifetime_minutes: 30
  refresh_token: optional
  concurrent_tokens: >-
    One active access token per client per user. Acquiring a new token invalidates any other token
    the client holds for that user.
  required_parameters:
  - client_id
  - redirect_uri
  - response_type=code
  - state
  scopes_published: false
  scopes_note: >-
    The token response carries a scope field, but Genome publishes no scope reference — the example
    shows a literal "{scope}" placeholder. No scopes/ artifact is emitted because there is nothing
    published to record.
  discovery_document: none
  discovery_note: >-
    No /.well-known/oauth-authorization-server and no /.well-known/openid-configuration on
    my.genome.eu — both return the SPA shell (see well-known/genome-well-known.yml). A TPP must read
    the endpoints out of prose.
  strong_customer_authentication:
    required: true
    factors:
    - Login at my.genome.eu
    - OTP delivered to the account holder's email or phone
    note: >-
      The access token carries no permissions until the account owner approves access, per PSD2 SCA.
  additional_required_headers:
  - name: Tpp-Qwac-Certificate
    description: >-
      The TPP's eIDAS QWAC certificate, PEM body with boundaries and no line breaks. This is the
      PSD2 RTS-mandated qualified website authentication certificate, carried as a header rather
      than negotiated at the TLS layer.
  - name: X-Request-ID
    description: Unique per-call identifier set by the initiating party.
  - name: PSU-IP-Address
    description: PSU's IP address, required when the request is actively initiated by the PSU.
  - name: Consent-ID
    description: The AIS consent the call is made under (account and transaction reads).
  onboarding: Registered AISP/PISP only; request access at psd2@genome.eu
  docs: https://developers.genome.eu/psd2-api/
- id: hpp-jwt
  type: http
  scheme: bearer
  format: JWT (JWS, HS256)
  applies_to:
  - Hosted Payment Page session initiation (https://pay.genome.eu)
  - Financial Pixel Web SDK (iframe and popup)
  signing_key_derivation: >-
    HMAC key = raw SHA-256 digest of the Payment Page API secret. The raw secret is NOT the signing
    key — tokens signed with it are always rejected. Genome hashes first to guarantee a 32-byte key
    regardless of secret length.
  claims:
    required:
    - iss (your API key)
    - sub (order or user id)
    - iat
    - exp
    - jti (fresh unique id per token)
    - VALUE_AMOUNT_ISO
    - VALUE_AMOUNT_RAW
    recommended:
    - VALUE_ORDER_ID
    - VALUE_USER_ID
    - VALUE_SUCCESS_URL
    - VALUE_FAILURE_URL
  legacy: >-
    A pre-JWT signature calculation is still documented under the heading "Deprecated - Legacy
    signature calculation".
  docs: https://developers.genome.eu/merchants/hosted-payment-page/
- id: callback-hmac
  type: signature
  direction: inbound-to-merchant
  applies_to:
  - Incoming payment notification webhooks
  header: X-Signature
  algorithm: HmacSHA256
  algorithm_header: X-Signature-Algorithm
  version_header: X-Version
  signed_content: the full callback HTTP request body
  key: per-customer shared secret configured by Genome
  docs: https://developers.genome.eu/webhooks/
- id: callback-checksum
  type: signature
  direction: inbound-to-merchant
  applies_to:
  - Host-to-Host transaction callbacks
  - SEPA Payout callbacks
  field: checkSum
  algorithm: SHA-256 over pipe-joined, key-sorted callback fields with the merchant private signature appended
  key: private signature issued by the Genome integration team
  docs: https://developers.genome.eu/sepa-payout-api/
- id: hpp-api-key-header
  type: apiKey
  in: header
  name: X-API-Key
  applies_to:
  - Hosted Payment Page callbacks (Genome -> merchant)
  docs: https://developers.genome.eu/merchants/hosted-payment-page/
summary:
  scheme_count: 7
  declared_in_openapi: 0
  oauth2_surfaces: 1
  mutual_tls_or_qwac: 1
  transport: TLS 1.2 on api.genome.eu, TLS 1.3 on genome.eu (see security/genome-domain-security.yml)
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com