Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Customer-Present Cloud enables merchants to integrate point-of-sale (POS) devices for in-person card-present transactions. This solution bridges physical payment terminals with your cloud-based software systems.
Accept EMV chip cards, contactless payments, and traditional magnetic stripe cards through integrated POS devices.

​
Key Features

EMV Chip Support

Accept secure EMV chip card transactions

Contactless Payments

Support NFC payments including Apple Pay and Google Pay

Magnetic Stripe

Process traditional swipe transactions

PIN Debit

Handle PIN-based debit transactions

​
Supported Processing Modes

Real-time transaction processing with immediate response.Best for:
  • Traditional POS systems
  • Immediate transaction confirmation
  • Simple checkout flows
Characteristics:
  • Request blocks until complete
  • Immediate response
  • Simple error handling

​
Device Management

​
Device Registration

Register POS devices with your gateway account:
1

Obtain Device

Acquire a compatible POS device from your gateway provider
2

Register Device

Register the device serial number in the merchant control panel
3

Configure Device

Set up device parameters (merchant ID, terminal ID, etc.)
4

Test Device

Verify device connectivity and transaction processing

​
Device Discovery

Discover available devices on your network: 
POST https://api.ionicfi.com/device/discover

{
    "security_key": "YOUR_API_KEY"
}
Response: 
{
    "devices": [
        {
            "device_id": "DEVICE12345",
            "device_name": "Terminal 1",
            "status": "available",
            "ip_address": "192.168.1.100"
        }
    ]
}

​
Transaction Processing

​
Synchronous Transaction

Process a transaction and wait for the result: 
<?php
$url = "https://api.ionicfi.com/device/transact";

$data = array(
    "security_key" => "YOUR_API_KEY",
    "device_id" => "DEVICE12345",
    "type" => "sale",
    "amount" => "25.00",
    "processing_mode" => "synchronous"
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120); // Extended timeout for card insertion

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

​
Asynchronous Transaction

Initiate a transaction and receive webhook notification: 
POST https://api.ionicfi.com/device/transact

{
    "security_key": "YOUR_API_KEY",
    "device_id": "DEVICE12345",
    "type": "sale",
    "amount": "25.00",
    "processing_mode": "asynchronous",
    "webhook_url": "https://yoursite.com/webhook"
}
Immediate Response: 
{
    "status": "pending",
    "transaction_id": "TXN123456",
    "message": "Transaction initiated"
}
Webhook Notification (when complete): 
{
    "transaction_id": "TXN123456",
    "response": "1",
    "responsetext": "SUCCESS",
    "amount": "25.00",
    "card_type": "VISA",
    "last_four": "1111"
}

​
Transaction Types

Process a sale transaction with immediate settlement.
{
    "type": "sale",
    "amount": "25.00"
}
Authorize funds without settlement.
{
    "type": "auth",
    "amount": "25.00"
}
Refund a previous transaction.
{
    "type": "refund",
    "transaction_id": "ORIGINAL_TXN_ID",
    "amount": "25.00"
}
Void an unsettled transaction.
{
    "type": "void",
    "transaction_id": "ORIGINAL_TXN_ID"
}

​
Device Status Monitoring

Monitor device status in real-time: 
POST https://api.ionicfi.com/device/status

{
    "security_key": "YOUR_API_KEY",
    "device_id": "DEVICE12345"
}
Response: 
{
    "device_id": "DEVICE12345",
    "status": "ready",
    "battery_level": 85,
    "last_transaction": "2025-10-30T10:30:00Z",
    "firmware_version": "2.1.5"
}

​
EMV Transaction Flow

1

Initiate Transaction

Send transaction request to device via API
2

Customer Inserts Card

Device prompts customer to insert EMV chip card
3

PIN Entry (if required)

Customer enters PIN for debit transactions
4

Authorization

Device communicates with issuer for authorization
5

Remove Card

Device prompts customer to remove card
6

Receipt

Print or display receipt to customer

​
Contactless Transactions

For contactless (NFC) payments: 
{
    "security_key": "YOUR_API_KEY",
    "device_id": "DEVICE12345",
    "type": "sale",
    "amount": "25.00",
    "entry_mode": "contactless"
}
Contactless transactions typically have faster processing times and reduced friction for customers.

​
Error Handling

Common device error scenarios:
Error CodeDescriptionResolution
DEVICE_OFFLINEDevice not connectedCheck network connectivity
CARD_DECLINEDIssuer declined transactionRequest alternative payment
CHIP_ERROREMV chip malfunctionTry magnetic stripe
TIMEOUTTransaction timeoutRestart transaction
DEVICE_BUSYDevice processing another transactionWait and retry

​
Security Features

End-to-End Encryption

Card data encrypted from device to processor

EMV Compliance

Shift liability for counterfeit fraud

PCI P2PE

Point-to-point encryption validation

Tokenization

Store tokens instead of card data

​
Testing

Use test mode to verify device integration:
  • Test cards provided by the gateway
  • Sandbox environment for non-production testing
  • Device simulators for development
  • Certification process before production
Complete certification testing before processing live transactions with customer cards.

​
Next Steps

Payment API

Integrate with online transactions

Webhooks

Handle asynchronous notifications

Customer Vault

Store payment tokens

Response Codes

Understand device responses