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":"[e-mail]"
   },
   "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.

Name	Type	Description	Example
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

Name	Type	Description	Example
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

3KB

Token Basket Postman Collections.postman_collection.json.zip

archive