# API Overview

Introduction to the Inovio Payment Service API, its transport and encoding requirements, and how testing and production environments are separated.

Source: https://developer.inoviopay.com/api/overview.html  
Markdown: https://developer.inoviopay.com/api/overview.md

The Inovio Payment Service API is designed to allow merchants to communicate and process online transactions with the payment gateway's transaction processing system. All cardholder and transaction data are sent over the internet using the TLS 1.2 cryptographic protocol.

The API expects all data to be URL and UTF-8 encoded, using character set ISO-8859-1 over HTTPS.

**Testing & Production Environments:** At Inovio, merchants use the exact same account credentials and API endpoints for both testing and production. The distinction lies purely in how your site is configured within the Inovio portal. During testing, your site's transactions will be pointed to a "Test Bank" Merchant ID (MID), allowing you to safely simulate payments. When you are ready to process real transactions, this configuration is simply updated in the portal to point to your live production MID(s), requiring zero changes to your code.

**POST** `https://api.inoviopay.com/payment/pmt_service.cfm`

Authentication parameters (`REQ_USERNAME`, `REQ_PASSWORD`, `SITE_ID`) are required on every request. You can verify your credentials are working with the `TESTAUTH` action, documented on the [Authentication](https://developer.inoviopay.com/api/authentication.md#auth) page.

## Service Availability

Use the `TESTGW` action to check if the Payment Service is available to process requests. This is useful for uptime monitoring and health checks.

| Parameter | Description |
|---|---|
| `REQUEST_ACTION` (required) | Must be set to `TESTGW`. |
| `REQ_USERNAME` (required) | Merchant's Service username. |
| `REQ_PASSWORD` (required) | Merchant's Service password. |
| `SITE_ID` (required) | Merchant's website ID. |
| `REQUEST_API_VERSION` (required) | Must be sent as `4.14`. |
| `REQUEST_RESPONSE_FORMAT` (optional) | Format of the response. Accepts `XML` or `JSON`. |

**cURL**

```bash
curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=TESTGW&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON"
```

**PHP**

```php
use Inovio\Gateway\{Credentials, InovioClient};

$client = new InovioClient(new Credentials('api_user', 'P@ssw0rd!', '12345'), 'SANDBOX');

$health = $client->testAvailability();

echo $health->ok, "\n";
echo $health->outcome->service->code, ' ', $health->outcome->service->advice, "\n";
```

**Node**

```ts
import { InovioClient } from '@inovio/gateway-sdk';

const client = new InovioClient(
  { reqUsername: 'api_user', reqPassword: 'P@ssw0rd!', siteId: '12345' },
  { environment: 'SANDBOX' }
);

const health = await client.testAvailability();

console.log(health.ok);
console.log(health.outcome.service.code, health.outcome.service.advice);
```

**Python**

```python
from inovio_gateway import Credentials, InovioClient

client = InovioClient(Credentials("api_user", "P@ssw0rd!", "12345"), environment="SANDBOX")

health = client.test_availability()

print(health.ok)
print(health.outcome.service.code, health.outcome.service.advice)
```

**Java**

```java
InovioClient client = new InovioClient(
    new InovioClient.Credentials("api_user", "P@ssw0rd!", "12345"));

HealthResult health = client.testAvailability();

System.out.println(health.ok());
System.out.println(health.outcome().service().code() + " " + health.outcome().service().advice());
```

**Response**

```json
{
  "REQUEST_ACTION": "TESTGW",
  "TRANS_STATUS_NAME": "",
  "TRANS_VALUE": "",
  "TRANS_ID": "",
  "CUST_ID": "",
  "XTL_CUST_ID": "",
  "MERCH_ACCT_ID": "",
  "CARD_BRAND_NAME": "",
  "PMT_L4": "",
  "API_RESPONSE": "0",
  "API_ADVICE": " ",
  "SERVICE_RESPONSE": 101,
  "SERVICE_ADVICE": "Service Available",
  "PROCESSOR_RESPONSE": 0,
  "PROCESSOR_ADVICE": " ",
  "INDUSTRY_RESPONSE": 0,
  "INDUSTRY_ADVICE": " ",
  "REF_FIELD": "",
  "PROC_NAME": "",
  "AVS_RESPONSE": "",
  "CVV_RESPONSE": "",
  "REQUEST_API_VERSION": "4.14",
  "TRANS_NTOKEN_USED": 0
}
```