Terminal Overview
Use Terminal to accept in-person payments on a physical Reader. Your backend sends a PaymentIntent to the Reader. The Reader collects the payment method from the customer. Bahn sends the result to your webhook.
High-level flow
sequenceDiagram
autonumber
participant Merchant as Merchant backend
participant API as Bahn API
participant Reader
participant Customer
Merchant ->> API: Create PaymentIntent
API -->> Merchant: payment_intent (requires_payment_method)
Merchant ->> API: Send PaymentIntent to Reader
API -->> Merchant: reader_action (in_progress)
API ->> Reader: Start the action
Reader ->> Customer: Prompt to tap, insert, or scan
Customer ->> Reader: Payment method
Reader ->> API: Authorize the payment
API -->> Merchant: Webhook with the result
Merchant ->> Merchant: Complete the sale
Concepts
| Object | Description |
|---|---|
| Account | A bank-account holder on Cake. The party that receives funds. |
| Merchant | The trading entity under an Account. |
| Location | A physical place a merchant trades from. Belongs to the Account. |
| Terminal | One registration at a Location. Carries the network terminal id. |
| Reader | One cashier device. A Reader is approved for one Terminal before it can take payments. Approval happens on the Reader itself. |
| PaymentIntent | One payment session. Same object as for online payments. |
| Reader action | One unit of work that the Reader runs, for example process_payment_intent. A Reader runs one action at a time. |
Who creates what
| Actor | Creates |
|---|---|
| Admin or portal | Account, Merchant, Location, Terminal |
| Cashier device | Reader (self-registered on first setup) |
| Cashier (on the Reader) | Approval of the Reader for one Terminal |
| Your backend | PaymentIntent |
| Your backend | Sends the PaymentIntent to a Reader |
Payment methods
| Method | Description |
|---|---|
card_present | Contact or contactless EMV card. |
napas_qr | VietQR. |
visa_qr | Visa QR. |