Payment Items

Overview

Payment Items endpoints provide access to the products and services configured for merchant transactions. These endpoints allow merchants to retrieve available payment options, view detailed configurations, and understand pricing and requirements before initializing transactions.

1. Get Payment Items

Endpoint: GET /api/v1/transactions/in/payment-items

Purpose: Retrieves a complete list of all active payment items configured for the merchant account.

Authentication: Bearer token (merchant_secret_key) in Authorization header

Code Snippets

JavaScript
TypeScript
Java
Python
C#

const url = "https://ags.payislands.com/api/v1/transactions/in/payment-items";

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MERCHANT_SECRET_KEY}` },
});

const json = await res.json();
console.log(json);

const url = "https://ags.payislands.com/api/v1/transactions/in/payment-items";

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MERCHANT_SECRET_KEY as string}` },
});

const json = (await res.json()) as unknown;
console.log(json);

import okhttp3.*;
import java.io.IOException;

public class GetPaymentItems {
  public static void main(String[] args) throws IOException {
    String url = "https://ags.payislands.com/api/v1/transactions/in/payment-items";
    String merchantSecretKey = System.getenv("MERCHANT_SECRET_KEY");

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .addHeader("Authorization", "Bearer " + merchantSecretKey)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import os
import requests

url = "https://ags.payislands.com/api/v1/transactions/in/payment-items"
headers = {"Authorization": f"Bearer {os.environ['MERCHANT_SECRET_KEY']}"}

resp = requests.get(url, headers=headers, timeout=30)
print(resp.status_code, resp.text)

using System.Net.Http;
using System.Net.Http.Headers;

var url = "https://ags.payislands.com/api/v1/transactions/in/payment-items";
var merchantSecretKey = Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", merchantSecretKey);

var resp = await http.GetAsync(url);
var body = await resp.Content.ReadAsStringAsync();
Console.WriteLine(body);

Sample cURL Request

curl -X GET "https://ags.payislands.com/api/v1/transactions/in/payment-items" \
  -H "Authorization: Bearer {{merchant_secret_key}}"

Success Response (200 OK)

{
  "status": true,
  "message": "payment items fetched successfully",
  "data": [
    {
      "id": 3,
      "core_service_business_id": 2,
      "name": "Testing Item",
      "description": null,
      "amount": "1000",
      "form_data": [],
      "transaction_split_code": "TS_PSL2v2CwhVQoGCG8cdf9CoEOiGn",
      "is_enumerated_data": false,
      "category": 1,
      "category_details": {
        "id": 1,
        "name": "Government",
        "status": 1
      },
      "sub_category": 1,
      "sub_category_details": {
        "id": 1,
        "name": "Federal",
        "status": 1
      },
      "status": 1,
      "is_deleted": false,
      "created_at": "2024-09-20T06:06:30.215Z",
      "allow_quick_print": true
    },
    {
      "id": 13,
      "core_service_business_id": 2,
      "name": "Coke Zero",
      "description": null,
      "amount": "500000",
      "form_data": [
        {
          "name": "Name",
          "type": "input",
          "value": "",
          "options": [],
          "required": true
        },
        {
          "name": "Age",
          "type": "input",
          "value": "",
          "options": [],
          "required": true
        }
      ],
      "transaction_split_code": "TS_PSL2E7qXJkAGp4wyuIDDwn2E83U",
      "is_enumerated_data": false,
      "category": 1,
      "category_details": {
        "id": 1,
        "name": "Government",
        "status": 1
      },
      "sub_category": 1,
      "sub_category_details": {
        "id": 1,
        "name": "Federal",
        "status": 1
      },
      "status": 1,
      "is_deleted": false,
      "created_at": "2024-10-07T06:50:56.339Z",
      "allow_quick_print": true
    }
  ],
  "statusCode": 200
}

Failure Response (403 Forbidden)

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403
}

2. Get Payment Item Details

Endpoint: GET /api/v1/transactions/in/payment-item/{payment_item_id}

Purpose: Fetches comprehensive details for a specific payment item by ID.

Authentication: Bearer token (merchant_secret_key) in Authorization header

Path Parameter: payment_item_id (Integer) - Unique identifier of the payment item

Code Snippets

JavaScript
TypeScript
Java
Python
C#

const paymentItemId = 3;
const url = `https://ags.payislands.com/api/v1/transactions/in/payment-item/${paymentItemId}`;

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MERCHANT_SECRET_KEY}` },
});

const json = await res.json();
console.log(json);

const paymentItemId = 3;
const url = `https://ags.payislands.com/api/v1/transactions/in/payment-item/${paymentItemId}`;

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MERCHANT_SECRET_KEY as string}` },
});

const json = (await res.json()) as unknown;
console.log(json);

import okhttp3.*;
import java.io.IOException;

public class GetPaymentItemDetails {
  public static void main(String[] args) throws IOException {
    int paymentItemId = 3;
    String url = "https://ags.payislands.com/api/v1/transactions/in/payment-item/" + paymentItemId;
    String merchantSecretKey = System.getenv("MERCHANT_SECRET_KEY");

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .addHeader("Authorization", "Bearer " + merchantSecretKey)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import os
import requests

payment_item_id = 3
url = f"https://ags.payislands.com/api/v1/transactions/in/payment-item/{payment_item_id}"
headers = {"Authorization": f"Bearer {os.environ['MERCHANT_SECRET_KEY']}"}

resp = requests.get(url, headers=headers, timeout=30)
print(resp.status_code, resp.text)

using System.Net.Http;
using System.Net.Http.Headers;

var paymentItemId = 3;
var url = $"https://ags.payislands.com/api/v1/transactions/in/payment-item/{paymentItemId}";
var merchantSecretKey = Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", merchantSecretKey);

var resp = await http.GetAsync(url);
var body = await resp.Content.ReadAsStringAsync();
Console.WriteLine(body);

Sample cURL Request

curl -X GET "https://ags.payislands.com/api/v1/transactions/in/payment-item/3" \
  -H "Authorization: Bearer {{merchant_secret_key}}"

Success Response (200 OK)

{
  "status": true,
  "message": "payment item details fetched successfully",
  "data": {
    "id": 3,
    "core_service_business_id": 2,
    "name": "Testing Item",
    "description": null,
    "amount": "1000",
    "form_data": [],
    "transaction_split_code": "TS_PSL2v2CwhVQoGCG8cdf9CoEOiGn",
    "is_enumerated_data": false,
    "category": 1,
    "category_details": {
      "id": 1,
      "name": "Government",
      "status": 1,
      "delete_at": null,
      "created_at": "2024-09-12T20:31:41.030Z",
      "created_by": 1,
      "is_deleted": false,
      "updated_at": "2024-09-12T20:31:41.030Z"
    },
    "sub_category": 1,
    "sub_category_details": {
      "id": 1,
      "name": "Federal",
      "status": 1,
      "delete_at": null,
      "created_at": "2024-09-12T20:31:41.583Z",
      "created_by": 1,
      "is_deleted": false,
      "updated_at": "2024-09-12T20:31:41.583Z",
      "business_registration_type_id": 1
    },
    "status": 1,
    "is_deleted": false,
    "created_at": "2024-09-20T06:06:30.215Z",
    "allow_quick_print": true
  },
  "statusCode": 200
}

Key Fields in Payment Item Objects

Group	Field	Type	Description	Example / Notes
Identification	`id`	integer	Unique payment item identifier.	`3`
Identification	`name`	string	Display name.	`"Testing Item"`
Identification	`description`	string \| null	Additional product info (often `null`).	`null`
Identification	`core_service_business_id`	integer	Associated business identifier.	`2`
Pricing	`amount`	string	Base price in Naira (NGN major units), with up to two decimal places. `"1000"` means ₦1,000.00. Fixed items have a value; variable items often use `"0"`.	`"1000"`, `"500000"`, `"0"`
Form	`form_data`	array	Custom fields required to pay for this item.	`[]` or `[{name,type,value,options,required}]`
Form	`is_enumerated_data`	boolean	Indicates whether the item uses enumerated data.	`false`
Revenue split	`transaction_split_code`	string	Revenue split configuration ID.	`TS_PSL...`
Classification	`category`	integer	Category ID.	`1`
Classification	`category_details`	object	Category metadata (name, status, etc.).	`{ id, name, status, ... }`
Classification	`sub_category`	integer	Sub-category ID.	`1`
Classification	`sub_category_details`	object	Sub-category metadata.	`{ id, name, status, ... }`
Flags	`status`	integer	Item status: typically `1` = active.	`1`
Flags	`is_deleted`	boolean	Whether the item is deleted/archived.	`false`
Flags	`allow_quick_print`	boolean	Whether receipts/quick print is supported.	`true`
Flags	`can_edit_item`	boolean	Whether this item can be edited (in detailed response).	`true/false`
Flags	`show_on_agent_app`	boolean	Visibility in agent apps (in detailed response).	`true/false`
Timestamps	`created_at`	string (ISO8601)	When the item was created.	`"2024-09-20T06:06:30.215Z"`
Timestamps	`updated_at`	string (ISO8601)	Last modification time (in detailed response).	`"2024-09-12T20:31:41.030Z"`
Timestamps	`delete_at`	string (ISO8601) \| null	Deletion timestamp (usually `null`).	`null`

Common Use Cases

1. Payment Selection Interface

Fetch all payment items, filter by active status and category, display with names and amounts for customer selection.

2. Dynamic Form Generation

Retrieve payment item details, parse form_data array, dynamically generate input fields with validation based on configuration.

3. Amount Verification

Before transaction initialization, fetch payment item details to verify amount matches for fixed-amount items or validate range for variable items.

4. Revenue Split Verification

Check transaction_split_code to understand default fund distribution before initializing transaction or to display settlement information.

Filter payment items by category_details and sub_category_details to create organized navigation structure (Government > Federal > specific items).

Overview​

1. Get Payment Items​

Code Snippets​

Sample cURL Request​

Success Response (200 OK)​

Failure Response (403 Forbidden)​

2. Get Payment Item Details​

Code Snippets​

Sample cURL Request​

Success Response (200 OK)​

Key Fields in Payment Item Objects​

Common Use Cases​

1. Payment Selection Interface​

2. Dynamic Form Generation​

3. Amount Verification​

4. Revenue Split Verification​

5. Category-Based Navigation​

Overview

1. Get Payment Items

Code Snippets

Sample cURL Request

Success Response (200 OK)

Failure Response (403 Forbidden)

2. Get Payment Item Details

Code Snippets

Sample cURL Request

Success Response (200 OK)

Key Fields in Payment Item Objects

Common Use Cases

1. Payment Selection Interface

2. Dynamic Form Generation

3. Amount Verification

4. Revenue Split Verification

5. Category-Based Navigation