Bancontact Authentication

generated: '2026-09-17'
method: searched
docs: https://docs.bancontactpro.com/guides/general/gettingstarted052025v4
source: >-
  securitySchemes of the three first-party OpenAPI 3.1 bundles (openapi/*.yml), upgraded with the
  Getting Started, Callback and Refunds guides on docs.bancontactpro.com (2026-09-17).
summary:
  types: [apiKey]
  api_key_in: [header]
  oauth2: false
  openid_connect: false
  mutual_tls: false
  request_signing: detached JWS (RFC 7797), ES256, keys exchanged as JWKS (RFC 7517)
  environments:
    preprod: https://merchant.api.preprod.bancontact.net
    prod: https://merchant.api.bancontact.net
  transport: TLS 1.2 or 1.3 only; plain HTTP fails
onboarding: >-
  Credentials are issued by Bancontact, not self-served. Production: the API key and Company ID
  are read from the Bancontact Pro portal (portal.bancontactpro.com, Settings) after a merchant
  contract; PREPROD: email devsupport@bancontact.com with company name, Merchant ID, contact and
  integration type — provisioning takes up to 2 weeks. One API key and one Product Profile ID
  (PPID) are issued per product.
schemes:
  - name: api_key_payment_profile
    type: apiKey
    in: header
    parameter: Authorization
    format: Bearer <api-key>
    description: >-
      Per-product API key generated by Bancontact's API Manager, sent as a Bearer token in the
      Authorization header. The key carries the profileId, subjectType (INTEGRATOR:{CCV_ID} or
      MERCHANT:{ID}), resource (PAYMENTPROFILE:{profileId}) and authority (MERCHANT_PAYMENT or
      MERCHANT_REFUND) that each operation checks.
    applies_to: [merchant-get-payment, cancel_payment, search, create, create_static_qr_payment, merchant-acknowledge, create-refund]
    sources: [openapi/bancontact-payment-v3-api-openapi.yml]
  - name: JWS-Request-Signature
    type: apiKey
    in: header
    parameter: Signature
    description: >-
      Detached JSON Web Signature (RFC 7797) over the request body, alg ES256, with a JOSE header
      carrying kid, typ jose+json and the critical claims https://payconiq.com/sub (merchant
      profile id), /iss, /iat (ISO 8601 UTC), /jti (unique request id) and /path (request path).
      The merchant hosts its public key as a JWKS and shares the URL with Bancontact during
      integration; Bancontact publishes its own keys at https://jwks.bancontact.net/ (PROD) and
      https://jwks.preprod.bancontact.net/ (PREPROD) so merchants can verify signed responses
      (SignatureBank header) and callbacks. Refund creation must additionally be activated by
      Bancontact support before the JWS-signed endpoint accepts calls.
    variants:
      - {name: JWS-Request-Signature-Payment, spec: openapi/bancontact-payment-v3-api-openapi.yml, note: added in Payment API 3.6.4 (2025-08-26) for all payment calls}
      - {name: JWS-Request-Signature-Refund, spec: openapi/bancontact-payment-refund-service-api-openapi.yml}
      - {name: JWS-Request-Signature, spec: openapi/bancontact-merchant-reconciliation-api-openapi.yml}
    applies_to: [createRefund, getRefundById, getPayoutList, getPayments, getRefunds, create, merchant-get-payment, cancel_payment, search, create_static_qr_payment]
    sources:
      - openapi/bancontact-merchant-reconciliation-api-openapi.yml
      - openapi/bancontact-payment-refund-service-api-openapi.yml
      - openapi/bancontact-payment-v3-api-openapi.yml
inbound_verification:
  callbacks: >-
    Status callbacks POSTed to the merchant carry a detached JWS in the `signature` header signed
    by Bancontact (kid resolved against the published JWKS); merchants must verify origin,
    integrity, audience (sub) and all crit claims before trusting the body. Bancontact rotates
    keys without notice — a new JWK is published 24 h before the old one is removed; cache JWKS
    for at most 12 h and re-fetch on verification failure.
  docs: https://docs.bancontactpro.com/guides/general/callback052025
related:
  scopes: none — no OAuth scopes; authorities (MERCHANT_PAYMENT, MERCHANT_REFUND) are baked into the issued key
  conventions: conventions/bancontact-conventions.yml
  sandbox: sandbox/bancontact-sandbox.yml