Kodaris Payments Gateway Integration - One Time Payment Flow

This guide explains how to integrate Kodaris Payments Gateway into your ecommerce checkout flow for credit card processing using the One Time Payment Flow.

Prerequisites

Kodaris API Key Secret

Integration Overview

The integration uses a two-step process:

Server-to-Server: Your backend requests a secure payment form URL from Kodaris
Client-Side: Your frontend displays the form in an iframe and handles the payment flow

Step 1: Request Payment Form URL (Server-Side)

Make a server-to-server call to obtain a secure credit card form URL:

None
GET /api/system/paymentProcessing/card/formUrl?companyID=123
Authorization: Bearer YOUR_API_KEY

Parameters:

companyID (optional): The customer company ID that the card and transaction will be tied to

Response:

JSON
{
"success": true,
"code": 200,
"messages": [],
"errors": [],
"data":"https://payments.kodaris.com/api/user/kodarispayments/cardForm?nonce=nonceToken",
"requestId": "some_string"
}

Important:

Form URLs are single-use only
URLs expire after a short time if not accessed
Request a new URL if the form needs to be reloaded or an error occurs

Step 2: Display Payment Form (Client-Side)

Embed the Form

Embed the form URL in an iframe on your checkout page:

HTML
<iframe
id="kodaris-payment-iframe"
src="FORM_URL_FROM_STEP_1"
width="100%"
height="400">
</iframe>
<button id="submit-payment">Complete Payment</button>

Submit the Form

Trigger form submission from outside the iframe:

Javascript
const kodarisPaymentIframe = document.getElementById('kodaris-payment-iframe');
const submitButton = document.getElementById('submit-payment');

submitButton.onclick = () => {
kodarisPaymentIframe.contentWindow.postMessage(
{ type: 'kpSubmit' },
'https://payments.kodaris.com'
);
};

// Handle Payment Response
// Listen for messages from the payment iframe:
window.addEventListener('message', async (ev) => {
// Security: Only trust messages from Kodaris
if (ev.origin !== 'https://payments.kodaris.com') {
console.error('Untrusted message origin');
return;
}

if (ev.data.type === 'kpSubmitSuccess') {
const paymentNonce = ev.data.nonce;
// TODO Send nonce to your server for processing
} else if (ev.data.type === 'kpSubmitError') {
alert('Payment failed. Please try again.');
// TODO Handle validation or submission errors
}
});

Step 3: Process Payment (Server-Side)

Once you receive the nonce token from the client, process the payment on your server:

None
POST /api/system/paymentProcessing/card/charge/byNonce?amount=1.23&invoiceNumber=1234&companyID=123
Authorization: Bearer YOUR_API_KEY
Content-Type: text/plain

noncetokenhere

Parameters:

amount: Transaction amount (decimal)
invoiceNumber (optional): Your internal invoice/order ID
companyID (optional): The customer company ID to associate with the transaction
Request body: The nonce token as plain text

Security Considerations

Always validate message origins (https://payments.kodaris.com)
Process payments server-side only - never expose API keys to clients
Nonce tokens are single-use and expire quickly