Payment service

The payment service provides an implementation for kiosk card terminal payments. When registered, the platform will use your plugin to process card payments.

Registration

export default async context => {
    context.service.addService({
        type: 'paymentService',
        paymentType: 'terminal',
        startPayment: async params => {
            // params contains: paymentSessionId, orderId, amount, currencyIsoCode, uiCultureCode
            // ... handle the payment
            return { status: 'ReservationStarted', requestData: params };
        },
    });
};

Request parameters

The startPayment method receives an object with the following properties:

Property	Type	Description
paymentSessionId	string	Identifier for the payment session
orderId	string	The order being paid for
amount	number	The total amount to charge in the smallest currency unit (e.g. 100 for $1.00)
currencyIsoCode	string	Currency code (e.g. "SEK", "NOK")
uiCultureCode	string	Culture code for localization (e.g. "en-GB")

Responses

Success

Return a ReservationStarted response when payment has been initiated successfully:

return {
    status: 'ReservationStarted',
    requestData: {
        paymentSessionId: params.paymentSessionId,
        orderId: params.orderId,
        amount: params.amount,
        currencyIsoCode: params.currencyIsoCode,
        uiCultureCode: params.uiCultureCode,
    },
};

Error

Return an Error response when payment fails:

return {
    status: 'Error',
    error: {
        code: 'kiosk.payment.error.amountdeclined',
        message: 'A human-readable error message',
    },
};

Payment flow after startPayment

After startPayment returns a ReservationStarted response, the UI transitions to a "user action" screen (e.g. an insert card prompt). The UI remains on this screen until one of the following events is received:

Event	Source	Outcome
PaymentSessionAborted	Ordering	The payment session was aborted. The UI displays an error and the customer can retry.
PaymentReservationCompleted	Payment	The payment reservation completed successfully. The UI proceeds to the next step.
PaymentReservationFailed	Payment	The payment reservation failed. The UI displays an error and the customer can retry.

Error codes

Code	Description
kiosk.payment.error.cancelledbycustomer	The customer cancelled the payment
kiosk.payment.error.amountdeclined	The amount was declined
kiosk.payment.error.declined	The card was blocked or declined
kiosk.payment.error.terminalissues	Terminal hardware or connection issues
kiosk.payment.error.uncategorized	An uncategorized error
kiosk.payment.error.invalidpin	Invalid PIN entered
kiosk.payment.error.cardnotallowed	Card type not accepted
kiosk.payment.error.invalidcard	Invalid or unreadable card