MeldCX Agent Payments API

Terminology

Configuration

The payment API supports configuring the various properties of the API Engine, Gateway and Terminal using the following configuration mechanisms:

• Application manifest, manifest.json file stored in the root of your application folder (alongside index.html)
• Account Preferences
• Device Options
• Display Options
• Explicit configuration via Agent.Payments.setConfiguration, Agent.Payments.setGatewayConfiguration and Agent.Payments.setTerminalConfiguration

The available configuration properties are as follows

There are additional values for each Terminal and Gateway see the Payment Terminals section for the various Terminal configuration options and the Payment Gateways section for the various Gateway configuration options.

Payment Terminals

Some terminals require configuration to setup the devices for Styling, Behavioural restrictions and other configuration.

Available Terminals

The currently terminals supported by MeldCX are:

Configuration

Configuration of the terminals can be done using any of the configuration mechanisms listed in Configuration, the configuration is structured as follows:

Pairing Payment Terminal/Pin Pad

It is necessary to ensure that the terminal we are communicating with is authorised in order to do this we use the process of pairing to validate the terminal.

If the Payments Engine has not paired with a device it will be in the TerminalPairingFailed state which can be validated using the Agent.Payments.status() function.

Pairing Mode

The following pairing modes are supported:

• Silent - Doesn't require any user interaction to pair with the terminal
• Interactive - Requires user interaction to pair the terminal

Pairing Strategy

The supported pairing strategies are as follows:

Pairing Mode - Interactive

The following Interactive pairing strategies are available:

Note: These are available only if using the Interactive Pairing Mode.

Interactive Pairing Stragegy - Code On Screen

Using the Agent.Payments.pairInteractiveCommence() function to invoke the device to go into pairing mode and show a pairing code on screen.

Call the Agent.Payments.pairInteractiveComplete() function and provide the pairingCode as the property on the object provided to the function for example.

await Agent.Payments.pairInteractiveCommence();

// Pairing Code will be displayed on terminal screen

const result = await Agent.Payments.pairInteractiveComplete({pairingCode: 123456});

if (result) console.log('Pairing Succeeded');
else console.log('Pairing Failed');

// Validate that the pairing succeeded and that the Payments Engine is ready to take payments

const status = await Agent.Payments.status();

if (status.message === 'Ready') console.log('Payments Engine is ready!');
else console.log('Payments Engine is not ready');

The Agent will then store unique identification information about this pinpad and trust the device automatically from this point forward until Agent.Payments.unPair() is called.

Silent Pairing Strategies

The following Silent pairing strategies are available.

Serial Number Only

This strategy enables pairing based on matching the serial number only.

This can be configured in the device options as follows:

Encryption Key Only

This strategy enables pairing based on matching the Encyrption Key KSN and Type.

This can be configured in the device options as follows:

Serial Number and Encryption Key

This strategy enables pairing based on matching the serial number and the Encyrption Key KSN and Type.

This can be configured in the device options as follows:

Silent Pairing

Silent Pairing is run automatically or can be invoked using the Agent.Payments.pairSilent() function, this will resolve to true or false depending on if the pairing was a success.

Interactive Pairing

Interactive Pairing is invoked manually using the Agent.Payments.pairInteractiveCommence() function and providing any neccessary parameters, this will invoke the terminal to start the interactive pairing sequence. To complete the interactive pairing simply call Agent.Payments.pairInteractiveComplete() function and provide any neccessary parameters (see independant terminal section.)

IDTech VP6800 & VP8800

Mock Terminal

You can invoke failure modes by making a transaction with the total value in the charges set to the corresponding value in the table below.

Payment Gateways

The available payment gateways are:

• FreedomPay Freeway
• Mock Gateway

Mock Gateway

The mock gateway is intended to be used for debugging, testing and setting up your initial integration with this API.

Configuration

You can invoke failure modes by making a transaction with the total value in the charges set to the corresponding value in the table below.

You can configure other aspects of the mock gateway using configuration options, see below.

FreedomPay Freeway

Configuration

The following configuration options are available for the FreedomPay Freeway gateway:

The payment API supports a heirarchical system that applies the configuration in a cascading order of the following: manifest.json, Account Preferences, Device Options and Display Options.

The bulk of these options should be pre-configured as account preferences, however some values such as terminalId may be kiosk specific.

* This will be populated automatically by MeldCX (can be overridden) and will reference the MeldCX Unique device ID.

** This will be populated automatically by MeldCX (can be overridden).

You can invoke failure modes by making a transaction with the total value in the charges set to the corresponding value in the table below.

Errors

FreedomPay Freeway Errors will have the following format:

Minimum Configuration with ID Tech VP6800 & VP8800 Payment Terminals

The Minimum configuration required for the payments setup in development is as follows:

Minimum Configuration without Payment Terminal

Transaction Types

