Introduction

Kody's client SDKs give you one integration for payments taken on a screen and payments taken in person. They wrap the gRPC Payments API, handle authentication and retries for you, and stay compatible as the API grows.

You do not have to write code to see it work. The demo store runs every flow against staging, with the default demo credentials or your own, so you can watch a payment succeed — and fail — before you install anything.

Choose your payment flow

What you need to do	Where the card is	Start here
Sell on a website or app; the customer pays on a Kody-hosted page	On a screen	Online Payments
Same, but the customer never leaves your page	On a screen	Checkout Component
Charge a saved card with the customer not present	Either	Tokenised Payments
Take payment at a Kody terminal, final amount known	In person	Terminal Payments
Hold an amount now, capture the real one later — hotel, bar tab, rental	In person	Pre-Authorisations

Two things worth knowing before you choose:

• One Store ID and one API key cover both channels. Selling online and in person is not a second onboarding.
• A saved card can be charged from either channel. Where the card is presented decides which call saves it; what you do with the token afterwards is a separate choice.

What the SDKs handle for you

• Authentication. Your API key is attached to every call; no header assembly.
• Retries. Failed requests are retried with backoff.
• Protobuf over gRPC. Smaller payloads and generated types instead of hand-written JSON models.
• Language idioms. Native types and error handling in each language, not a thin HTTP wrapper.
• Backward compatibility. New API fields do not break a working integration.

The SDKs are server-side only. Never place an API key in a browser, a mobile app, or anything else a customer can read.

Client libraries

Language	Repository
Java	kody-clientsdk-java
Python	kody-clientsdk-python
PHP	kody-clientsdk-php
.NET	kody-clientsdk-dotnet

Every example in this documentation is available in all four. If you need another language, talk to your Kody account manager — the API is plain gRPC, so a generated client is always an option.

Installation is covered in the Installation Guide.

Credentials and endpoints

Your Store ID and API key come from the Kody team — ask your account manager, or email integrations@kody.com. Test and live are separate stores, not two modes of one store: each has its own Store ID, API key and region. Request the staging pair to build against, and the live pair when you are ready to go live. One key can cover several stores in the same account, but staging and live stay apart.

Kody publishes regional endpoints only. There is no global host to fall back on, so choosing a region is not optional.

Region	Development and test	Live
Asia-Pacific	grpc-staging-ap.kodypay.com	grpc-ap.kodypay.com
Europe	grpc-staging-eu.kodypay.com	grpc-eu.kodypay.com

The region is part of the hostname, not a request field — you cannot switch region at call time. Set it from where your merchant operates. A live key against a staging host fails with no explanation, which is the most common setup error we see.

Full details in Authentication.

Try it in the demo store

ecom-php-demo.kody.com is a working PHP store that calls the same staging API you are about to integrate against. Each page shows the request it made, the response it got, and the code that produced it.

Every row below opens the demo store on staging. Demo Site takes them one at a time, with the settings that matter and what to watch for in each.

Page by page

Demo page	What it shows you	Key calls	Reference
Online Payment Demo	Full hosted-page payment: create the link, pay, come back, confirm	InitiatePayment → PaymentDetails	Online Payments
Checkout Component In Iframe	The same payment embedded in the page, with the postMessage outcome	InitiatePayment + isEmbeddedInIframe=1	Checkout Component
Terminals	Every terminal assigned to the store, and its online status	Terminals	Terminal Payments
Token Payment	Saving a card, then charging it with no customer present	CreateCardToken → PayWithCardToken	Tokenised Payments
Card Tokens	Saved cards on the store, and deleting one	GetCardTokens, DeleteCardToken	Tokenised Payments
All Transactions	Online payment history with status and refunds	GetPayments, Refund	Online Payments
View Logs	The raw request and response for everything above	—	Overview

Point it at your own store

Open Settings on the demo store and paste in your own staging Store ID and API key; Reset restores the demo defaults, which start at Store ID c4cebf51-b006-4bb9-acd5-bb4bcdbd6e09. That default store is shared with every other reader, so its transactions, saved cards and terminals are not yours — switch to your own staging store as soon as you have one.

No terminal to test against? Email integrations@kody.com or your Kody representative with your staging Store ID and the model you need (S1F2 or AMS1).

Make it fail on purpose

You need the decline paths working before go-live, and staging lets you trigger them on demand. In person, the last three digits of the amount select the response; online and MOTO payments ignore the amount and turn on whether the expiry date and security code are entered correctly. The amounts, the card numbers and the amounts reserved for internal testing are on Test Cards.

Before you ship

• Mark an order paid only after a server-side check. A return_url redirect and a browser message carry no proof of outcome — confirm with PaymentDetails.
• Handle every PaymentStatus, not only success. Pending and expired are normal outcomes.
• Send an idempotency key so a retry cannot take the money twice.
• Refund in the store that took the payment. A payment taken in one store cannot be refunded from another.
• Every pre-authorisation hold must end in a capture or a release.
• Get your domain allowlisted on day one if you are embedding the checkout. It has a lead time, and the iframe renders blank until it lands.
• Turn on Wait for Orders on any terminal you drive from the API. Without it the terminal will not accept an API-initiated payment.

Go live

Live is fully compatible with test: the same calls, the same request shapes. What changes is the store you point at — its own Store ID, API key and regional host.

Before your first real transaction:

• Live Store ID and API key requested from the Kody team and confirmed as the live store's
• Host switched to the live regional endpoint for that store
• Payment methods enabled on the live store
• Orders marked paid only after a server-side PaymentDetails check
• At least one deliberate decline exercised end to end
• Terminal settings confirmed with your Kody account manager:
  • Wait for Orders — required for an API integration
  • Store name display
  • Receipt layout and logos
  • Receipt auto-printing
  • Access PINs

Your Kody account manager can confirm the live store carries everything on this list.