> For the complete documentation index, see [llms.txt](https://developer.tokeninc.com/token-developer-portal-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tokeninc.com/token-developer-portal-1/x-platform/integration-via-backend-old/pos-integration-service.md).
# POS Integration Service
## Architecture
.jpg?alt=media&token=09770086-844b-4497-b7c3-90d2f87827a9)
## 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.
```bash
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.
| 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
```json
{
"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:
```json
{
"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 | BIN Query Error | 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 Domestic | warn | 7 | Bank |
| 5111 | Card is not Issued by Requested Bank | warn | 7 | Bank |
| 5112 | Card Type is not Foreign | warn | 7 | Bank |
## Access to API's
{% file src="/files/BUecd2vYCWl8sjlC0F6d" %}