Act for a Connected Merchant

A platform acts for a connected merchant with the Account header. The header behaves the same across every Bahn service. This page shows how it applies to Terminal.

Read the overview and the server-side integration first.

Before you start

The platform must have an active connection to the merchant. Request the connection through your account manager.

The platform must hold an account-keyed API key issued through the portal.

Make a call for a connected merchant

Send the request with the platform's API key and name the merchant to act for in the Account header.

curl -X POST "https://bn.cake.vn/api/payment_intents" \
  -H "Bn-Api-Key: $PLATFORM_SECRET_KEY" \
  -H "Account: $CONNECTED_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "vnd",
    "payment_method_types": ["card_present"]
  }'

• Bn-Api-Key names the platform.
• Account names the merchant to act for.
• The PaymentIntent and every downstream webhook are attributed to the connected merchant, not to the platform.

Access rules

• The connection must exist and must be active.
• Both the platform's Account and the connected merchant's Account must be active.
• A legacy credential cannot act for another account. Platforms must use account-keyed API keys issued through the portal.

If the connection does not exist, the API returns an access-denied error. The error does not say which part failed, by design.

Send a PaymentIntent to a Reader

Terminal operations for a connected merchant use the same endpoints as the server-side integration. Add the Account header on every request.

curl -X POST "https://bn.cake.vn/api/terminal/readers/$READER_ID/process_payment_intent" \
  -H "Bn-Api-Key: $PLATFORM_SECRET_KEY" \
  -H "Account: $CONNECTED_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "YOUR_PAYMENT_INTENT_ID",
    "process_config": { "enable_customer_cancellation": true }
  }'

Readers approved for the connected merchant's Terminals are reachable the same way as for the merchant's own backend. A public endpoint for listing Readers by Terminal is on the roadmap. Today, contact your account manager to confirm which Readers are approved for a given Terminal.

Publishable key path

The SDK publishable-key path also supports connected accounts via the same Account header. See the SDK documentation for details.

Next step

Reference for objects, statuses, errors, and webhook events.