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. Payment Redirect Url (Webhook). We will send the user to this url when he/she starts a payment. You can then redirect the user the the right payment page or let them choose a payment method to use and then redirect them to the payment page.
  5. 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'
}

If you also want to store additional meta data, like an IP address / port, this is possible with device meta.

Pin terminal listing

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

Payment flow​

We have set-up a default payment flow, our POS will monitor these events and change our interface based on the status changes.

1. Payment request webhook​

When someone clicks the start payment button, we will send you an payment request webhook. Along with this we will send over the payment request parameters. With this information you can start the pin transaction of the terminal.

The result of this request we will show in our interface, the same way we'll load a widget into our system.

2. Maintain the request status​

For the pin terminal status we work with 4 different values. You can change these values by doing a meta data update on the device. Like this:

curl --location --request PUT 'https://api.camping.care/v21/devices/{device_id}/meta?key=request_status&value=pending'

pending​

If the pin terminal is in idle (doing nothing) state the request_status should be pending.

started​

To inform our platform that the payment has been started, please update the device status request_status to started.

error​

If any error occurs, change the request_status to error. If you have an error message add this text in this meta field: error_message

curl --location --request PUT 'https://api.camping.care/v21/devices/{device_id}/meta?key=error_message&value=message text from the error'

We will display the error and the user will get the possibility to start the transaction again. Then the process will repeat itself.

success​

If the transaction was successfull change the request_status to success. At this point, we will process the payment and add it to the system.

If you want to store additional payment information, add a json with this data in this meta field: transaction_information

curl --location --request PUT 'https://api.camping.care/v21/devices/{device_id}/meta?key=transaction_information&value={ JSON WITH DATA}'

Additional parameters​

network_status meta field can be used to indicate if the device is online or offline. optional.

transaction_provider_id meta field (Optional), this is the ID of the payment provider. If you are not listed as a provider we are able to provide you with a new provider_id. Default is 1 (Other). payment Providers API

transaction_method_id meta field (Optional), this is the ID of the payment method (Creditcard or Apple PAy etc.). By default this is 4 (Pin). payment Methods API

transaction_id the unique reference from the payment provider. (Optional)

transaction_url a link to the transaction on the website of the provider. (Optional)

transaction_information Additional payment information (array or object) to be stored in the payment. (Optional)