Capacitor Pax Payment

A plugin for initiating and managing payments via PAX FRv6 terminals, and printing custom tickets through Neptune printer APIs, with clear transaction and print result handling for seamless app-to-app integration.

Note: This plugin is designed to work exclusively with PAX FRv6 terminals. It will not function with other terminal models.

Prerequisites

• Device: PAX Technology Android device (FRv6 terminal)
• Android: Minimum Android API level 24 (Android 7.0)
• PAX Payment App: Required for initiateTransaction.
• Neptune Lite Printer Runtime: Required for printCustomTicket (Neptune jar + native libs in the plugin).

Android Host App Requirement (Neptune Native Libs)

If you use printCustomTicket and hit an error like couldn't find "libDeviceConfig.so", configure your host app (android/app/build.gradle) like this:

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging true
    }
  }
}

Install

yarn add capacitor-pax-payment
yarn cap sync

Payment Example

import { PaxPayment, TransactionType } from 'capacitor-pax-payment';

const initiatePayment = async () => {
  try {
    const result = await PaxPayment.initiateTransaction({
      amount: '100', // 1.00 € in smallest currency unit
      currency: '978', // ISO 4217 currency code for Euro
      beneficiary: 'John Doe',
      transactionType: TransactionType.DEBIT,
    });

    if (result.status === 'success') {
      console.log('Transaction successful:', result.transactionNumber);
      console.log('Message:', result.successMessage);
    } else {
      console.error('Transaction failed:', result.errorCode, result.errorMessage);
    }
  } catch (error) {
    console.error('Failed to initiate payment:', error);
  }
};

Print Ticket Example

import { PaxPayment, PrintAlign } from 'capacitor-pax-payment';

const printTicket = async () => {
  try {
    const result = await PaxPayment.printCustomTicket({
      lines: [
        { text: 'OAK & MAPLE GROCERIES', align: PrintAlign.CENTER, doubleHeight: true, doubleWidth: true },
        { text: '------------------------------' },
        { text: 'Apples x2', align: PrintAlign.LEFT },
        { text: 'TOTAL: 12.50 EUR', align: PrintAlign.RIGHT, doubleHeight: true },
        { text: 'Thank you, see you soon!', align: PrintAlign.CENTER },
      ],
      charset: 'UTF-8',
      feedLines: 3,
    });

    if (result.status === 'success') {
      console.log('Print successful:', result.printerStatusCode, result.printerStatusMessage);
    } else {
      console.error('Print failed:', result.printerStatusCode, result.errorMessage);
    }
  } catch (error) {
    console.error('Failed to print ticket:', error);
  }
};

Note: printCustomTicket uses Neptune Lite printer APIs available on PAX devices.
If Neptune classes are unavailable at runtime, the method rejects with a printer API error.

Payment Status Codes

The plugin returns specific error codes from the PAX payment system. Here's a reference:

| Code | Description | |------|-------------| | 00 | Transaction successful | | 01 | Transaction was refused | | 02 | Transaction was aborted | | 03 | An error occurred | | 04 | Invalid request | | 08 | Transaction type not authorized | | 09 | Original transaction not found | | ActivityResultNotOK | Transaction was canceled by the user or failed at the activity level |

Note: The error code 00 indicates success. All other codes indicate various failure scenarios.

Print Status Codes

The printCustomTicket method returns printerStatusCode from Neptune start().

| Code | Description | |------|-------------| | 0 | Success | | 1 | Printer is busy | | 2 | Out of paper | | 3 | Print data format error | | 4 | Printer malfunction | | 8 | Printer overheated | | 9 | Printer voltage too low | | -2 | Data package is too long | | -4 | Printer font library not installed | | -5 | Cover open error | | -6 | Cutter jam error | | -16 | Printing unfinished |

Printing Recommendations

• Keep each line reasonably short to reduce wrapping on narrow printer widths.
• Keep overall ticket size moderate to avoid printer buffer limits.

API

• initiateTransaction(...)
• printCustomTicket(...)
• Interfaces
• Enums

initiateTransaction(...)

initiateTransaction(options: TransactionOptions) => any

Initiates a payment transaction with the PAX system.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | ------------------------------------ | | options | TransactionOptions | Transaction options for the payment. |

Returns: any

printCustomTicket(...)

printCustomTicket(options: PrintTicketOptions) => any

Prints a custom ticket using the PAX built-in printer (Neptune Lite).

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | ----------------------------------------- | | options | PrintTicketOptions | Custom ticket content and print settings. |

Returns: any

Interfaces

TransactionOptions

Represents the options for a transaction.

| Prop | Type | Description | | --------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | amount | string | The amount for the transaction, in the smallest currency unit (e.g., 1.25 € = "125"). Must be a string containing only positive digits | | currency | string | The ISO 4217 currency code (e.g., "978" for Euro, "840" for US Dollar...). This should be a 3-digit currency code. | | beneficiary | string | The beneficiary name (optional). | | transactionType | TransactionType | The transaction type (optional). |

TransactionResult

Represents the result of a transaction.

| Prop | Type | Description | | ----------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | status | 'success' | 'failure' | The status of the transaction. - 'success' indicates the transaction was successful. - 'failure' indicates the transaction failed. | | successMessage | string | A message describing the success of the transaction. Present only if the transaction succeeds. | | transactionNumber | string | The transaction number for identifying the transaction. Optional, only present if the transaction succeeds. | | errorCode | string | The error code returned in case of failure. Optional, only present if the transaction fails. | | errorMessage | string | A detailed error message, if available. Optional, only present if the transaction fails. |

PrintTicketOptions

Represents a custom ticket print request.

| Prop | Type | Description | Default | | --------------- | ------------------- | -------------------------------------- | -------------------- | | lines | {} | Ticket lines to print, in order. | | | charset | string | Character set used to print text. | 'UTF-8' | | feedLines | number | Extra blank lines appended at the end. | 3 |

TicketLine

Represents one printable line in a custom ticket.

| Prop | Type | Description | Default | | ------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------- | | text | string | The text to print. If empty, the line is skipped. | | | align | PrintAlign | Text alignment. | 'left' | | doubleWidth | boolean | Enables double-width for this line. | false | | doubleHeight | boolean | Enables double-height for this line. | false | | invert | boolean | Enables inverted printing for this line. | false |

PrintTicketResult

Represents the result of a ticket print.

| Prop | Type | Description | | -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | | status | 'success' | 'failure' | Print status. | | printerStatusCode | number | Printer return code from Neptune start(). Present on both success and failure. | | printerStatusMessage | string | Human-readable status description. | | errorMessage | string | Detailed error message when status is failure. |

Enums

TransactionType

| Members | Value | Description | | ----------- | -------------------- | ---------------------------------------------------------- | | DEBIT | 'DEBIT' | A debit transaction. This is the default transaction type. |

PrintAlign

| Members | Value | Description | | ------------ | --------------------- | -------------------- | | LEFT | 'left' | Left-aligned text. | | CENTER | 'center' | Center-aligned text. | | RIGHT | 'right' | Right-aligned text. |