Payments

Introduction

The POSaBIT Connect provides a seamless mechanism to integrate a variety of payment options directly into your POS (Point-Of-Sale) system. Using our API will enable your existing platforms to communicate with payment terminals and other payment networks.

Setup Requirements

Active POSaBIT merchant account
POSaBIT payment terminal
Onsite Internet connectivity

Credentials

Each venue requires its own unique Client ID and Client Secret to utilize the POSaBIT API, found at the payment portal under Settings. Your project implementation should store these credentials for each venue in a secure manner.

APIKeys Note: If you do not see the API Credentials tab in the settings page please contact your account manager to enable this feature.

For operations involving a payment terminal transaction Sale the Terminal ID parameter must specify the target terminal where the transaction begins. Each payment station will need its own Terminal ID. from the payment portal (see below) or by selecting a terminal from the list provided in the Account call. Visit the portal Terminals page to see the setup terminals.

Terminals

Authentication

Payment services are accessed using a session token that is required to be included in the headers of your HTTP requests. To receive a session token first call the Authenticate API using your credentials provided. Upon successful authentication a token will be generated and will be valid for the duration of the session.

Base URL:

Staging Env	Production Env
https://staging.posabittest.com/v3	https://my.posabit.com/v3

API Key (ApiToken)
- Parameter Name: X-POSaBit-Token, in: header. Authentication token

Transactions

Overview

Flow

Sale Example

To complete a sale you must first gain access to a POSaBIT API token. This token enables you to access POSaBIT web services. These tokens expire in one hour, therefore, you will need to refresh with a new token for each session. The following examples show these operations using curl commands.

Auth Request:


curl -X POST https://api.posabit.com/v3/auth \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"client_id": "1525430608","client_secret": "..."}'

Note: This is an example but to get an actual response, replace the values for the client_id and client_secret with your given credentials.

Once successfully authenticated the API will return a AuthResponse message. This will contain your token, expiration of time of the token and the scope of operations granted.

Auth Response:


{
  "token": "E3FD1D8B-E0DA-4CC4-9D72-7399F24E548B",
  "expiration": "1610525430608",
  "scope": "sale"
}

Now we can begin to build a sale request and send it to the API. The example request below shows the minimal SaleRequest parameters for initiating a debit transaction. Notice the token from the previous request is included in the headers to provide authorized access. You must set the network wait time (timeout) to 5 minutes to allow time for the consumer to complete the interactive screens. This will start the sale on the payment terminal.

Sale Request:


curl -X POST https://api.posabit.com/v3/sale --max-time 300 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-POSaBit-Token: E3FD1D8B-E0DA-4CC4-9D72-7399F24E548B' \
  -d '{"payment_type": "debit", "amount": 100.0, \
   "terminal_id": "c8471535-f6c6-4944-8790-f45792d99446", \
   "reference_id": "T0123456789"}'

Once a sale has been successfully completed a SaleResponse message will be returned containing information for concluding the payment portion of a POS transaction.

Sale Response:


{
  "status": "complete",
  "payment_type": "debit",
  "total_amount": 110.0,
  "sale_amount": 100.0,
  "tip": 10.0,
  "change": 0,
  "fee": 1.0,
  "datetime": "2021-07-28 15:49:22 -0700",
  "reference_id": "T0123456789",
  "auth_code": "263891",
  "confirmation_code": "DAF4-F9435133",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "terminal_id": "c8471535-f6c6-4944-8790-f45792d99446"
  
}

Testing

During the integration phase of your system with POSaBIT payments the staging environment provides mock responses to test the various transactions states. You can receive a mock response for testing these states by sending a special mock terminal_id value in the Sale request to illicit mock responses.

Mock Terminal Id	Mock Response
`TERMINAL_SUCCESS`	Returns a successful SaleResponse
`TERMINAL_BUSY`	Returns an ErrorResponse with error code P129
`TERMINAL_ERROR`	Returns an ErrorResponse with error code P130

To test a successful sale response pass the value TERMINAL_SUCCESS in the terminal_id parameter field as shown in the example below.

Sale Request:


{
  "payment_type": "debit",
  "amount": 100.0,
  "terminal_id": "TERMINAL_SUCCESS",
  "reference_id": "TestTransRef1",
}

Status

