Onboarding

Before you can call the Bahn REST API or embed the Web SDK, you complete a one-time onboarding with the Bahn team. Onboarding produces the credentials every later step depends on: your merchant account, an exchanged set of public keys, a server-side API key, and a client-side publishable key.

Some steps are handled manually by the Bahn team — creating your merchant account is not self-service.

Overview

sequenceDiagram
    autonumber
    participant You as You (Merchant)
    participant Bahn as Bahn Team
    participant API as Bahn API

    Note over You, Bahn: Step 1 — Create merchant account (manual)
    You ->> Bahn: Request onboarding (business details)
    Bahn -->> You: Merchant account created

    Note over You, API: Step 2 — Exchange public keys
    You ->> You: Generate P-256 key pairs (sig + enc)
    You ->> Bahn: Submit your public keys (JWK)
    You ->> API: GET /api/public-keys
    API -->> You: Bahn's public keys (JWK)

    Note over You, Bahn: Step 3 — Receive API key
    Bahn -->> You: Bn-Api-Key (secret, server-side)

    Note over You, Bahn: Step 4 — Receive publishable key
    Bahn -->> You: Publishable key (pk_..., client-side)

Step 1 — Create your merchant account

Creating a merchant account is a manual step. Contact Bahn (your account manager) to get onboarded. The Bahn team provisions your merchant account so the credentials in the following steps can be issued.

Provide the following information so Bahn can set up your account:

Account details

Field	Description
`name`	Your merchant / business name.
`mcc`	Merchant Category Code (ISO 18245) describing your line of business.
`city_code`	City code of your business location.
`country_code`	Country code of your business location.
`settlement_currency`	Currency in which Bahn settles funds to you.
`payment_currency`	Currency your buyers are charged in.

Business details

Field	Description
`website_url`	Your business website.
`contact_person`	Primary contact name.
`contact_phone`	Contact phone number.
`contact_email`	Contact email address.
`description`	Short description of your business.
`city`	City.
`country`	Country.
`address_line1`	Street address, line 1.
`address_line2`	Street address, line 2 (optional).

Webhook configuration

Field	Description
`webhook_url`	HTTPS endpoint where Bahn delivers webhook events.
`webhook_enabled_events`	The event types you want delivered to your webhook.

INFO

There is no self-service API to create a merchant — this step is completed by the Bahn team during onboarding.

Step 2 — Exchange public keys

Bahn secures request and response payloads with the JOSE framework, so you and Bahn exchange public keys once.

Generate two P-256 key pairs — one for signing requests (JWS), one for decrypting responses (JWE). See Generate Key Pairs. Your private keys never leave your systems.
Submit your public keys to Bahn — send both public keys in JWK format. Each key must include a kid and a use (sig or enc). See Public Key Requirements.
Fetch Bahn's public keys — retrieve the JWK keys Bahn uses so you can encrypt sensitive card data client-side and verify signed responses:

http

GET /api/public-keys

Step 3 — Receive your API key

Once your merchant account is created, Bahn issues your API key. Send it on every REST request using the Bn-Api-Key header — see API Key.

WARNING

The API key is a server-side secret. Never expose it in a browser, mobile app, or public repository. If it is compromised, contact Bahn support to have it rotated.

Step 4 — Receive your publishable key

For client-side card collection with the Web SDK, Bahn issues a publishable key (pk_...). Unlike the API key, the publishable key is safe to embed in your frontend. Use it to initialize the SDK — see Web SDK · Getting Started.

Credentials summary

Credential	Type	Used for	Provided by
Signing & encryption key pairs	Your keys (private stays with you)	JWS signing / JWE decryption	You — Step 2
Bahn public keys	Public (JWK)	Encrypting card data, verifying responses	Bahn — `GET /api/public-keys`
API key (`Bn-Api-Key`)	Secret	Server-side REST calls	Bahn — Step 3
Publishable key (`pk_...`)	Public	Web SDK (client-side)	Bahn — Step 4

Next Steps

Generate Key Pairs — create and export your P-256 signing and encryption key pairs.
Make Your First Request — sign and send a request end-to-end.
Web SDK · Getting Started — initialize the SDK with your publishable key.

Onboarding ​

Overview ​

Step 1 — Create your merchant account ​

Step 2 — Exchange public keys ​

Step 3 — Receive your API key ​

Step 4 — Receive your publishable key ​

Credentials summary ​

Next Steps ​