Authentication

Authentication to the Kody API is accomplished using a Store ID and an API key. These credentials are provided during your technical integration onboarding or by your Kody contact.

During development, you'll use a test Store and API key. When you're ready for live access, production credentials will be shared securely and linked with your live store. The API endpoints for test and live environments are compatible; only the credentials and service hostname differ.

---

Hostnames

⚠️ Migrate to a regional endpoint. The global endpoints (grpc-staging.kodypay.com and grpc.kodypay.com) are being retired. Switching to the regional endpoint closest to your users gives you more stable connectivity, and global endpoint support may be discontinued in the future. Please migrate as soon as possible.

• Development and Test:

  • For Asia-specific region: https://grpc-staging-ap.kodypay.com
  • For Europe-specific region: https://grpc-staging-eu.kodypay.com

• Live:

  • For Asia-specific region: https://grpc-ap.kodypay.com
  • For Europe-specific region: https://grpc-eu.kodypay.com

Note to Developers: Please set the region based on the user's location. This will route traffic to the closest datacenter, thereby improving connection performance.

---

Examples

Authentication Code Samples

Below are examples in multiple programming languages demonstrating how to set up authentication when calling Kody API services.

Java

import io.grpc.ManagedChannelBuilder;
import io.grpc.Metadata;
import io.grpc.stub.MetadataUtils;
import com.kodypay.ecom.v1.GetPaymentsRequest;
import com.kodypay.ecom.v1.GetPaymentsResponse;
import com.kodypay.ecom.v1.KodyEcomPaymentsServiceGrpc;

class Main {
    public static void main(String[] args) {
        // Setup channel and client with authentication
        Metadata metadata = new Metadata();
        metadata.put(Metadata.Key.of("X-API-Key", Metadata.ASCII_STRING_MARSHALLER), "API_KEY");

        var channel = ManagedChannelBuilder.forAddress("HOSTNAME", 443)
            .useTransportSecurity()
            .build();
        var client = KodyEcomPaymentsServiceGrpc.newBlockingStub(channel)
            .withInterceptors(MetadataUtils.newAttachHeadersInterceptor(metadata));

        // Create GetPayments request
        var request = GetPaymentsRequest.newBuilder()
            .setStoreId("STORE_ID")
            .setPageCursor(GetPaymentsRequest.PageCursor.newBuilder()
                .setPageSize(10)
                .build())
            .build();

        // Fetch payments
        GetPaymentsResponse response = client.getPayments(request);

        // Print payment details
        response.getResponse().getPaymentsList().forEach(payment -> {
            System.out.println("Payment ID: " + payment.getPaymentId());
            System.out.println("Status: " + payment.getStatus());
        });
    }
}

Python

import grpc
import kody_clientsdk_python.ecom.v1.ecom_pb2 as kody_model
import kody_clientsdk_python.ecom.v1.ecom_pb2_grpc as kody_client

# Setup channel and client with authentication
channel = grpc.secure_channel("HOSTNAME", grpc.ssl_channel_credentials())
client = kody_client.KodyEcomPaymentsServiceStub(channel)

# Metadata for authentication
metadata = [("x-api-key", "API_KEY")]

# Create GetPayments request
request = kody_model.GetPaymentsRequest(
    store_id="STORE_ID",
    page_cursor=kody_model.GetPaymentsRequest.PageCursor(page_size=10)
)

# Fetch payments
response = client.GetPayments(request, metadata=metadata)

# Print payment details
for payment in response.response.payments:
    print(f"Payment ID: {payment.payment_id}")
    print(f"Status: {payment.status}")

.NET

using Grpc.Core;
using Grpc.Net.Client;
using Com.Kodypay.Ecom.V1;

class Program
{
    static async Task Main(string[] args)
    {
        // Setup channel and client with authentication
        var channel = GrpcChannel.ForAddress("HOSTNAME");
        var client = new KodyEcomPaymentsService.KodyEcomPaymentsServiceClient(channel);

        // Metadata for authentication
        var metadata = new Metadata
        {
            { "X-API-Key", "API_KEY" }
        };

        // Create GetPayments request
        var request = new GetPaymentsRequest
        {
            StoreId = "STORE_ID",
            PageCursor = new GetPaymentsRequest.Types.PageCursor
            {
                PageSize = 10
            }
        };

        // Fetch payments
        GetPaymentsResponse response = await client.GetPaymentsAsync(request, metadata);

        // Print payment details
        foreach (var payment in response.Response.Payments)
        {
            Console.WriteLine($"Payment ID: {payment.PaymentId}");
            Console.WriteLine($"Status: {payment.Status}");
        }
    }
}

PHP

<?php
require __DIR__ . '/../vendor/autoload.php';

use Com\Kodypay\Ecom\V1\KodyEcomPaymentsServiceClient;
use Com\Kodypay\Ecom\V1\GetPaymentsRequest;
use Grpc\ChannelCredentials;
use Grpc\Status;

// Setup channel and client with authentication
$client = new KodyEcomPaymentsServiceClient('HOSTNAME', [
    'credentials' => ChannelCredentials::createSsl()
]);

// Metadata for authentication
$metadata = ['X-API-Key' => ['API_KEY']];

// Create GetPayments request
$request = new GetPaymentsRequest();
$request->setStoreId('STORE_ID');
$pageCursor = new GetPaymentsRequest\PageCursor();
$pageCursor->setPageSize(10);
$request->setPageCursor($pageCursor);

// Fetch payments
list($response, $status) = $client->GetPayments($request, $metadata)->wait();

if ($status->code !== Status::OK) {
    echo "Error: " . $status->details . PHP_EOL;
} else {
    foreach ($response->getResponse()->getPayments() as $payment) {
        echo "Payment ID: " . $payment->getPaymentId() . PHP_EOL;
        echo "Status: " . $payment->getStatus() . PHP_EOL;
    }
}

---

Remember to replace the following placeholders with your actual values:

• HOSTNAME: Use the regional endpoint for your environment — e.g. grpc-staging-eu.kodypay.com or grpc-staging-ap.kodypay.com for development and test, or grpc-eu.kodypay.com or grpc-ap.kodypay.com for live. Global endpoints are deprecated — see the note above.
• API_KEY: Your API key
• STORE_ID: Your store identifier

For further support or more detailed information, please contact our support team.