Skip to main content

Add a pin terminal

In this tutorial we'll describe how you are able to add an PIN Terminal to our POS (Point Of Sale).

Pre-requirements​

For this tutorial it's good to have an understanding how our App Store works. If not, you can read the documentation here or follow our toturial for Laravel or Vue JS.

Create an app​

Go to the Appstore and create an app. These are the requirements:

  1. Your app need an webhook with the event patment.request
  2. The category needs to be payment_provider
  3. It needs a logo and a description
  4. You need all the scopes for the devices API.

Setup a device​

We can use the devices API to setup an new pin terminal device. This can be found here: devices API

Add a new device with the following required parameters.

{
    name: 'Terminal Reception',
    type: 'pin_terminal'
}

Once you have added the device with the type pin_terminal, it will also be listed in the terminal list in the POS application.

Pin terminal listing

You need to add some meta keys, like the payment_endpoint or cancellation_endpoint this is possible with device meta. 

{
    key: "payment_endpoint",
    value: "https://your-app-url.com/payment-request"
}
{
    key: "payment_timeout", // (Optional)
    value: 120
}
{
    key: "cancellation_request", // (Optional)
    value: "https://your-app-url.com/cancellation-request"
}

Payment flow​

We have set-up a default payment flow. Once the payment is initiated in from our software, we create a new payment. This payment has the status pending and has a lifetime of 3 minutes.

1. Payment request (POST)​

When the user initiates the payment, we will send the following request to the payment_endpoint you have defined in your device.

{
    id: 123456,
    payment_uid: "pay_dfngjdnfg........."
}

Retrieve data​

With the get payment endpoint. You can retreive all the data from this payment. Like the currency and amount.

Success​

1. Update payment status

Update payment status to locked or open. When the payment is open the user can manual delete it. When it's locked, the user is unable to delete the payment. (Locked is adviced)

2. Return the success

When the payment was a success, return the following json message.

{
    result: "success"
}

Error​

When anything went wrong, send the following json message back amd describe your error message. 

{
    error:
    {
        message: "Clearify what is going wrong in an error message."
    }
}

Timeout​

The default timeout is 120 seconds. But you can change this by changing the timeout parameters in your device. The maximum timeout you can set is 300 seconds.

Automatic cancellation​

When, for whatever reason the payment is still pending after 300 seconds. We will delete the payment automaticly. The pending status will change in deleted.

2. Cancellation request (POST)​

This request is optional. If you don't support the cancellation feature. You can leaf the cancellation_request endpoint en the device meta empty. 

{
    id: 123456,
    payment_uid: "pay_dfngjdnfg........."
}

Success​

When the payment was a success, return the following json message.

{
    result: "success",
}

Error​

When anything went wrong, send the following json message back amd describe your error message. 

{
    error:
    {
        message: "Clearify what is going wrong in an error message."
    }
}