Status	Description
invalid	The transaction request failed initial validation
pending	The transaction request was received and is currently pending user input
timeout	Terminal took too long to respond back
cancelled	Transaction was cancelled
error	A transaction failure occurred
busy	Target terminal is busy with another transaction request
complete	Transaction was successfully completed

Errors

POSaBit Code	Description
P101	Unsupported payment type.
P102	Invalid authorization amount.
P103	Missing or invalid consumer ID document.
P104	Payment network unavailable.
P105	Invalid tip parameter.
P106	Transaction declined.
P107	Transaction declined. Contact issuing financial instituation.
P108	Account is not enabled.
P109	Invalid payment PIN.
P110	Transaction limit reached.
P111	Invalid credentials
P112	Invalid terminal
P113	Operation timeout
P114	Transaction pending
P122	Invalid tip amount
P123	Invalid payment type
P124	Payment type not enabled for account
P125	Duplicate transaction reference_id
P126	Missing transaction reference_id
P128	Transaction cancelled
P129	Terminal busy
P130	Terminal response error
P134	Missing or invalid consumer name
P135	Missing or invalid consumer ID number
P136	Missing or invalid consumer ID type
P137	Missing or invalid consumer ID expiration
P138	Missing or invalid consumer ID date of birth
P140	Transaction not found
P141	Unable to cancel transaction
P142	Unsupported terminal type
P144	Terminal offline

The POSaBit API uses the following HTTP error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified endpoint or transaction could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API

