Versions Compared

Version Old Version 14 New Version 15
Changes made by

Support team (Unlicensed)

Daniil Kabirov (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Terms and definitions

POS (point of sale)- a place where a user executes the payment for goods or services

Merchant - small amd medium enterprises, supplier of goods and/or services that work with the SWiP service.

Integrator - an employee of POS/merchant/third-party who connects the merchant's POS to the SWiP system and provides further support.

SWiP loyalty - a loyalty program provided SWiP, which is configured by the merchant.

User - a person who makes purchases and pays through the SWiP app.

Payment scenarios - SWiP supports following payment scenarios:

Scenario 1 - the user pays by the SWiP app after SWiP loyalty calculation. Payments can be made via various methods: from bank cards, from e-wallets, from payment system, from national payment system and other methods.
Scenario 2 - the user makes payment in cash or by bank card at the terminal after SWiP loyalty calculation.

Two-stage payments - a payment operation that requires additional confirmation.

Holding - the user makes the payment and the funds are put on hold on their bank card. While the funds are put on hold, you can debit funds or cancel the payment within the specified timeout (the payment cancellation period can be changed in the settings).
Withdraw - funds on hold are debited after confirmation.

Using the API

POS API - a programming interface for accepting online payments executed by the SWiP service. Using the API you can execute a payment, cancel a payment, make refunds, get statements with all orders that are made by the SWiP service.

Intergration schema

SWiP loyalty calculation and payment inside SWiP app

During the payment process, SWiP loyalty is calculated, if loyalty is provided for the user. This scenario includes payment inside SWiP app using the following payment methods: from bank cards, from e-wallets, from payment system, from national payment system and other methods.

Drawio
zoom1
simple0
inComment0
pageId8716310
custContentId11403318
lbox1
diagramDisplayNamepaymentbycash
contentVer3
revision3
baseUrlhttps://swipsw.atlassian.net/wiki
diagramNameДиаграмма без названия-1670504786808.drawio
pCenter0
width591
links
tbstyle
height471

HTTP protocol

Step 1. The POS system creates an order.

Step 2. The POS system receives the Order object.

Step 3. The SWiP app requests order detailed information.

Step 4. The User receives the Order object with personalized loyalty at the SWiP app.

Step 5. The User confirms payment at the SWiP app.

Step 6. The SWiP server sends a request for order payment.

Step 7. The SWiP server receives order payment confirmation.

Step 8. The SWiP app receives order payment confirmation from the SWiP server.

Step 9. The POS system sends a request to get the information about the current order status.

Step 10. The POS system receives paid order with applied loyalty.

Step 11. The POS system sends a request to close the order.

SWiP loyalty calculation and payment by cash or card in bank terminal

During the payment process, SWiP loyalty is calculated, if loyalty is provided for the user. This scenario includes payment by cash or card in bank terminal.

Drawio
zoom1
simple0
inComment0
pageId8716310
custContentId10944572
lbox1
diagramDisplayNamepaymentbycash
contentVer3
revision3
baseUrlhttps://swipsw.atlassian.net/wiki
diagramNamepaymentbycash
pCenter0
width431
links
tbstyle
height472

HTTP protocol

Step 1. The POS system creates an order.

Step 2. The POS system receives the Order object.

Step 3. The SWiP app requests order detailed information.

Step 4. The User receives the Order object with personalized loyalty at the SWiP app.

Step 5. The User confirms payment via alternative payment method (by cash or card in bank terminal).

Step 6. The POS system sends a request to get the information about the current order status.

Step 7. The POS system receives unpaid order with applied loyalty.

Step 8. The POS accepts payment by cash or card in bank terminal.

Step 9. The POS system sends a request to close the order.

Integration URL

URL of the integration environment https://capi-test.smartwallet.ru.

Order and session identification

The id and the merchantOrderId fields act as an order identifier.

Field name

Description

id (UUID)

The identifier in the SWiP system. POS should not fill it. POS creates an order, sending an order object (Order). The Order object returns with the specified id field. This field is used in GET requests.

merchantOrderId

Order id in the merchant's system.

The sessionCode field acts as a session identifier.

Field name

Description

sessionCode

The session identifier (text value encrypted in QR code). If the POS system works in restaurant mode, then QR code is received from the server's response to order creation request.

Transport and protocol

The API uses HTTPS as protocol. Messages are represented in the JSON format.

Authentication

Authentication is implemented by a static token. Token must be sent in the header of HTTP requests.

The header in every API request should include:

Field name

Value example

Description

Authorization

Bearer 8c6b8b64-6815-6084-0a3e-178401251b68

Token from the merchant’s marketing engine.

X-Merchant-ID

ABCD

The value is sent by the SWiP employee after the merchant's onboarding. Four-letter codes are used at the moment. The values can be expanded in the future.

X-Store-ID

Test storeID

Store ID that the SWiP employee sends after the merchant's onboarding. The value is taken from the merchant's system: either the real identifier of the store or, if it cannot be received from POS, the value from the SWiP plugin settings.

X-Cash-ID

1231

POS ID in the merchant's system.

Api-Version

3

API version.

Integration scenarios

POS API supports several payment scenarios. They differ depending on the payment method and store’s settings.

Grocery store, bakery, coffee shop, restaurant, supermarket and many others

Example of implementation:

  1. The user makes an order at the POS system.

  2. POS creates an order and sends parameters in the API request headers (for more information, see the Authentication chapter):
    X-Merchant-ID - the identifier of the merchant;
    X-Store-ID - the identifier of the store in the merchant's system;
    X-Cash-ID - POS ID in the merchant's system.

  3. The user confirms the payment.

  4. POS closes the order and prints the fiscal receipt.

Vending machine

Example of implementation:

  1. The user selects a product on the vending machine.

  2. The vending machine creates an order and sends parameters in the API request headers (for more information, see the Authentication chapter):
    X-Merchant-ID - the identifier of the merchant;
    X-Store-ID - the identifier of the vending machine;
    X-Cash-ID - modem IMEI or empty value.

  3. The user confirms the payment and receives the product.

Order object

The Order object (Order) contains all currently relevant information about the order. The object is generated during creation of an order and sent as a response to some requests.

Order object can contain other fields that POS is not using yet. They should be ignored.

*- the fields that are filled in by the POS system when creating an order.

Parameter

Type

Description

id

string (UUID)

Order ID in the SWiP system.

merchantOrderId*

string

Order ID in the merchant's system.
(If the merchant uses the UUID format to identify orders, this value can be used for the order ID in the SWiP system).

apiVersion

integer

API version which was used for the order payment.

authorizationCode

string

Authorization code from payment system.

cash

boolean

Attribute of an alternative payment method.

closeAmount*

double

Order closing amount. Indicated after the order closing.

customerId

string (UUID)

ID of a customer who paid the order. Indicated after the order closing.

discountCard

string

Discount card ID in the SWiP system.

error

string

Text description of the last error by order payment.

merchantCash

string

POS or POS group ID (no need to fill, is taken from HTTP request headers).

merchantCashier*

string

Cashier name.

merchantCashierId*

string (UUID)

Cashier ID. For POS systems, that sets this parameter.

merchantCategory

string

Description of the merchant scope.

merchantCommission

double

Merchant's external commission.

merchantDiscount

double

Discount provided by merchant.

merchantId

string (UUID)

Merchant ID in the SWiP system.

merchantName

string

Merchant name.

merchantOrderNumber*

string

Order number in the merchant’s system (printed on a receipt usually).

merchantProfileImageId

string (UUID)

Image ID in the merchant’s profile.

merchantStore

string

Merchant store ID (no need to fill, is taken from HTTP request headers).

orderNumber

string

Order number in the acquirer bank.

orderStatus

OrderStatus

Order status. Possible values:

  • OPEN,

  • CLOSED.

paid

double

Amount paid by the user using the application. Indicated after the payment is confirmed by the bank.

pan

string

Masked card number.

paymentMethod

PaymentMethod

Payment method. Possible values:

  • CARD,

  • CREDIT,

  • CASH.

paymentSystem

PaymentSystem

Payment system. Сurrent values:

  • AMEX,

  • VISA,

  • MASTERCARD.

If necessary, the list can be expanded.

purchases

object

List of purchases.

refunded

double

Order refund amount.

rrn

string

Unique identifier of the bank transaction that is assigned by the Acquiring Bank when the payment is initialized.

saleDate*

long

Sale date (milliseconds since 1970.01.01). The creation date does not have to match the date that will be printed on the receipt.

sessionCode*

string

QR code (only in fast food and offline store mode).
If the field is sent empty, the SWiP server generates its value.
If you pay using Selfie2Pay, you do not need to fill in this field.

slip

string

Formatted text (80 symbols in width) with bank information about payment.

terminalNo

string

Bank terminal number.

total*

double

Purchase amount with discount.

totalOriginal*

double

Purchase amount without discount.

unconfirmed

double

Amount paid by the user using the application, but not confirmed by POS (paid>=unconfirmed).

Purchases object

Parameter

Type

Description

id

string (UUID)

Product ID.
If merchant uses UUID to identify purchases, it can be used as ID. If not, the SWiP server generates UUID.

discount

double

SWiP calculated loyalty for purchase (under development).

parentId

string (UUID)

Parent product ID. If the order contains products with modifier, than the modifier should have parentId.

productId

string (UUID)

Product item (product ID) in the merchant’s system.

name

string

Description of purchase.

quantity

double

Quantity (pieces, kilograms, liters).

price

double

Price.

amount

double

Amount (price * quantity).

unit

Unit

Units (LITERS, KILOGRAMS, PIECES).

Example of ORDER object

Code Block
languagejson
{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": true,
  "closeAmount": 0.0,
  "customerId": null,
  "discountCard": "string",
  "error": "string",
  "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantCash": "88",
  "merchantCashier": "Cashier name",
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",
  "merchantCategory": "Electronics",
  "merchantCommission": 0,
  "merchantId": "VZLT",
  "merchantName": "shop",
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantOrderNumber": "11",
  "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381",
  "merchantStore": "3",
  "orderNumber": "28048058915136358726242016980679",
  "orderStatus": "OPEN",
  "paid": 0.0,
  "pan": "string",
  "paymentMethod": "CARD",
  "paymentSystem": "AMEX",
  "purchases": [
    {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",
      "discount": 0,
      "name": "Sprite 0,33 l",
      "parentId": "string",
      "productId": null,
      "quantity": 0,
      "unit": "string",
      "price": 50.0,      
      "amount": 50.0, 
    }
  ],
  "refunded": 0,
  "rrn": "string",
  "saleDate": 1540485815026,
  "sessionCode": "https://swip.one/?qr=6794742",
  "slip": "...very long text...",
  "terminalNo": "string",
  "total": 50.0,
  "totalOriginal": 50.0,
  "unconfirmed": 0.0
}

Create an order

To send an order for loyalty calculation and payment execution, you need to create an Order object. It contains all the necessary payment information.
If necessary, you can always send a single product in the Purchases object, for example, a service.

The order can be in the OPEN status for 1,5 minutes for POS systems that operate in fast food or retail mode. For POS systems operating in restaurant mode, the timeout is 10 hours.

Endpoint

POST /orders

Request format

To create an order, you have to send a request with the following parameters:

Parameter

Type

Description

required

merchantOrderId

string

Order ID in the merchant's system.
If the merchant uses the UUID format to identify orders, this value can be used for the order ID in the SWiP system.

merchantCashier

string

Cashier name.

saleDate

long

Sale date (milliseconds since 1970.01.01). The creation date does not have to match the date that will be printed on the receipt.

total

double

Purchase amount with discount.

totalOriginal

double

Purchase amount without discount.

purchases

class

Purchase list.

name

string

Description of purchase.

quantity

double

Quantity (pieces, kilograms, liters).

price

double

Price.

amount

double

Amount (price * quantity).

optional

sessionCode

string

QR code text value.
POS can send any value in this field.
If the field is sent empty, the SWiP server generates its value.
If you pay via Selfie2Pay, you do not need to fill in this field.

merchantOrderNumber

string

Merchant order number (printed on a receipt usually).

merchantCashierId

string

Cashier ID. For POS systems, that sets this parameter.

id

string

Product ID.
If merchant uses UUID to identify purchases, it can be used as id. If not, the SWiP server generates UUID.

productId

string

Product item (product ID) in the merchant’s system.

unit

Unit

Units (LITERS, KILOGRAMS, PIECES).

guests

double

Number of guests

parentId

string

Parent product ID. If the order contains products with modifier, than the modifier should have parentId.

Request example

Code Block
languagejson
{
  "guests": 0,                                                  // number of guests														
  "merchantCashier": "Cashier name",                            // cashier name	   							
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",  // cashier ID		
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",    // order ID in the merchant's system		
  "merchantOrderNumber": "11",               	                // order number in the merchant's system (printed on a receipt usually)										
  "purchases": [
     {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",             // product ID in the SWiP system												
      "name": "Sprite 0,33 l",                                  // item name
      "parentId": "string",										
      "productId": null,                                        // product item (product ID)						
      "quantity": 0,                                            // quantity (in selected units)
      "unit": "string",                                         // units (LITERS, KILOGRAMS, PIECES)
      "price": 50.0,                                            // price								    
      "amount": 50.0,                                           // total amount (price * quantity) 
    }
  ],
  "saleDate": 1540485815026,                                    // sale date (milliseconds since 1970.01.01)
  "sessionCode": "https://swip.one/?qr=6794742",                // QR code text value 
  "total": 50.0,                                                // purchase amount with discount
  "totalOriginal": 50.0                                         // purchase amount without discount
}

Response format

The response to the request will contain the same order with the filled fields:

  • id - SWiP orderId,

  • sessionCode.

If sessionCode was sent empty, then the filled in field will return. It should be printed on the guest receipt or shown on the screen (of the POS system) to the user.

Response example

Code Block
languagejson
{
  "apiVersion": 3,                                                    // API version 
  "authorizationCode": "string",                                      // authorization code from payment system 
  "cash": true,
  "closeAmount": 0.0,
  "customerId": null,
  "discountCard": "string",                                           // discount card ID in the SWiP system 
  "error": "string",                                                  // text description of the last error by order payment
  "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1",                       // order ID in the SWiP system
  "merchantCash": "88",                                               // POS or POS group ID
  "merchantCashier": "Cashier name",                                  // cashier name
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",        // cashier ID 
  "merchantCategory": "Electronics",                                  // description of the merchant scope
  "merchantCommission": 0,                                            // merchant's external commission
  "merchantId": "VZLT",                                               // merchant ID in the SWiP system 
  "merchantName": "shop",                                             // merchant name
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",          // order ID in the merchant's system
  "merchantOrderNumber": "11",                                        // order number in the merchant's system (printed on a receipt usually)
  "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381",   // image ID in the merchant's profile 
  "merchantStore": "3",                                               // merchant store ID
  "orderNumber": "28048058915136358726242016980679",                  // order number in the acquirer bank
  "orderStatus": "OPEN",                                              // order status
  "paid": 0.0,
  "pan": "string",                                                    // masked card number
  "paymentMethod": "CARD",                                            // payment method
  "paymentSystem": "AMEX",                                             // payment system
  "purchases": [                                                      // list of purchases
     {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",                   // product ID in the SWiP system
      "discount": 0,
      "name": "Sprite 0,33 l",                                        // item name
      "parentId": "string",
      "productId": null,                                              // product item (product ID) 
      "quantity": 0,                                                  // quantity (in selected units)
      "unit": "string",                                               // units (LITERS, KILOGRAMS, PIECES)
      "price": 50.0,                                                  // price     
      "amount": 50.0,                                                 // total amount (price * quantity)
    }
  ],
  "refunded": 0,											          // order refund amount
  "rrn": "string",                                                    // unique identifier of the bank transaction
  "saleDate": 1540485815026,                                          // sale date (milliseconds since 1970.01.01)
  "sessionCode": "https://swip.one/?qr=6794742",                      // QR code text value
  "slip": "...very long text...",                                     // formatted text with bank information about payment 
  "terminalNo": "string",                                             // bank terminal number
  "total": 50.0,                                                      // purchase amount with discount 	
  "totalOriginal": 50.0,                                              // purchase amount without discount
  "unconfirmed": 0.0                                                  // amount paid by the user using the application, but not confirmed by POS
}

Get an order

Sends a request to get the information about the current order status by its unique ID.

Endpoint

GET /orders/{id}

Request format

To get the information about the current order status, you have to send a request with the following parameters:

Parameter

Type

Description

id

string, required

Unique order ID in the SWiP system.

Response format

The response to the request will contain the Order object with the current status.

Response example

Code Block
languagejson
{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": true,
  "closeAmount": 0.0,
  "customerId": null,
  "discountCard": "string",
  "error": "string",
  "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantCash": "88",
  "merchantCashier": "Cashier name",
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",
  "merchantCategory": "Electronics",
  "merchantCommission": 0,
  "merchantId": "VZLT",
  "merchantName": "shop",
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantOrderNumber": "11",
  "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381",
  "merchantStore": "3",
  "orderNumber": "28048058915136358726242016980679",
  "orderStatus": "OPEN",
  "paid": 0.0,
  "pan": "string",
  "paymentMethod": "CARD",
  "paymentSystem": "AMEX",
  "purchases": [
    {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",
      "discount": 0,
      "name": "Sprite 0,33 l",
      "parentId": "string",
      "productId": null,
      "quantity": 0,
      "unit": "string",
      "price": 50.0,      
      "amount": 50.0, 
    }
  ],
  "refunded": 0,
  "rrn": "string",
  "saleDate": 1540485815026,
  "sessionCode": "https://swip.one/?qr=6794742",
  "slip": "...very long text...",
  "terminalNo": "string",
  "total": 50.0,
  "totalOriginal": 50.0,
  "unconfirmed": 0.0
}

Order status options and how they change

The POS system waits 45 seconds for payment. If there is no payment during this time, the POS system closes the order with amount=0.

An order can have the following statuses:

  • OPEN,

  • CLOSED.

Payment is determined by the paid field. Let's say that a payment is made for 100 monetary units:

  1. Order creation:
    status=OPEN, totalOriginal=100, total=100, paid=0, unconfirmed=0

  2. Payment:
    status=OPEN, totalOriginal=100, total=100, paid=100, unconfirmed=100

  3. Order closure:
    status=CLOSED, totalOriginal=100, total=100, paid=100, unconfirmed=0

If you close the order with amount=0, the payment will be cancelled:
status=CLOSED, totalOriginal=100, total=100, paid=0, unconfirmed=0

Close an order

Sends a request to close the order.

Order closing method can be requested only once. In the request body, you must pass the order closing amount. If there is an error in the closing process or there is no order closing amount, the money for the order will be refunded.

Endpoint

POST /orders/{id}/actions/close

Request format

To close the order, you have to send a request with the following parameters:

Parameter

Type

Description

id

string, required

Unique order ID in the SWiP system.

amount

double, required

Order closing amount.

Request example

Code Block
languagejson
{  
   "amount":50.0
}

Response format

The response to the request will contain the Order object with the current status.

Code Block
languagejson
{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": true,
  "closeAmount": 0.0,
  "customerId": null,
  "discountCard": "string",
  "error": "string",
  "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantCash": "88",
  "merchantCashier": "Cashier name",
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",
  "merchantCategory": "Electronics",
  "merchantCommission": 0,
  "merchantDiscount": 0,
  "merchantId": "VZLT",
  "merchantName": "shop",
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantOrderNumber": "11",
  "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381",
  "merchantStore": "3",
  "orderNumber": "28048058915136358726242016980679",
  "orderStatus": "OPENCLOSED",
  "paid": 0.0,
  "pan": "string",
  "paymentMethod": "CARD",
  "paymentSystem": "AMEX",
  "purchases": [
    {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",
      "discount": 0,
      "name": "Sprite 0,33 l",
      "parentId": "string",
      "productId": null,
      "quantity": 0,
      "unit": "string",
      "price": 50.0,      
      "amount": 50.0, 
    }
  ],
  "refunded": 0,
  "rrn": "string",
  "saleDate": 1540485815026,
  "sessionCode": "https://swip.one/?qr=6794742",
  "slip": "...very long text...",
  "swipDiscount": 0,
  "terminalNo": "string",
  "total": 50.0,
  "totalOriginal": 50.0,
  "unconfirmed": 0.0
}

Refund

Only the order with the CLOSED status can be refunded.

Returns a successfully completed payment by the order’s unique ID. The SWiP loyalty will also be returned. Payment can be refunded in whole or in part. You are allowed to make an infinite number of partial refunds, as long as the total amount of all partial refunds does not exceed the payment amount.

Endpoint

POST /refunds

Request format

To make a refund, you have to send a request with the following parameters:

Parameter

Type

Description

amount

double, required

Amount to be refunded to the user.

merchantId

string, required

Merchant ID in the SWiP system.

merchantOrderId

string, required

Order ID in the merchant's system.

Request example

Code Block
languagejson
{
  "amount": 25.00,
  "merchantId": "d30ceaab-cc06-4f7c-bc58-2e86d336d7b3",
  "merchantOrderId": "130ceaab-cc06-4f7c-bc58-2e86d336d723"
}

Response format

The response to the request will contain the refund status and its description.

Response example

Code Block
languagejson
{
    "status": "SUCCESS",                  // refund status (SUCCESS, FAIL)
    "slip": "string",                     // text with bank information about the payment
    "description": "Some description",    // error description
    "code": 0                             // error code in the SWIP system
}

Cancel a payment

Only the order with the CLOSED status can be cancelled.

This method performs cancellation of a payment for which funds were put on hold and have not yet been captured. If it is already impossible to cancel the payment, an error with code 27 will be returned.

Endpoint

POST /reverses

Request format

To cancel the payment, you have to send a request with the following parameters:

Parameter

Type

Description

amount

double, optional

Amount of the payment cancellation.

merchantId

string, required

Merchant ID in the SWiP system.

merchantOrderId

string, required

Order ID in the merchant's system.

Request example

Code Block
languagejson
{
  "amount": 25.00,
  "merchantId": "d30ceaab-cc06-4f7c-bc58-2e86d336d7b3",
  "merchantOrderId": "130ceaab-cc06-4f7c-bc58-2e86d336d723"
}

Response format

The response to the request will contain the payment cancellation status and its description.

Response example

Code Block
languagejson
{
    "status": "SUCCESS",                  // cancellation status (SUCCESS, FAIL)
    "slip": "string",                     // text with bank information about the payment
    "description": "Some description",    // error description
    "code": 0                             // error code in the SWIP system
}

Cancel an order

This method is necessary in case of a timeout at POS or other reasons to cancel an order.

Cancels the order with the OPEN status.

Endpoint

POST /orders/{id}/actions/close

Request format

To cancel the order, you have to send a request with the following parameters:

Parameter

Type

Description

id

string, required

Unique order ID in the SWiP system.

amount

double, optional

Amount which POS transmits to cancellation.

Request example

Code Block
languagejson
{  
   "amount":0.0
}

The request body is optional. If it is absent, the entire order is cancelled.

Response format

The response to the request will contain the Order object with the current status.

Response example

Code Block
languagejson
{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": true,
  "closeAmount": 0.0,
  "customerId": null,
  "discountCard": "string",
  "error": "string",
  "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantCash": "88",
  "merchantCashier": "Cashier name",
  "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144",
  "merchantCategory": "Electronics",
  "merchantCommission": 0,
  "merchantId": "VZLT",
  "merchantName": "shop",
  "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1",
  "merchantOrderNumber": "11",
  "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381",
  "merchantStore": "3",
  "orderNumber": "28048058915136358726242016980679",
  "orderStatus": "OPENCLOSED",
  "paid": 0.0,
  "pan": "string",
  "paymentMethod": "CARD",
  "paymentSystem": "AMEX",
  "purchases": [
    {
      "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78",
      "discount": 0,
      "name": "Sprite 0,33 l",
      "parentId": "string",
      "productId": null,
      "quantity": 0,
      "unit": "string",
      "price": 50.0,      
      "amount": 50.0, 
    }
  ],
  "refunded": 0,
  "rrn": "string",
  "saleDate": 1540485815026,
  "sessionCode": "https://swip.one/?qr=6794742",
  "slip": "...very long text...",
  "terminalNo": "string",
  "total": 50.0,
  "totalOriginal": 50.0,
  "unconfirmed": 0.0
}

Response codes

In case an error occurs during the processing of a request, the API will return an error object and a standard HTTP code.

HTTP code

Description

Error code

200

Successful request.

400

Invalid request because of rule violations regarding the interaction with the API.

unauthorized

401

Invalid authorization.

unauthorized

403

No permission to access.

forbidden

404

Resource with specified ID was not found in the SWiP system.

not_found

405

Forbidden or unsupported method is used.

method_not_allowed

429

Too many requests sent in a short amount of time.

too_many_request

500

Internal server error.

internal_server_error

Error codes and description

Error code

Description

1

INTERNAL SERVER ERROR
Internal server error.

2

AUTHENTICATION ERROR
Invalid authentication.

4

ACCESS DENIED
Access is denied.

5

VALIDATION FAILED
Incorrect validation.

6

ILLEGAL STATE
Error of the wrong state of the current operation.

7

METHOD NOT SUPPORTED
Method is not supported.

8

DUPLICATE
Duplication of data.

9

NOT FOUND
Resource is not found.

10

UNSUPPORTED MESSAGE
Unsupported message.

11

ORDER FLOW VIOLATION
Violation of the order processing.

13

OPERATION TIMED OUT
Operation is timed out.

27

REVERSE UNAVAILABLE
Reverse is unavailable.

28

ORDER ALREADY EXISTS
Order already exists.

29

ORDER ALREADY REFUNDED
Order is already refunded.

30

ORDER ALREADY CONFIRMED
Order is already confirmed.

31

ORDER NOT PAID
Order is not paid.

32

EXCESS TOTAL AMOUNT
Attempt to return an amount in excess of the total order amount.

Error object

If something is wrong with the request (HTTP response code other than 200), then HTTP response codes 4xx or 5xx will return a response body in JSON format with a description of the error.

Example of response body in case of error

Code Block
languagejson
{
  "code": 0,                        // SWiP internal error code
  "description": "string",          // error description
  "fieldErrors": [                  // array of objects with detailed description
    {
      "field": "string",            // error field
      "message": "string",          // error details
      "objectName": "string"        // object class which had an error
    }
  ]
}

Table of Contents
minLevel1
maxLevel1
outlinetrue
absoluteUrltrue
Info

We are always ready to help and answer all your questions via support@swip.one