The available transaction types are as follows:

These Transaction types can be referenced using the Agent.Payments.TransactionType property or imported from the @meldcx/agent-payments NPM library as follows:

import {TransactionType} from '@meldcx/agent-payments';

Reference Information

All transactions require that you provide reference information for tracking the state and maintaing records of your transactions. The supported fields for the reference information object are as follows:

Some gateways require different information to be provide as the reference for the transaction, below is a list of reference information required by each gateway implemented by MeldCX

Charges

All transactions require that you provide a charges object containing all of the charges to be applied.

Performing Transactions

Performing a transaction is done using the Agent.Payments.startTransaction() function.

To peform a payment transaction you need to provide the following parameters:

• Transaction Type (See Transaction Types)
• Reference Information (See Reference Information)
• Charges (See Charges)
• Optional Configuration

Payment Transaction

Performing a Payment Transaction can be done like so:

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';
import moment from 'moment';

const agent = new Agent();
const transactionType = agent.Payments.TransactionType.Payment;
const reference = { invoiceNumber: 'ABC1234DEF', invoiceDate: (new Date()).toISOString() };
const charges = { total: 100, tax: 10 };

try {
    const result = await agent.Payments.startTransaction(transactionType, reference, charges, options);
    console.log('Transaction Was Approved', result);
} catch (ex) {
    if (ex instanceof TransactionRejectedException) {
        const {responseCode, code} = ex;

        console.log(`Transaction was rejected: ${code} with response code: ${responseCode}`);

        return;
    }

    console.log(`Some other error occurred: ${ex.code}`);
}

Performing a pre-auth Transaction can be done like so, additionally we have added line items for this pre-auth:

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';
import moment from 'moment';

const agent = new Agent();
const transactionType = agent.Payments.TransactionType.PreAuth;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 100, tax: 10 };

// NOTE: Items are not mandatory, they only need to be provided once for a given transaction reference. i.e. Provided with pre-auth but absent from capture.
const items = [
    {
        folioNumber: 7741234,
        expectedDuration: 2,
        noShow: false,
        checkinDate: moment().toISOString(),
        checkoutDate: moment().add(2, 'days').toISOString(),
        extraChargeType: 'M',
        roomRate: 50,
        roomTax: 5,
        extraChargeTotal: 0
    }
];
const options = { items };
try {
    const result = await agent.Payments.startTransaction(transactionType, reference, charges, options);
    console.log('Transaction Was Approved', result);
} catch (ex) {
    if (ex instanceof TransactionRejectedException) {
        const {responseCode, code} = ex;

        console.log(`Transaction was rejected: ${code} with response code: ${responseCode}`);

        return;
    }

    console.log(`Some other error occurred: ${ex.code}`);
}

Capturing a prior transaction

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';

const agent = new Agent();
let transactionType = agent.Payments.TransactionType.PreAuth;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 100, tax: 10 };

let result = await agent.Payments.startTransaction(transactionType, reference, charges);

reference.id = result.response.requestID;

transactionType = agent.Payments.TransactionType.Capture;

result = await agent.Payments.startTransaction(transactionType, reference, charges);

Making a Credit transaction:

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';

const agent = new Agent();
const transactionType = agent.Payments.TransactionType.Credit;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 100};

try {
    const result = await agent.Payments.startTransaction(transactionType, reference, charges);
    console.log('Transaction Was Approved', result);
} catch (ex) {
    if (ex instanceof TransactionRejectedException) {
        const {responseCode, code} = ex;

        console.log(`Transaction was rejected: ${code} with response code: ${responseCode}`);

        return;
    }

    console.log(`Some other error occurred: ${ex.code}`);
}

Cancel a Transaction:

Note: If the transaction doesn't cancel, you may still need to make a reversal/credit transaction.

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';

const agent = new Agent();
const transactionType = agent.Payments.TransactionType.Capture;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 100, tax: 10 };

try {
    setTimeout(() => agent.Payments.cancelTransaction(reference));
    const result = await agent.Payments.startTransaction(transactionType, reference, charges);
    console.log('Transaction Was Approved', result);
} catch (ex) {
    if (ex instanceof AgentCancelledException) {
        const {code} = ex;

        console.log(`Transaction was cancelled: ${code}`);

        return;
    }

    console.log(`Some other error occurred: ${ex.code}`);
}

Making a PreAuth and Token transaction:

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';

const agent = new Agent();
const transactionType = agent.Payments.TransactionType.PreAuth | agent.Payments.TransactionType.Token;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 50};

try {
    const result = await agent.Payments.startTransaction(transactionType, reference, charges);
    console.log('Transaction Was Approved', result);
    console.log('Token is:', result.response.token);
} catch (ex) {
    if (ex instanceof TransactionRejectedException) {
        const {responseCode, code} = ex;

        console.log(`Transaction was rejected: ${code} with response code: ${responseCode}`);

        return;
    }

    console.log(`Some other error occurred: ${ex.code}`);
}

