Kody Payments API

This guide provides an overview of using the Kody Payments API and its reference documentation.

Client Libraries
Java Installation
Authenticate to Payments API
Payments API Reference
API data reference and Demo code
More sample code

Client Libraries

Kody provides client libraries for many popular languages to access the APIs. If your desired programming language is supported by the client libraries, we recommend that you use this option.

Available languages:

The advantages of using the Kody Client library instead of a REST API are:

Maintained by Kody.
Built-in authentication and increased security.
Built-in retries.
Idiomatic for each language.
Quicker development.
Backwards compatibility with new versions.

If your coding language is not listed, please let the Kody team know and we will be able to create it for you.

Java Installation

Requirements

Java client supports JDK 17 and above
Gradle (optional), recommended way to install the SDK

Install the Kody Java Client SDK using the following gradle snippet:

dependencies {
    implementation("com.kodypay.grpc:kody-clientsdk-java:0.0.8")
}

The library can also be downloaded from here.

Import in code

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

Authenticate to Payments API

The client library uses a combination of a Store ID and an API key. These will be shared with you during the technical integration onboarding or by your Kody contact.

During development, you will have access to a test Store and test API key, and when the integration is ready for live access, the production credentials will be shared securely with you and associated with a live store that was onboarded on Kody.

The test and live API calls are always compatible, only changing credentials and the service hostname is required to enable the integration in production.

Host names

Development and test: https://grpc-staging.kodypay.com
Live: https://grpc.kodypay.com

API Authentication

Every client library request authenticates with the server using a storeId and an API Key. The storeId is used as a request parameter and the API Key is configured when initialising the client.

Example:

String storeId = "UUID of assigned store"; // STORE_ID
PaymentClient paymentClient = new PaymentClient(HOSTNAME, API_KEY);

TerminalsRequest terminalsRequest = TerminalsRequest.newBuilder()
        .setStoreId(storeId)
        .build();

List<Terminal> response = paymentClient.getTerminals(terminalsRequest);

Replace the STORE_ID, API_KEY and HOSTNAME with the details provided by the Kody team. Note: it is recommended that you store the API_KEY in a secured storage, and insert it into your code via an environment variable.

Payments API Reference

Kody supports the following channels to accept payments via API (using the Java 6 library).

Terminal - In-person payments

Each of these channels have their own collection of services that are available as method calls on the client library:

PaymentClient

Terminal - In-person payments

The Kody Payments API Terminal service has the following methods:

Get List of Terminals: PaymentClient.getTerminals - returns all the terminals of the store and their online status
Create Terminal Payment:PaymentClient.sendTerminalPayment - initiate a terminal payment
Cancel terminal payment: PaymentClient.cancelPayment - cancel an active terminal payment
Get Payment Details PaymentClient.getDetails - get the payment details
Refund terminal payment: PaymentClient.requestRefund - refund a terminal payment

Follow the links for these methods to see the sample code and the data specification.

API data reference and Demo code

Every request to the client library requires authentication and the identifier of the store. See more authentication.

Get list of Terminals

This is a simple and read only method, that returns a list of all terminals assigned to the store, and their online status. You can use this request frequently, and it is a good way to check if your API code is configured properly for authentication.

The terminals request requires the following parameters:

storeId - the ID of your assigned store

TerminalsRequest : Terminal Request

public class TerminalRequest {
  private String storeId; // STORE_ID
}

TerminalsResponse : Terminal Response

public class Terminal {
    private String terminalId;  // Terminal serial number
    private boolean online;     // Online status
}