Authenticate

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://api.posabit.com/v3/auth',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://api.posabit.com/v3/auth', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.posabit.com/v3/auth", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.posabit.com/v3/auth";

      string json = @"{
  ""client_id"": ""1525430608"",
  ""client_secret"": ""EUE1kJUm1BPkvX7ieizcrz""
}";
      AuthRequest content = JsonConvert.DeserializeObject(json);
      await PostAsync(content, url);


    }

    /// Performs a POST Request
    public async Task PostAsync(AuthRequest content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(AuthRequest content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X POST https://api.posabit.com/v3/auth \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /auth

Initiate session authentication using your client_id and client_secret to receive a session token.

Body parameter

{
  "client_id": "1525430608",
  "client_secret": "EUE1kJUm1BPkvX7ieizcrz"
}

Parameters

Name	In	Type	Required	Description
body	body	AuthRequest	true	none

Example responses

Successful authentication

{
  "token": "E3FD1D8B-E0DA-4CC4-9D72-7399F24E548B",
  "expiration": "1610525430608",
  "scope": "sale"
}

Unauthorized

{
  "status": "invalid",
  "code": "P111",
  "message": "Invalid credentials"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful authentication	AuthResponse
401	Unauthorized	Unauthorized	ErrorResponse

Sale

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://api.posabit.com/v3/sale',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://api.posabit.com/v3/sale', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.posabit.com/v3/sale", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.posabit.com/v3/sale";

      string json = @"{
  ""payment_type"": ""debit"",
  ""amount"": 125.8,
  ""employee"": {
    ""id"": ""bcbf708c90fc"",
    ""first_name"": ""Marry"",
    ""last_name"": ""Jane""
  },
  ""terminal_id"": ""c8471535-f6c6-4944-8790-f45792d99446"",
  ""reference_id"": ""T0123456789"",
  ""id_document"": {
    ""name"": ""Shaggy Rogers"",
    ""type"": ""drivers"",
    ""doc_id"": ""D08954797"",
    ""doc_exp"": ""2024/12/02"",
    ""dob"": ""1970/12/02"",
    ""state"": ""WA"",
    ""country"": ""USA""
  },
  ""tip"": ""20%""
}";
      SaleRequest content = JsonConvert.DeserializeObject(json);
      await PostAsync(content, url);


    }

    /// Performs a POST Request
    public async Task PostAsync(SaleRequest content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(SaleRequest content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X POST https://api.posabit.com/v3/sale \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /sale

Initiate a consumer payment transaction. Once the sales total has been calculated and the payment method has been selected you may then initiate a Sale request. The server upon receiving a request it will activate the payment terminal to begin and instruct the consumer to provide their payment details. The request's network connection will remain open during the consumer interaction portion and will return a responce once the operation has concluded. Upon success you will receive SaleResponse containing the transaction details. If an error occurred you will receive ErrorResponse containing a code and a error description. If the network operation is interrupted at any point you can simply initiate the sale request again using the same reference_id parameter to continue the operation or realized completion. Certain payment types may require you to provide an IDDocument or enable display_id_scan to identify the end consumer for preventative risk measures.

Please Note: Set your network timeout parameter to 300 seconds to allow time for the consumer to complete the interactive screens.

Body parameter

{
  "payment_type": "debit",
  "amount": 125.8,
  "employee": {
    "id": "bcbf708c90fc",
    "first_name": "Marry",
    "last_name": "Jane"
  },
  "terminal_id": "c8471535-f6c6-4944-8790-f45792d99446",
  "reference_id": "T0123456789",
  "id_document": {
    "name": "Shaggy Rogers",
    "type": "drivers",
    "doc_id": "D08954797",
    "doc_exp": "2024/12/02",
    "dob": "1970/12/02",
    "state": "WA",
    "country": "USA"
  },
  "tip": "20%"
}

Parameters

Name	In	Type	Required	Description
body	body	SaleRequest	true	Sale request body.

Example responses

Successful operation

{
  "status": "complete",
  "payment_type": "debit",
  "total_amount": 176.12,
  "sale_amount": 163.54,
  "tip": 12.58,
  "change": 0,
  "fee": 1.5,
  "datetime": "2021-07-28 15:49:22 -0700",
  "reference_id": "T0123456789",
  "auth_code": "263891",
  "confirmation_code": "DAF4-F9435133",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "terminal_id": "001740F0-6613-4E4A-99DD-C623F707F75A"
}

Invalid parameters in request

{
  "status": "invalid",
  "code": "P101",
  "message": "Unsupported payment type"
}

{
  "status": "invalid",
  "code": "P102",
  "message": "Invalid authorization amount"
}

{
  "status": "invalid",
  "code": "P104",
  "message": "Missing or invalid consumer ID document"
}

Unauthorized

{
  "status": "invalid",
  "code": "P111",
  "message": "Unauthorized access"
}

Server specific error

{
  "status": "error",
  "code": "P132",
  "error": "Payment network unavailable"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	SaleResponse
400	Bad Request	Invalid parameters in request	ErrorResponse
401	Unauthorized	Unauthorized	ErrorResponse
500	Internal Server Error	Server specific error	ErrorResponse

Account

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.posabit.com/v3/account',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.posabit.com/v3/account', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.posabit.com/v3/account", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.posabit.com/v3/account";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X GET https://api.posabit.com/v3/account \
  -H 'Accept: application/json'

GET /account

Retrieve accounts details. Provides information about the account such as supported payment types, configured terminals and tip options.

Example responses

Success

{
  "id": "",
  "name": "POSaBIT",
  "address": "123 ABC Ln",
  "city": "Kirkland",
  "state": "WA",
  "zip": "98053",
  "payment_types": [
    "debit",
    "credit"
  ],
  "terminals": [
    {
      "id": "T12345",
      "name": "Terminal 1",
      "tipping": true,
      "id_scan": true
    }
  ],
  "tips": {
    "mode": "fixed",
    "value1": "5.00",
    "value2": "10.00",
    "value3": "15.00"
  }
}

{
  "id": "",
  "name": "POSaBIT",
  "address": "123 ABC Ln",
  "city": "Kirkland",
  "state": "WA",
  "zip": "98053",
  "payment_types": [
    "debit",
    "pob"
  ],
  "terminals": [
    {
      "id": "T12345",
      "name": "Terminal 1",
      "tipping": true,
      "id_scan": true
    }
  ],
  "tips": {
    "mode": "percent",
    "value1": "5%",
    "value2": "10%",
    "value3": "15%"
  }
}

Unauthorized

{
  "status": "invalid",
  "code": "P111",
  "message": "Invalid credentials"
}

Responses

Status	Meaning	Description	Schema
200	OK	Success	AccountResponse
401	Unauthorized	Unauthorized	ErrorResponse

Transaction

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.posabit.com/v3/transaction/{reference_id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.posabit.com/v3/transaction/{reference_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.posabit.com/v3/transaction/{reference_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.posabit.com/v3/transaction/{reference_id}";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X GET https://api.posabit.com/v3/transaction/{reference_id} \
  -H 'Accept: application/json'

GET /transaction/{reference_id}

Retreive transaction information and status.

Parameters

Name	In	Type	Required	Description
reference_id	path	string	true	Reference Id

Example responses

Transaction status

{
  "status": "complete",
  "payment_type": "debit",
  "total_amount": 176.12,
  "sale_amount": 163.54,
  "tip": 12.58,
  "change": 0,
  "fee": 1.5,
  "datetime": "2021-07-28 15:49:22 -0700",
  "reference_id": "T0123456789",
  "auth_code": "263891",
  "confirmation_code": "DAF4-F9435133",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "terminal_id": "001740F0-6613-4E4A-99DD-C623F707F75A"
}

{
  "status": "complete",
  "payment_type": "debit",
  "total_amount": 176.12,
  "sale_amount": 163.54,
  "tip": 12.58,
  "change": 0,
  "fee": 1.5,
  "datetime": "2021-07-28 15:49:22 -0700",
  "reference_id": "T0123456789",
  "auth_code": "263891",
  "confirmation_code": "DAF4-F9435133",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "terminal_id": "001740F0-6613-4E4A-99DD-C623F707F75A",
  "refunds": [
    {
      "transaction_id": "901840F0-6613-6E4F-19DE-C623F707A550",
      "refund_reference_id": "R0123456789",
      "datetime": "2021-07-29 12:05:32 -0700",
      "auth_code": "928374",
      "amount": "24.50",
      "status": "complete"
    }
  ]
}

{
  "status": "timeout",
  "code": "P113",
  "message": "Operation timed out"
}

Unauthorizated

{
  "status": "invalid",
  "code": "P111",
  "message": "Unauthorized access"
}

Responses

Status	Meaning	Description	Schema
200	OK	Transaction status	SaleResponse
401	Unauthorized	Unauthorizated	ErrorResponse

Cancel Transaction

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.posabit.com/v3/transaction/{reference_id}/cancel',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.posabit.com/v3/transaction/{reference_id}/cancel', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.posabit.com/v3/transaction/{reference_id}/cancel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.posabit.com/v3/transaction/{reference_id}/cancel";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X GET https://api.posabit.com/v3/transaction/{reference_id}/cancel \
  -H 'Accept: application/json'

GET /transaction/{reference_id}/cancel

Cancel an active transaction session by Reference Id

Parameters

Name	In	Type	Required	Description
reference_id	path	string	true	Reference Id

Example responses

Cancel success

{
  "status": "cancelled",
  "code": "P128",
  "message": "Transaction cancelled"
}

Terminal is busy and can't be cancelled

{
  "status": "busy",
  "code": "P129",
  "message": "Terminal busy"
}

Responses

Status	Meaning	Description	Schema
200	OK	Cancel success	ErrorResponse
400	Bad Request	Terminal is busy and can't be cancelled	ErrorResponse

Refund Transaction

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'https://api.posabit.com/v3/transaction/{reference_id}/refund',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('https://api.posabit.com/v3/transaction/{reference_id}/refund', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.posabit.com/v3/transaction/{reference_id}/refund", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.posabit.com/v3/transaction/{reference_id}/refund";

      string json = @"{
  ""refund_reference_id"": ""R0123456789""
}";
      RefundRequest content = JsonConvert.DeserializeObject(json);
      await PostAsync(content, url);


    }

    /// Performs a POST Request
    public async Task PostAsync(RefundRequest content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(RefundRequest content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X POST https://api.posabit.com/v3/transaction/{reference_id}/refund \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /transaction/{reference_id}/refund

Refund an existing transaction session by Reference Id. If partial amount is ommited than transaction is assumed to be a full refund.

Body parameter

{
  "refund_reference_id": "R0123456789"
}

Parameters

Name	In	Type	Required	Description
body	body	RefundRequest	false	Refund request
reference_id	path	string	true	Reference Id

Example responses

Refund success

{
  "amount": 24.5,
  "auth_code": "263891",
  "datetime": "2021-07-28 15:49:22 -0700",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "refund_reference_id": "R01234565",
  "status": "complete"
}

Invalid transaction

{
  "status": "invalid",
  "code": "P140",
  "message": "Transaction not found"
}

Responses

Status	Meaning	Description	Schema
200	OK	Refund success	RefundResponse
400	Bad Request	Invalid transaction	ErrorResponse

Terminal

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.posabit.com/v3/terminal/{terminal_id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.posabit.com/v3/terminal/{terminal_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.posabit.com/v3/terminal/{terminal_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.posabit.com/v3/terminal/{terminal_id}";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

# You can also use wget
curl -X GET https://api.posabit.com/v3/terminal/{terminal_id} \
  -H 'Accept: application/json'

GET /terminal/{terminal_id}

Terminal status and controls. Query if a particular terminal is online before initiating a sale request.

Parameters

Name	In	Type	Required	Description
terminal_id	path	string	true	Terminal Id

Example responses

Terminal Status response

{
  "status": "online"
}

{
  "status": "offline"
}

Unauthorized

{
  "status": "invalid",
  "code": "P111",
  "message": "Unauthorized access"
}

Responses

Status	Meaning	Description	Schema
200	OK	Terminal Status response	TerminalStatusResponse
401	Unauthorized	Unauthorized	ErrorResponse

Schemas

Employee

{
  "id": "E0000001234",
  "first_name": "Joe",
  "last_name": "Billings"
}

Employee description

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique employee id
first_name	string	true	none	Employee first name
last_name	string	true	none	Employee last name

IDDocument

{
  "name": "Shaggy Rogers",
  "type": "drivers",
  "doc_id": "D08954797",
  "doc_exp": "2024/12/02",
  "dob": "1970/12/02",
  "state": "WA",
  "country": "USA"
}

Consumer ID Document

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Type of document (drivers, passport, military)
doc_id	string	true	none	Document number
doc_exp	string	true	none	Expiration of document
dob	string	true	none	Date of birth
state	string	false	none	State issued document
country	string	false	none	Document country
name	string	true	none	Name provided by ID document

SaleRequest

{
  "payment_type": "debit",
  "amount": 125.8,
  "employee": {
    "id": "bcbf708c90fc",
    "first_name": "Marry",
    "last_name": "Jane"
  },
  "terminal_id": "c8471535-f6c6-4944-8790-f45792d99446",
  "reference_id": "T0123456789",
  "id_document": {
    "name": "Shaggy Rogers",
    "type": "drivers",
    "doc_id": "D08954797",
    "doc_exp": "2024/12/02",
    "dob": "1970/12/02",
    "state": "WA",
    "country": "USA"
  },
  "tip": "20%"
}

Sale transaction request

Properties

Name	Type	Required	Restrictions	Description
payment_type	string	false	none	Type of payment instrument (debit, credit, ach). Leave empty for consumer choice.
amount	number	true	none	Transaction sale amount
employee	Employee	false	none	Employee associated with transaction
terminal_id	string	true	none	Specified terminal to initiate sale
id_document	IDDocument	false	none	Consumer identifying document information
reference_id	string	false	none	POS provided unique transaction id
display_tips	boolean	true	none	Show consumer tip screen (on supported terminals)
display_id_scan	boolean	false	none	Show screen for scanning consumer ID Document (on supported terminals)
tip	string	false	none	Selected tip option value

AccountResponse

{
  "id": "",
  "name": "POSaBIT",
  "address": "123 ABC Ln",
  "city": "Kirkland",
  "state": "WA",
  "zip": "98053",
  "payment_types": [
    "debit",
    "credit"
  ],
  "terminals": [
    {
      "id": "T12345",
      "name": "Terminal 1",
      "tipping": true,
      "id_scan": true
    }
  ],
  "tips": {
    "mode": "fixed",
    "value1": "5",
    "value2": "10",
    "value3": "15"
  }
}

Root Type for AccountResponse

Properties

None

Terminal

{
  "id": "T12345",
  "name": "Terminal 1",
  "tipping": true,
  "id_scan": true
}

Root Type for Terminal

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Unique terminal identifier
name	string	false	none	Common terminal name
tipping	boolean	false	none	Whether terminal supports consumer tipping
id_scan	boolean	false	none	Whether terminal supports scanning ID documents

TipSetting

{
  "mode": "fixed",
  "value1": "5.00",
  "value2": "10.00",
  "value3": "14.99"
}

Root Type for Tip

Properties

Name	Type	Required	Restrictions	Description
mode	string	false	none	Supports fixed and percent modes (example "fixed" or "percent")
value1	string	false	none	First tipping option. Fixed amount or percentage.
value2	string	false	none	Second tipping option. Fixed amount or percentage.
value3	string	false	none	Third tipping option. Fixed amount or percentage.

TerminalStatusResponse

{
  "status": "online"
}

Root Type for TerminalStatusResponse

Properties

Name	Type	Required	Restrictions	Description
status	any	false	none	Online status of a terminal

ErrorResponse

{
  "status": "invalid",
  "code": "P101",
  "message": "An error message"
}

Root Type for Response

Properties

Name	Type	Required	Restrictions	Description
code	string	false	none	Result code of zero string for success. Othersize will contain error code reference.
message	string	false	none	Description text of error details
status	string	false	none	General status code for the operation

AuthRequest

{
  "client_id": "1525430608",
  "client_secret": "65s9CiZ6PqCKnKSg0FkAuTEM5",
  "scope": "sale"
}

Root Type for AuthRequest

Properties

Name	Type	Required	Restrictions	Description
client_id	string	false	none	Client identity
client_secret	string	false	none	Client secret
scope	string	true	none	Space seperated list of session scopes

AuthResponse

{
  "token": "E3FD1D8B-E0DA-4CC4-9D72-7399F24E548B",
  "expiration": "1610525430608"
}

Root Type for AuthResponse

Properties

Name	Type	Required	Restrictions	Description
token	string	false	none	Session token identifier
expiration	string	false	none	Token expiration time

SaleResponse

{
  "status": "complete",
  "payment_type": "debit",
  "total_amount": 176.12,
  "sale_amount": 163.54,
  "tip": 12.58,
  "change": 0,
  "fee": 1.5,
  "datetime": "2021-07-28 15:49:22 -0700",
  "reference_id": "T0123456789",
  "auth_code": "263891",
  "confirmation_code": "DAF4-F9435133",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "terminal_id": "001740F0-6613-4E4A-99DD-C623F707F75A"
}

Response from transaction sale

Properties

Name	Type	Required	Restrictions	Description
payment_type	string	false	none	Payment type of transaction
total_amount	number	false	none	Total amount charged to consumer not including fee
reference_id	string	false	none	POS provided unique transaction id
auth_code	string	false	none	Authorization code provided by card processor
confirmation_code	string	false	none	Short transaction reference code
sale_amount	number	false	none	Amount charged to consumer not including tip, change or fee
tip	number	false	none	Tip amount
change	number	false	none	Change amount due back to consumer at end of sale
fee	number	false	none	Service fee charged to consumer
datetime	string	false	none	Date and time the transaction occurred.
status	string	true	none	General status of the operation
refunds	[RefundResponse]	false	none	List of and applied refund transactions
transaction_id	any	false	none	Transaction Id from server.

RefundRequest

{
  "refund_reference_id": "R0123456789",
  "amount": 125.45
}

Root Type for RefundRequest

Properties

Name	Type	Required	Restrictions	Description
transaction_id	string	false	none	POSaBit Transaction Id
amount	number	false	none	Amount to refund the transaction
refund_reference_id	string	false	none	Refund Reference Id unique to parent transaction.

RefundResponse

{
  "amount": 24.5,
  "auth_code": "263891",
  "datetime": "2021-07-28 15:49:22 -0700",
  "transaction_id": "0000FF11-CBF8-49D1-BAA1-51D155FF753E",
  "refund_reference_id": "R01234565",
  "status": "complete"
}

Root Type for Refund

Properties

Name	Type	Required	Restrictions	Description
transaction_id	string	false	none	Server provided Transaction Id for refund
amount	number	false	none	Amount refunded
datetime	string(date-time)	false	none	Date and time the refund occurred
auth_code	string	false	none	Authorization code provided by card processor
status	string	false	none	Status of refund portion of the transaction
refund_reference_id	string	false	none	POS provided Reference Id for refund

Payments

Point of sale

Payments

Introduction

Setup Requirements

Credentials

Authentication

Transactions

Overview

Sale Example

Auth Request:

Auth Response:

Sale Request:

Sale Response:

Testing

Sale Request:

Status

Errors

API

Authenticate

Parameters

Responses

Sale

Parameters

Responses

Account

Responses

Transaction

Parameters

Responses

Cancel Transaction

Parameters

Responses

Refund Transaction

Parameters

Responses

Terminal

Parameters

Responses

Schemas

Employee

Properties

IDDocument

Properties

SaleRequest

Properties

AccountResponse

Properties

Terminal

Properties

TipSetting

Properties

TerminalStatusResponse

Properties

ErrorResponse

Properties

AuthRequest

Properties

AuthResponse

Properties

SaleResponse

Properties

RefundRequest

Properties

RefundResponse

Properties