Voiding a prior transaction:

import {PaymentException} from '@meldcx/agent-payments';
import Agent from '@meldcx/agent';

const agent = new Agent();
let transactionType = agent.Payments.TransactionType.PreAuth;
const reference = { invoiceNumber: 'DEF383832', invoiceDate: (new Date()).toISOString() };
const charges = { total: 50};

let result = await agent.Payments.startTransaction(transactionType, reference, charges);

reference.id = result.response.requestID;

transactionType = agent.Payments.TransactionType.Void;
result = await agent.Payments.startTransaction(transactionType, reference, charges);

Transaction Status

You can listen to transaction status updates by register an event listener using the function onTransactionStatus and example of this is below:

Agent.Payments.onTransactionStatus((reference, status) => {
    console.log(`Transaction with reference ${JSON.stringify(reference)} has status ${JSON.stringify(status)})`);
});

Transaction Result

The transaction result will have the following properites:

A full example response object is show below:

{
    "charges": {
        "total": 4
    },
    "cardInfo": {
        "maskedPAN": "541333******0011",
        "cardHolderName": "UAT USA/TEST CARD 10",
        "cardType": {
            "code": 1,
            "type": "Mastercard"
        },
        "cardExpiry": {
            "month": 12,
            "year": 2022
        },
        "entryMethod": {"code": 1, "type": "MSR"}
    },
    "reference": {
        "invoiceNumber": "e0f2619f-5f3c-4f83-8",
        "invoiceDate": "2019-12-23T04:35:04.636Z"
    },
    "transactionId": "99e4f3bb-e6f9-4ad4-9ca3-5398b0bd7b54",
    "approved": true,
    "response": {
        "token": "9680082379174111",
        "requestID": "01Z6HT2V0R01U67LG1LOM4POFBRGJ8OI",
        "receipt": "************* AUTHORIZATION *************\n APPROVED\n\nTotal: $4.00\n\nCard Type: MASTERCARD\nCard Entry: MAG STRIPE\nAcct #: 541333******0011\nApproval Code: 621575",
        "resultCode": 200,
        "authorizationCode": "621575",
        "authorizationDateTime": "2020-01-17T05:22:35.6164684Z"
    },
    "gatewayResponse": {}
}

Entry Methods

Errors

Common Errors

Emulator

A Payments emulation component has been developed for the Agent Emulator, this can be found in the Payments section of the Emulator Menu.

Emulating Payment System State

Under the section titled System there is a drop down list from which you can set the state of the Payments System, the following states correspond to these errors being throw by the system:

Emulating Gateway State

Under the section titled Gateway there are 2 drop down lists:

• The first allows you to set the state of the Gateway API.
• The second allows you to set the gateway action for the transactions it receives.

Gateway State and Errors:

Gateway Result/Actions:

Emulating Terminal State

The Status column shows the emulated display of the payment terminal and the prompts that the user would see.

The Input Method column contains a drop down list that allows you to select the emulated input method for the card, this may be MSR, Chip and EMV.

The Swipe, Tap, Insert button allows you to invoke the Swipe, Tap or Insert action. This buttons action changes based on the Input Method you select.

The CV Trigger Limit designates the amount the charge to the card can be before it triggers a Card Holder Verification request, this only applies to transaction of type Tap & Insert (EMV Transactions).

Working with EMV

EMV mantains much stricter and safer controls over what transactions are supported and the conditions around verifying the cardholder before releasing the data stored on the card, if certain conditions are met the customer may be prompted to enter their PIN or to perform some other kind of verification.

We have added support to emulate this behaviour in our Emulator. When the transaction amount is greater than or equal to that specified in the CV Trigger Limit drop down list, the emulator will trigger the "CVM Required" event, you can listen to this as follows:

Agent.Payments.onCVMRequested((cvMethod: CVMethod, reference: TransactionReference) => {
    console.log(`The transaction with reference: ${reference.invoiceNumber} is requesting to perform Cardholder Verification via ${CVMMethod.type}`);

    // At this time the emulator only returns a Cardholder Verification method of type 'ONLINE_PIN'.
}));

Additionally you can emulate a successful Cardholder Verification by clicking on the CV Verify button which will temporarily replace the Insert/Tap button.

The transaction result will reflect the differing presentation methods with the result.cardInfo.entryMethod objects values differing depending on the Entry method

Terminal Errors

We have added support for emulating a wide variety of payment terminal errors:

Connectivity Errors

The Connectivity column contains a drop down that allows you to switch the connectivity state of the payment terminal.

Driver & Terminal Errors

Status Errors

Transaction Errors

EMV Errors

The EMV Errors will be returned in the form of {CEMV_APP_ERROR_FN}.{CEMV_APP_ERROR_STATE}