iPayOS Payment Gateway API

Comprehensive API Documentation for iPayOS Payment Processing

API Overview

iPayOS provides easy smart and secured platform for payments. It builds single and common bridge for merchants, service providers, consumers and money authorities, which brings new user experience in fintech.

Base URL

https://gateway.ipayos.lk/ncc_controller.php

Authentication

All requests require the following credentials in the request body:

  • clientId - Client ID
  • token - Token
  • secret - Secret

🧪 Test Credit Card Details

  • Card No: 4564456445644564
  • Expiry Date: 05/26
  • CCV: 123
Payment Flows

Flow 1: On the Fly Enter Card Details

1
NCC INIT Request
2
NCC INIT Response with redirection URL
3
Redirect to Bank/Payment Gateway
4
Enter Card Details
5
Redirect to User
6
NCC COMPLETE Request
7
NCC COMPLETE Response - Successful payment
API Endpoints
POST /ncc_controller.php NCC INIT - Initialize Payment

Initialize a payment request to redirect customer to payment gateway.

Request Parameters

Parameter Type Required Description
clientId string Yes Client ID
token string Yes Token
secret string Yes Secret
requestType string Yes Must be "NCC_INIT"
transactionAmount string Yes Amount in decimal format (e.g., "100.00")
msisdn string Yes Customer mobile number
email string Yes Customer email address
clientReference string Yes Unique reference from your system
redirectUrl string Yes URL to redirect after payment

Example Request

{ "clientId": "XXXX", "token": "token_xxxxxxxx", "secret": "secret_xxxxx", "requestType": "NCC_INIT", "transactionAmount": "100.00", "msisdn": "+1234567890", "email": "customer@example.com", "clientReference": "ORDER_001", "redirectUrl": "https://example.com/callback" }

Response Examples

200 OK Success Response
{ "status": 0, "statusDescription": "SUCCESS", "data": { "requestId": "REQ_123456789", "paymentPageUrl": "https://gateway.ipayos.lk/payment/REQ_123456789" } }
POST /ncc_controller.php NCC COMPLETE - Complete Payment

Complete a payment request using the requestId from NCC_INIT response.

Request Parameters

Parameter Type Required Description
clientId string Yes Client ID
token string Yes Token
secret string Yes Secret
requestType string Yes Must be "NCC_COMPLETE"
requestId string Yes Request ID from NCC_INIT response

Example Request

{ "clientId": "XXXX", "token": "token_xxxxxxxx", "secret": "secret_xxxxx", "requestType": "NCC_COMPLETE", "requestId": "REQ_123456789" }

Response Examples

200 OK Success Response
{ "status": 0, "statusDescription": "SUCCESS", "data": { "nccReference": "NCC123456789", "responseText": "APPROVED" } }
200 OK Failure Response
{ "status": 5, "statusDescription": "GATEWAY_ERROR", "data": { "nccReference": "NCC123456789", "responseText": null } }
Error Codes
Status Code Description Possible Causes
0 SUCCESS Request processed successfully
1 INVALID_PARAMETERS Missing or invalid required parameters
2 UNAUTHORIZED Invalid credentials (clientId, token, secret)
3 INSUFFICIENT_FUNDS Insufficient funds in customer account
4 CARD_DECLINED Card was declined by issuer
5 GATEWAY_ERROR Internal gateway error
6 TIMEOUT Request timeout
7 INVALID_CARD Invalid card details
8 EXPIRED_CARD Card has expired
9 BLOCKED_CARD Card is blocked
10 LIMIT_EXCEEDED Transaction limit exceeded
Integration Guide

Getting Started

  1. Retrieve your Client ID, Token, and Secret

Testing

Use the provided test credit card details for testing your integration:

  • Card Number: 4564456445644564
  • Expiry Date: 05/26
  • CCV: 123

Security Best Practices

  • Always use HTTPS for all API requests
  • Never expose your credentials in client-side code
  • Implement proper error handling and logging
  • Validate all input parameters before sending requests
  • Store sensitive data securely

Support

For technical support and integration assistance, please contact: