Kody Payments API

The Kody Payments API is a set of gRPC services for taking and managing payments across online, in-person, tokenised, and pre-authorisation flows. This page covers everything common to those services — hostnames and regions, authentication, and shared conventions.

APIs

API	What it does	Service
Online Payments	Hosted-page card and wallet payments for e-commerce checkouts.	`KodyEcomPaymentsService`
Terminal Payments	In-person card payments on Kody physical terminals.	`KodyPayTerminalService`
Tokenised Payments	Securely store and reuse a customer's card for future payments.	`KodyEcomPaymentsService`
Pre-Authorisations	Hold funds on a card, then capture or release later.	`KodyPreAuthTerminalService`, `KodyTerminalTokenService`

Client SDKs

Kody publishes gRPC client libraries with the request/response types and service stubs pre-generated, so you don't need to compile the .proto files yourself. Add the library for your language, then follow the examples on each endpoint page.

Language	Package	How to add
Java	`com.kodypay.grpc:kody-clientsdk-java` (Maven Central)	`implementation 'com.kodypay.grpc:kody-clientsdk-java:1.8.3'` (or the latest version)
Python	`kody-clientsdk-python` (PyPI)	`pip install kody-clientsdk-python`
.NET	`kody-dotnet8-client` (NuGet) — KodyPay/kody-clientsdk-dotnet	See .NET setup below
PHP	`kody/kody-php8-grpc-client` — KodyPay/kody-clientsdk-php	See PHP setup below

SDK notes

The generated Java types are grouped by service: Terminal Payments under com.kodypay.grpc.pay.v1.*, Online and Tokenised Payments under com.kodypay.grpc.ecom.v1.*, and Pre-authorisations under com.kodypay.grpc.preauth.v1.*.
Java also needs a gRPC runtime transport, for example io.grpc:grpc-netty-shaded.
For the latest version numbers and runnable samples, see each SDK's GitHub repository, or contact the Kody Support team at support@kody.com.

PHP setup

Requirements: PHP 7.2 or later, Composer, and the gRPC PHP extension.

1. Install via Composer. Add the package (served from a GitHub release) to your composer.json:

{
  "require": {
    "kody/kody-php8-grpc-client": "v1.6.10"
  },
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "kody/kody-php8-grpc-client",
        "version": "v1.6.10",
        "dist": {
          "type": "zip",
          "url": "https://github.com/KodyPay/kody-clientsdk-php/releases/download/v1.6.10/kody-php8-grpc-package.zip"
        }
      }
    }
  ]
}

Then run:

composer install

2. Install the gRPC and Protobuf PHP extensions.

macOS / Linux (prefix with sudo on Linux):

pecl install grpc
pecl install protobuf

Then enable them in your php.ini:

extension=grpc.so
extension=protobuf.so

On Windows, download the gRPC and Protobuf DLLs from pecl.php.net/package/grpc and pecl.php.net/package/protobuf, place them in your PHP ext directory, and add to php.ini:

extension=php_grpc.dll
extension=php_protobuf.dll

For more detail, see the Install gRPC for PHP documentation.

.NET setup

Requirements: .NET 8.0 or later. (Contact the Kody Support team if you need another version.)

Add the SDK to your .csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="kody-dotnet8-client" Version="1.6.3" />
  </ItemGroup>
</Project>

Then restore the dependencies:

dotnet restore

Hostnames and regions

All services share the same hosts. Connect to the endpoint closest to your store's region for the best latency.

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`

Scheme and port

gRPC connections use port 443 over TLS.

Clients that take a host:port (Java, Python, PHP): use <host>:443, e.g. grpc-staging-eu.kodypay.com:443.
Clients that take a full URL (.NET's GrpcChannel.ForAddress): prefix with https://, e.g. https://grpc-staging-eu.kodypay.com.

Use the regional staging host that matches your store while developing, and the matching live host in production.

Authentication

Every request is a gRPC call secured with TLS. Authenticate each call by attaching your API key to the request metadata using the X-API-Key header.

X-API-Key: <YOUR_API_KEY>

Requests without a valid key are rejected.

Best practice

Never share your secret API keys via unencrypted channels. If you need to rotate a compromised key or provision a new one safely, contact the Kody Support team at support@kody.com.

Common placeholders

The placeholder tokens listed below are used throughout the individual endpoint pages to represent values specific to your account. When implementing the endpoint examples found in those pages, replace these placeholders with your actual values:

Placeholder	Description
`HOSTNAME`	Your regional gRPC host, e.g. `grpc-staging-eu.kodypay.com` (staging) or `grpc-eu.kodypay.com` (live)
`API_KEY`	Your Kody API key
`STORE_ID`	Your Kody store identifier
`TERMINAL_ID`	Your terminal serial number (terminal and pre-auth flows)
`TOKEN_ID`	Token-creation request identifier returned by `CreateCardToken`
`PAYER_REFERENCE`	Your customer identifier (tokenised flows)
`PAYMENT_TOKEN`	The reusable card token used to take payments

Conventions

The following conventions apply across all Kody Payments APIs:

Amounts. Online, tokenised, and pre-authorisation requests use amount_minor_units (an integer in the currency's minor unit — e.g. 2000 for GBP 20.00). Terminal payments and refunds use a decimal string with two decimal places (e.g. "20.00").
Currency. Always an ISO 4217 three-letter code (e.g. GBP, EUR, HKD), and must match the store's configured currency where noted.
Idempotency. Where a request accepts an idempotency_uuid, send a unique, client-generated UUID so retries are processed at most once.
References. Your own payment_reference, order_id, and token_reference values are echoed back in responses so you can reconcile against your systems.
Timestamps. Returned as google.protobuf.Timestamp (UTC).
Errors. Most responses use a oneof of a success payload or an Error with a type enum and human-readable message.

Need help?

For further support or more detailed information, contact the Kody Support team at support@kody.com.

APIs​

Client SDKs​

PHP setup​

.NET setup​

Hostnames and regions​

Authentication​

Common placeholders​

Conventions​

Need help?​