Integrating as a Software Platform
Build merchant onboarding on your backend and contactless checkout in your mobile app. Koard facilitates payment requests to each merchant's configured processor; your app owns its customers, orders, operator permissions, and checkout experience.
Divide Responsibilities
| Your backend | Your mobile app |
|---|---|
| Authorize users against the intended merchant. | Authenticate the merchant through the SDK. |
| Create permitted partner/merchant accounts and board processor credentials. | Let the operator select an active merchant location in settings. |
| Link terminals to locations and issue merchant login credentials. | Complete platform linking/enrollment and readiness. |
| Use scoped REST keys for provisioning, reporting, and recovery. | Use the intended scoped SDK client key and released dependency. |
| Verify and persist webhooks; reconcile orders and settlement. | Submit a payment once, inspect its result, and preserve operation IDs for recovery. |
Keep privileged management keys on the server. An API key's hierarchy access is not a substitute for your own user authorization. See Account Hierarchy and Credentials.
1. Model Merchant Ownership
Create partners when you need to organize descendant businesses, and create a merchant account for the business accepting payments. Use the matching account creation request. Merchant tax ID, MCC, and payment defaults belong to the merchant.
Retain the environment with the merchant, terminal, location, and processor configuration IDs. Do not use another merchant's location when its credentials change.
2. Provision Routing and Credentials
Follow Merchant Setup via API: select an assigned processor configuration, create the merchant, board its terminal, link a location, and issue SDK credentials. Use the processor's own boarding fields.
Deliver merchant login credentials through a trusted channel. New account creation does not automatically issue a REST key. Use API Key Management separately when needed.
3. Build Standard Checkout
Start with the iOS or Android quickstart. Then integrate the full platform payment and response-handling example into your app.
Let an operator choose the active location in settings, validate its linked terminal, and display the choice before payment. Keep checkout blocked through login, location changes, linking/enrollment, and reader preparation.
Persist each supported operation ID with your order before the call. Process the actual returned status and amounts, including partial approvals and surcharge decisions. Use the Payment Lifecycle to distinguish a preauth hold, capture, reversal, refund, and settlement.
4. Reconcile on the Backend
Use signed webhooks with durable delivery persistence and idempotent business handlers. Track both transaction and event IDs; events describe operations and can have declined, pending, or error outcomes.
Expose an authenticated outcome recovery path for the mobile app rather than shipping a privileged reporting key or blindly retrying charges. Reconcile processor-specific batches and reports against your order ledger.
5. Launch by Platform and Processor
Use the Launch Checklist, then complete the platform approval and production configuration required for your distribution path. Scope tests to the assigned processor, card brands, supported payment operations, and approved device configurations. A working SDK demo alone is not completion of the launch process.
Contact support@koard.com to coordinate account access, processor configuration, and integration support.
