---
sidebar_position: 2
---

# 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

```javascript
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:

```javascript
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:

```javascript
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 |