Kodaris Payments Gateway Integration Guide

This guide explains how to integrate Kodaris Payments Gateway into your ecommerce checkoutflow for credit card processing.

Prerequisites

• Kodaris Payments API key
• HTTPS-enabled domain for production

Integration Overview

 The integration uses a two-step process:

1. Server-to-Server: Your backend requests a secure payment form URL from Kodaris
2. 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:

GET /api/system/paymentProcessing/card/formUrl
Authorization: Bearer YOUR_API_KEY

Response:

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

Step 2: Display Payment Form (Client-Side)

Embed the Form

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

<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:

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:

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

noncetokenhere

Parameters:

• amount : Transaction amount (decimal)
• invoiceNumber : Your internal invoice/order ID
• 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