POS Integration Service

Architecture

How the system works

Integration check List

Setup

BASE_URL='https://sandbox-api.payosy.com

API credentials for the test environment will be shared by mail.

Sale Flow

Sale APIs are used to turn orders into fiscal receipts. You can use them on both Sardis (400TR) Instant Sale API allows printing receipts and payment items at request time. Sale APIs are used to turn orders into fiscal receipts. The 3rd party Client Apps should provide a callback URL for sale flow. Otherwise, payment details cannot be sent.

curl --request POST \
  --url BASE_URL/api/instantorder \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-ibm-client-id: REPLACE_THIS_KEY' \
  --header 'x-ibm-client-secret: REPLACE_THIS_KEY' \
  --data '{
   "terminalid": "EC0000000002",
   "id": "1213",
   "asyncACK": false,
   "isCopy":0,
   "typeCode":0,
   "note":" YİNE BEKLERİZ",
   "currencyCode":0,
   "basketID":"1213",
   "taxTypeCode":0,
   "customerInfo":{
      "taxID":"99999999999",
      "name":"Mustafa Koray AKÇOCUK",
      "isLock":true,
      "room":"1",
      "street":"Koray Akcocuk Cd.",
      "buildingName":"Koray Binası",
      "buildingNumber":"16",
      "citySubdivisonName":"Alanya",
      "cityName":"Antalya",
      "postalZone":"07110",
      "region":"Güller Pınarı",
      "country":"Turkiye",
      "taxScheme":"Alanya",
      "telephone":"0 232 333 33 33",
      "telefax":"0 232 111 11 11",
      "email":"xxxx@xxxx.com"
   },
   "items":[
      {
         "name":"ÜLKER ÇİKOLATALI GOFRET",
         "priceType":0,
         "price":150,
         "taxPercent":800,
         "taxType":0,
         "quantityType":"NIU",
         "quantity":3000,
         "adjust":{
            "discountOrSurcharge":0,
            "type":0,
            "value":50,
            "description":"HOPI"
         }
      },
      {
         "name":"ELEKTRIK",
         "priceType":0,
         "price":15522,
         "taxPercent":1800,
         "taxType":0,
         "quantityType":"KWH",
         "quantity":2000
      },
      {
         "name":"SÜT",
         "priceType":0,
         "price":500,
         "taxPercent":1800,
         "taxType":0,
         "quantityType":"NIU",
         "quantity":50000
      }
   ],
   "paymentItems": [ 
       { 
           "amount":100,
           "operatorId":64,
           "type":3,
           "description": "CREDIT"
       },
       { 
           "amount":100,
           "operatorId":0,
           "type":1,
           "description": "CASH"
       }
   ],
   "adjust":{
      "discountOrSurcharge":0,
      "type":0,
      "value":50,
      "description":"HOPI"
   }
}'

a. Receipt with the following parameters is created.

NameTypeDescriptionExample

terminalid

string

Device unique id

'EC0000000002'

id

string

Attention: This number must be unique cannot be reset. See “orderid”. Unique number for receipt. Order can be tracked with this number such as: details, void operations

'1213'

asyncACK

boolean

Optional. If you don’t want to wait to ACK of device for HTTP response send as true; ACK will be sent to your callback url later.

false

b. Send order to device with client id and secret. If “asyncACK” is true then you will receive this as HTTP 200 Response’s Body. Order Received message by device

{
    "status": 0,
    "id": "1213",   // unique id of the order
    "msg": "OK"
}

c. When payment is completed, receipt details will be sent to the callback URL that provided at the subscription. Successful complete example:

{ 
    "id":"1213",
    "terminalid":"EC0000000002",
    "responseType":1, // operation instant sale
    "status":0,
    "msg": "OK",
    "invoiceID":"ERT2019000019890",
    "UUID":"4C76822B-D007-446E-8617-4432F94E2F61",
    "InstanceIdentifier":"4C76822B-D007-446E-8617-4432F94E2F61",
    "paymentCount": 1,
    "paymentItems": [ 
        { 
            "amount":100,
            "operatorId":64,
            "type":3,
            "description": "CREDIT"
        }
    ]
}
  • Main fields of callback response

NameTypeDescriptionExample

id

string

Unique id that sent with order from client id.

‘1000'

terminalid

string

Terminal ID.

‘EC0000000002'

responseType

int

0: ORDER, 1: INSTANT SALE. Which type of sale is completed or cause error

1

status

int

0: Success, Rest is error. See appendix for explanation of error types

0

Status Codes

Status

Description

Type

Step

Source

0

Successful

success

-

POS

-1

User Cancelled

warn

5, 7

POS

1

Missing Info

error

5

POS

2

Invalid E-Invoice Customer

error

6

E-Invoice Integrator

3

E-Invoice Integrator Error

error

10

E-Invoice Integrator

4

Network Error

error

5, 9

POS

5

Offline Invoice

success

-

POS

6

Onboarding error

error

5

POS

7

Invalid E-invoice Id

error

10

E-Invoice Integrator

8

Missing Customer Info

error

5

POS

9

POS is Busy

warn

5

POS

10

Payment Plan Error

error

7

POS

11

Payment is cancelled

warn

7

POS

12

Unknown E-Invoice Integrator

error

5

POS

13

Integrator Response Parsing Error

error

10

POS

1001

Missing ClientId

error

1

API

1002

Missing TerminalId

error

1

API

1003

Timeout

warn

3

API

1004

Missing Info

error

1

API

1005

Locked Transaction

warn

1

API

1006

Record not Found

error

1

API

1007

Duplicate ID

error

1

API

1008

Unauthorized Terminal Error

error

1

API

1009

Callback URL Error

warn

12

API

1010

Timeout

warn

3

API

1011

Transaction was not delivered to the terminal

warn

2

API

1012

Transaction is not completed yet

info

4...11

API

1013

Wrong data format

error

1

API

1014

General Error

error

1...11

API

5001

Error

error

7, 8

Bank

5002

Cancelled

warn

7, 8

Bank

5003

Offline Decline

error

7, 8

Bank

5004

Unable Decline

error

7, 8

Bank

5005

Online Decline

error

7, 8

Bank

5006

Payment App Not Found

error

7

Bank

5008

Bank App Not Found

error

7

Bank

5009

Bank App Crashed

error

8

Bank

5101

Card Validation Error

error

7

Bank

5102

Card Validation User Cancelled

warn

7

Bank

5104

Card Validation Timeout

error

7

Bank

5105

Card Validation Fallback Auth

error

7

Bank

5106

Card Validation Parsing Error

error

7

Bank

5107

Card is not Valid

warn

7

Bank

5108

Card Type is not Credit

warn

7

Bank

5109

Card Type is not Debit

warn

7

Bank

5110

Card Type is not Foreign

warn

7

Bank

5111

Card is not Issued by Requested Bank

warn

7

Bank

Access to API's

Last updated