public class TerminalsResponse {
    private List<Terminal> terminals;  // List of Terminal objects
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

String storeId = "UUID of assigned store"; // STORE_ID
PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

TerminalsRequest terminalsRequest = TerminalsRequest.newBuilder()
        .setStoreId(storeId)
        .build();

List<Terminal> response = paymentClient.getTerminals(terminalsRequest);

Create terminal payment

Send a payment initiation request to a terminal. This request will either make the terminal immediately display the card acquiring screen, or display a tip screen to the user after which it will go to the card acquiring screen.

A test terminal might have multiple apps on the OS screen. Launch the terminal app called [S] Payments.

The terminal must be in the mode: Wait for Orders which can be launched from the terminal app menu. A store that has the feature Wait for Orders enabled will always launch the Wait for Orders screen automatically. This screen can be closed (by tapping the X icon) to access other terminal features, but payments from API will not work until the Wait for Orders screen is started.

PayRequest - Payment Request

public class PayRequest {
    private String amount = null;
    private Boolean showTips = null;
    private PaymentMethod paymentMethod = null;
}

public class PaymentMethod {
  private PaymentMethodType paymentMethodType = null;
}

public enum PaymentMethodType {
  CARD("CARD"),
  ALIPAY("ALIPAY"),
  WECHAT("WECHAT")
}

Request parameters:

storeId - the UUID of your assigned store
terminalId - the serial number of the terminal that will process the payment request. This number is returned by the list of terminals request, or can be found on the back label of the hardware.
amount - amount as a 2.dp decimal number, such as "1.00"
showTips - (optional) whether to show (true) or hide (false) the tip options. Default is (false)
payment_method - (optional) Settings to enable going straight to QR scanning
- payment_method_type - Payment method type: CARD (default), ALIPAY, WECHAT

PayResponse : Payment Response

public enum PaymentStatus {
    PENDING(0),
    SUCCESS(1),
    FAILED(2),
    CANCELLED(3)
}

public class PayResponse {
    private PaymentStatus status = null;            // Status of payment
    private String failureReason = null;            // Optional, reason for failure
    private Map<String, Object> receiptJson = null; // Optional, json blob for receipt data
    private String orderId = null;                  // Unique order ID generated by Kody
    private OffsetDateTime dateCreated = null;      // Timestamp when the response was created
    private String extPaymentRef = null;            // Optional, external payment reference
    private OffsetDateTime datePaid = null;         // Optional, timestamp for date paid
    private String totalAmount = null;              // Optional, total amount
    private String saleAmount = null;               // Optional, sale amount
    private String tipsAmount = null;               // Optional, tips amount
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store";
String terminalId = "Terminal serial number";
String amount = "1.00";
boolean showTips = false;
PaymentMethodType paymentMethodType = PaymentMethodType.CARD;

PayRequest payRequest = PayRequest.newBuilder()
        .setStoreId(storeId)
        .setAmount(amount)
        .setTerminalId(terminalId)
        .setShowTips(showTips)
        .setPaymentMethod(PaymentMethod.newBuilder().setPaymentMethodType(paymentMethodType).build())
        .build();

PayResponse response = paymentClient.sendPayment(payRequest);

// Note: the response will be returned with a PENDING payment status
// the payment details should be retrieved by the client until the payment either completes (SUCCESS/FAILED) or is CANCELLED (see below).

Get Terminal Payment Details

The payment details request requires the following parameters:

storeId - the ID of your assigned store
orderId - the Order ID returned in the initial payment response, a unique UUID value for each payment.

PaymentDetailsRequest: Payment Details Request

public class PaymentDetailsRequest {
    private String storeId;
    private String orderId;
}

PayResponse : Get Payment Detail Response

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store";
String orderId = "UUID of order generated by Kody";

PaymentDetailsRequest paymentDetailsRequest = PaymentDetailsRequest.newBuilder()
        .setStoreId(storeId)
        .setOrderId(orderId)
        .build();

PayResponse response = paymentClient.getDetails(paymentDetailsRequest);

Cancel Terminal Payment

Cancel an ongoing terminal payment, before it has been paid on the terminal.

CancelRequest - Cancel Payment Request

public class CancelRequest {
    private String amount = null;
    private String orderId = null;
}

The cancel payment request requires the following parameters:

storeId - the ID of your assigned store
terminalId - the serial number of the terminal that is processing the payment request
amount - the amount sent in the original payment request, used to find the payment request
orderId - the Order ID returned in the initial payment response, a unique UUID value for each payment

CancelResponse : Cancel Payment Response

public enum PaymentStatus {
    PENDING(0),
    SUCCESS(1),
    FAILED(2),
    CANCELLED(3)
}

public class CancelResponse {
    private PaymentStatus status;   //Cancellation status
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store"; //STORE_ID
String terminalId = "Terminal serial number";
String amount = "1.00";
String orderId = "UUID of order generated by Kody";

CancelRequest cancelRequest = CancelRequest.newBuilder()
        .setStoreId(storeId)
        .setAmount(amount)
        .setTerminalId(terminalId)
        .setOrderId(orderId)
        .build();

PaymentStatus response = paymentClient.cancelPayment(cancelRequest);

Refund Terminal Payment

RefundRequest - Refund Payment Request

public class RefundRequest {
  private String storeId;
  private String orderId;
  private String amount;
}

The refund payment request requires the following parameters:

storeId - the ID of your assigned store
orderId - the Order ID returned in the initial payment response, a unique UUID value for each payment
amount - the amount to refund, should be less than or equal to the original payment amount

RefundResponse : Refund Payment Response

public enum RefundStatus {
    PENDING(0),
    REQUESTED(1),
    FAILED(2)
}

public class RefundResponse {
    private RefundStatus status;             // Refund status
    private String orderId;                  // The order ID sent in the request
    private String failureReason;            // If the refund fails, this will show the reason why
    private OffsetDateTime dateCreated;      // Date when the refund was requested
    private String totalPaidAmount;          // How much was paid for the order
    private String totalAmountRequested;     // The total amount of refunds requested for this order
    private String totalAmountRefunded;      // The total amount of refunds applied to this order
    private String remainingAmount;          // The amount remaining for this order
    private String paymentTransactionId;     // The ID of the payment that needs refunding
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store"; //STORE_ID
String orderId = "UUID of order generated by Kody";
String amount = "1.00";

RefundRequest refundRequest = RefundRequest.newBuilder()
        .setStoreId(storeId)
        .setAmount(amount)
        .setOrderId(orderId)
        .build();

RefundResponse response = paymentClient.requestTerminalRefund(refundRequest);

Ecom - In-person payments

Each of these channels have their own collection of services that are available as method calls on the client library:

PaymentClient

Ecom - Online payments

The Kody Payments API Ecom service has the following methods:

Create Online Payment:PaymentClient.sendOnlinePayment - initiate an online payment
Get Payment Details PaymentClient.paymentDetails - get payment details
Get Payments PaymentClient.getPayments - get payments
Refund online payment: PaymentClient.refundOnlinePayment - refund an online payment

Follow the links for these methods to see the sample code and the data specification.

API data reference and Demo code

Every request to the client library requires authentication and the identifier of the store. See more authentication.

Create online payment

Send a payment initiation request for an online payment. Returns an object with a URL to display an online payment page to the shopper.

PayRequest - Payment Request

public class PaymentInitiationRequest {
    private String storeId = "UUID of assigned store";
    private String orderId = "a unique reference for the payment";
    private String paymentReference = "a unique reference for the payment";
    private String amount = "1.00";
    private String currency = "GBP";
    private String returnUrl = "returnUrl";
    private ExpirySettings expirySettings;
}

public class ExpirySettings {
    private bool showTimer;
    private int expiringSeconds;
}

Request parameters:

storeId - the ID of your assigned store
paymentReference - a unique reference for the payment, sent from the client and returned by the server
amount - the amount to request for the online payment, formatted as a 2.dp decimal number, such as 1.00
currency - the currency for this payment in 3 character ISO format, such as GBP
orderId - a unique order ID for this payment, sent from the client and returned by the server
returnUrl - where the payment form will redirect to after the payment has completed, the return url will have additional query parameters appended to indicate the status of the payment request.
expiry - (optional) setting expiry settings
- showTimer - (optional) flag to show countdown timer in payment page
- expiringSeconds - (optional) how long the payment form will wait until the payment expires and the page will redirect to the return url

PayResponse : Payment Response

public enum ErrorType {
  UNKNOWN("UNKNOWN"),
  DUPLICATE_ATTEMPT("DUPLICATE_ATTEMPT"),
  INVALID_REQUEST("INVALID_REQUEST"),
  CANCELLED("CANCELLED")
}

public class Error {
  private ErrorType type;       //Enum for the error type
  private String message;       //Error message
}

public class PaymentInitiationResponse {
    private Response response;
    private Error error;
}

public class Response {
  private String paymentId;     // Unique identifier created by Kody
  private String paymentUrl;    // The URL to send to the user from your application 
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store";
String orderId = "a unique reference for the order";
String paymentReference = "a unique reference for the payment";
String amount = "1.00";
String currency = "GBP";
String returnUrl = "returnUrl";
ExpirySettings expirySettings = PaymentInitiationRequest.ExpirySettings.newBuilder()
        .setShowTimer(true)
        .setExpiringSeconds(1800)
        .build();

PaymentInitiationRequest paymentInitiationRequest = PaymentInitiationRequest.newBuilder()
        .setStoreId(storeId)
        .setPaymentReference(paymentReference)
        .setAmount(amount)
        .setCurrency(currency)
        .setOrderId(orderId)
        .setReturnUrl(returnUrl)
        .setExpiry(expirySettings)
        .build();

PaymentInitiationResponse response = paymentClient.sendOnlinePayment(paymentInitiationRequest);

Get Payment Details

The payment details request requires the following parameters:

storeId - the ID of your assigned store
paymentIdentifier - One of the two parameters below must be set. They are mutually exclusive
- paymentId - The unique identifier created by Kody
- paymentReference - Your unique payment reference that was set during the initiation

PaymentDetailsRequest: Payment Details Request

public class PaymentDetailsRequest {
    private String storeId;
    private String paymentId;
    private String paymentReference;
}

PaymentDetailsResponse: Payment Details Response

public class PaymentDetailsResponse {
  private String paymentId;                     // Unique identifier created by Kody
  private String paymentReference;              // payment reference
  private String orderId;                       // Unique order ID generated by Kody
  private String orderMetadata;                 // order related metadata
  private PaymentStatus status;                 // Status of payment
  private String paymentDataJson;               // Optional, json blob for payment data
  private OffsetDateTime dateCreated;           // Timestamp when the payment was created
  private OffsetDateTime datePaid;              // Timestamp when the payment was paid
  private String pspReference;                  // Payment Service Provider Reference
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store";
String paymentId = "Payment Id";

PaymentDetailsRequest paymentDetailsRequest = PaymentDetailsRequest.newBuilder()
        .setStoreId(storeId)
        .setPaymentId(paymentId)
        .build();

PaymentDetailsResponse payments = paymentClient.paymentDetails(paymentDetailsRequest);

Get Payments

The payment details request requires the following parameters:

storeId - the ID of your assigned store
pageCursor - set pagination settings.
- page - set an offset of the results. Value of 0 will return payments from the beginning of the data set.
- pageSize - the number of results to be returned per page. Value of 1 will return one record.

GetPaymentsRequest: Get Payments Request

public class PaymentDetailsRequest {
    private String storeId;
    private PageCursor pageCursor;
}

public class PageCursor {
  private int page;
  private int pageSize;
}

PaymentDetails: Payment Details

public class PaymentDetails {
  private String paymentId;                     // Unique identifier created by Kody
  private String paymentReference;              // payment reference
  private String orderId;                       // Unique order ID generated by Kody
  private String orderMetadata;                 // order related metadata
  private PaymentStatus status;                 // Status of payment
  private String paymentDataJson;               // Optional, json blob for payment data
  private OffsetDateTime dateCreated;           // Timestamp when the payment was created
  private OffsetDateTime datePaid;              // Timestamp when the payment was paid
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store";
PageCursor pageCursor = PageCursor.newBuilder()
        .setPageSize(1)
        .build();

GetPaymentsRequest getPaymentsRequest = GetPaymentsRequest.newBuilder()
        .setStoreId(storeId)
        .setPageCursor(pageCursor)
        .build();

List<PaymentDetails> response = paymentClient.getPayments(getPaymentsRequest);

Refund Online Payment

RefundRequest - Refund Payment Request

public class RefundRequest {
  private String storeId;
  private String paymentId;
  private String amount;
}

The refund payment request requires the following parameters:

storeId - the ID of your assigned store
paymentId - unique identifier created by Kody
amount - amount as a 2.dp decimal number, such as "1.00"

RefundResponse : Refund Payment Response

public enum RefundStatus {
    PENDING(0),
    REQUESTED(1),
    FAILED(2)
}

public class RefundResponse {
    private RefundStatus status;             // Refund status
    private String paymentId;                // Unique identifier created by Kody
    private String failureReason;            // If the refund fails, this will show the reason why
    private OffsetDateTime dateCreated;      // Date when the refund was requested
    private String totalPaidAmount;          // How much was paid for the order
    private String totalAmountRequested;     // The total amount of refunds requested for this order
    private String totalAmountRefunded;      // The total amount of refunds applied to this order
    private String remainingAmount;          // The amount remaining for this order
    private String paymentTransactionId;     // The ID of the payment that needs refunding
}

Java Demo

import common.PaymentClient;
import com.kodypay.grpc.pay.v1.*;

PaymentClient paymentClient = new PaymentClient(HOSTNAME, APIKEY);

String storeId = "UUID of assigned store"; //STORE_ID
String paymentId = "Unique identifier created by Kody";
String amount = "1.00";

RefundRequest refundRequest = RefundRequest.newBuilder()
        .setStoreId(storeId)
        .setPaymentId(paymentId)
        .setAmount(amount)
        .build();

RefundResponse response = paymentClient.requestOnlineRefund(refundRequest);

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
cli		cli
docs		docs
gradle/wrapper		gradle/wrapper
samples		samples
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle.kts		build.gradle.kts
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

License

KodyPay/kody-clientsdk-java

Folders and files

Latest commit

History

Repository files navigation

Kody Payments API

Client Libraries

Java Installation

Requirements

Import in code

Authenticate to Payments API

Host names

API Authentication

Payments API Reference

Terminal - In-person payments

API data reference and Demo code

Get list of Terminals

TerminalsRequest : Terminal Request

TerminalsResponse : Terminal Response

Java Demo

Create terminal payment

PayRequest - Payment Request

PayResponse : Payment Response

Java Demo

Get Terminal Payment Details

PaymentDetailsRequest: Payment Details Request

Java Demo

Cancel Terminal Payment

CancelRequest - Cancel Payment Request

CancelResponse : Cancel Payment Response

Java Demo

Refund Terminal Payment

RefundRequest - Refund Payment Request

RefundResponse : Refund Payment Response

Java Demo

Ecom - Online payments

API data reference and Demo code

Create online payment

PayRequest - Payment Request

PayResponse : Payment Response

Java Demo

Get Payment Details

PaymentDetailsRequest: Payment Details Request

PaymentDetailsResponse: Payment Details Response

Java Demo

Get Payments

GetPaymentsRequest: Get Payments Request

PaymentDetails: Payment Details

Java Demo

Refund Online Payment

RefundRequest - Refund Payment Request

RefundResponse : Refund Payment Response

Java Demo

More sample code

About

Resources

License

Stars

Watchers

Forks

Releases 9

Packages 0

Contributors 7

Languages

Packages