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 by 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.

Integration schema

SWIP can be delivered as an external loyalty system, as well as as an external loyalty system with the specified payment method. To learn more about these loyalty systems, see below.

SWiP loyalty calculation and payment inside the SWiP app

During the payment process, SWiP loyalty is calculated, if there is a loyalty program 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.

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 the paid order with applied loyalty.

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

SWiP loyalty calculation without payment inside the SWIP app

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

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://capi3.weawer.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. The POS must not fill it. The POS creates an order when 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 (the text value encrypted in the QR code). If the POS system works in a restaurant mode, then the QR code is received from the server's response to the order creation request.

Transport and protocol

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

Authentification

Authentification is implemented by a static token. The 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	The 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 the 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

The 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:

The user makes an order at the POS system.
The POS creates an order and sends parameters in the API request headers (for more information, see the Authentification 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 - the POS ID in the merchant's system.
The user confirms the payment.
The POS closes the order and prints the fiscal receipt.

Vending machine

Example of implementation:

The user selects a product on the vending machine.
The vending machine creates an order and sends parameters in the API request headers (for more information, see the Authentification chapter):
X-Merchant-ID - the identifier of the merchant;
X-Store-ID - the identifier of the vending machine;
X-Cash-ID - the modem IMEI or an empty value.
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.

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

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

The values in the Required column are the following:

true - the field is mandatory when interacting with the service
false - the field is not mandatory when interacting with the service

Parameter	Type	Description	Required
`id`	string (UUID)	Order ID in the SWiP system.	false
`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).	true
`apiVersion`	integer	API version which was used for the order payment.	false
`authorizationCode`	string	Authorization code from the payment system.	false
`cash`	boolean	Attribute of an alternative payment method.	false
`closeAmount`*	double	Order closing amount. Indicated after the order closing.	true
`customerId`	string (UUID)	ID of a customer who paid the order. Indicated after the order closing.	false
`discountCard`	string	Discount card ID in the SWiP system.	false
`error`	string	Text description of the last error by order payment.	false
`merchantCash`	string	POS or POS group ID (no need to fill, is taken from HTTP request headers).	false
`merchantCashier`*	string	Cashier name.	true
`merchantCashierId`*	string (UUID)	Cashier ID. For POS systems, that sets this parameter.	true
`merchantCategory`	string	Description of the merchant scope.	false
`merchantCommission`	double	Merchant's external commission.	false
`merchantDiscount`	double	Discount provided by a merchant.	false
`merchantId`	string (UUID)	Merchant ID in the SWiP system.	false
`merchantName`	string	Merchant name.	false
`merchantOrderNumber`*	string	Order number in the merchant’s system (printed on a receipt usually).	true
`merchantProfileImageId`	string (UUID)	Image ID in the merchant’s profile.	false
`merchantStore`	string	Merchant store ID (no need to fill, is taken from HTTP request headers).	false
`orderNumber`	string	Order number in the acquirer bank.	false
`orderStatus`	OrderStatus	Order status. Possible values: OPEN, CLOSED.	false
`paid`	double	Amount paid by the user using the application. Indicated after the payment is confirmed by the bank.	false
`pan`	string	Masked card number.	false
`paymentMethod`	PaymentMethod	Payment method. Possible values: CARD, CREDIT, CASH.	false
`paymentSystem`	PaymentSystem	Payment system. Сurrent values: AMEX, VISA, MASTERCARD. If necessary, the list can be expanded.	false
`purchases`	object	List of purchases.	false
`refunded`	double	Order refund amount.	false
`rrn`	string	Unique identifier of the bank transaction that is assigned by the Acquiring Bank when the payment is initialized.	false
`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.	true
`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.	true
`slip`	string	Formatted text (80 symbols in width) with bank information about the payment.	false
`terminalNo`	string	Bank terminal number.	false
`total`*	double	Amount after deducting discount.	true
`totalOriginal`*	double	Initial order amount.	true
`unconfirmed`	double	Amount paid by the user using the application, but not confirmed by the POS (paid>=unconfirmed).	false

Purchases object

The values in the Required column are the following:

true - the field is mandatory when interacting with the service
false - the field is not mandatory when interacting with the service

Parameter	Type	Description	Required
`id`	string (UUID)	Product ID. If merchant uses an UUID to identify purchases, it can be used as an ID. If not, the SWiP server generates the UUID.	true
`discount`	double	SWiP calculated loyalty for purchase (under development).	false
`parentId`	string	Parent product ID. If the order contains products with modifier, than the modifier should have `parentId`.	false
`productId`	string	Product item (product ID) in the merchant’s system.	true
`name`	string	Description of purchase.	false
`quantity`	double	Quantity (pieces, kilograms, liters).	true
`price`	double	Price.	true
`amount`	double	Amount (price * quantity).	false
`unit`	Unit	Units (LITERS, KILOGRAMS, PIECES).	false

Example of the ORDER object

{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": false,
  "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 the fast food or retail mode. For POS systems operating in restaurant mode, the timeout is 10 hours.

If one of the following methods was used (/close, /reverses или /refund), and there is a need to create the same or lightly modified order, then it has to have a new merchantOrderId, even if for a single product.

Endpoint

POST /orders

Request format

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

The values in the Required column are the following:

true - the field is mandatory when interacting with the service
false - the field is not mandatory when interacting with the service

The request body in each API request must include:

Parameter	Type	Description	Required
`sessionCode`	string	QR code text value. The 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.	false
`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.	true
`merchantOrderNumber`	string	Merchant order number (printed on a receipt usually).	false
`merchantCashierId`	string	Cashier ID. For POS systems, that sets this parameter.	false
`merchantCashier`	string	Cashier name.	true
`saleDate`	date	Sale date (milliseconds since 1970.01.01). The creation date does not have to match the date that will be printed on the receipt.	true
`total`	double	Amount after deducting discount.	true
`totalOriginal`	double	Initial order amount.	true
`purchases`	list	Purchase list.	true
`guests`	integer	Number of guests	false
`posType`	string	Pos type. Possible values: IIKO RKEEPER ONE_C TELEMETRON FRONTOL	true
`positionalDiscount`	boolean	Positional discount (influences the `mrp` parameter)	false

Purchases details

Parameter	Type	Description	Required
`id`	string	Product ID. If merchant uses an UUID to identify purchases, it can be used as id. If not, the SWiP server generates the UUID.	false
`name`	string	Description of purchase.	true
`parentId`	string	Parent product ID. If the order contains products with a modifier, than the modifier should have `parentId`.	false
`productId`	string	Product item (product ID) in the merchant’s system.	false
`quantity`	double	Quantity (pieces, kilograms, liters).	true
`unit`	Unit	Units (LITERS, KILOGRAMS, PIECES).	false
`price`	double	Price.	true
`amount`	double	Amount (price * quantity).	true
`mrp`*	double	Minimal retail price	false

*Example of calculation using MRP (minimal retail price)
Here, we are recalculating the final discount.

For example, there are two products that cost $100.
product 1 : $100
product 2 : $100 (mrp $90)

if a 20% discount is applied to this purchase, then the final discount will be $30, which accounts to 15%.

As a result, the system will display 15% on the scoreboard.

Note: The mrp parameter can be applied only if positionalDiscount: true

Request example

{
  "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)										
  "posType": "RKEEPER"                                          // origin of order cash
  "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 field with filled in values will return. It should be printed on the guest receipt or shown on the screen (of the POS system) to the user.

If there is a discount on the entire receipt or on one of the products in the receipt, the DISCOUNT field value in the purchase object will be greater than zero if POSITION DISCOUNT = true.

Response example

{
  "apiVersion": 3,                                                    // API version 
  "authorizationCode": "string",                                      // authorization code from payment system 
  "cash": false,
  "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	Parameter type	Type	Description	Required
`id`	path	string	Unique order ID in the SWiP system.	True

Response format

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

Response example

{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": false,
  "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",
  "private boolean": "cash",
  "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 90 seconds for the payment. If there is no payment during this time, the POS system has to close 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:

Order creation:
orderStatus=OPEN, totalOriginal=100, total=100, paid=0, unconfirmed=0
Payment:
orderStatus=OPEN, totalOriginal=100, total=100, paid=100, unconfirmed=100
Order closure:
orderStatus=CLOSED, totalOriginal=100, total=100, paid=100, unconfirmed=0

If you close the order with amount=0, the payment will be cancelled:
orderStatus=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.

If after closing the order (the amount can be == 0, or either > 0) the order is used in the creation request (/orders), do make sure that the NEW merchantOrderId is specified. In case the old merchantOrderId is specified, there will be an error.

Endpoint

POST /orders/{id}/actions/close

Request format

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

Parameter	Parameter type	Type	Description	Required
`id`	path	string	Unique order ID in the SWiP system.	True
`amount`	body	double	Order closing amount.	True
`tags`	body	List<String>	If there is a tag, the rounding will be applied.	False

Request example

{  
   "amount":50.0
}

Response format

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

{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": false,
  "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": "CLOSED",
  "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
}

Rounding

Sends a request to round the total cost of the purchase.

If earlier there was a zero amount in the total amount of the order, the order was canceled, and the Customer received a refund of the amount paid. Now, if there is an amount for rounding in the total amount of the order, the "ROUNDED" tag is used. It should be noted that this approach only works for alternative payment (cash).

At the same time, the difference between TotalCloseAmount and the ROUNDED tag should not be more than one, since only pennies can be rounded.

Request example

public class ConfirmOrderRequest {
    private double amount;
    private List<String> tags;
}

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	Parameter type	Type	Description	Required
`amount`	body	double	Amount to be refunded to the user.	True
`merchantId`	path	string	Merchant ID in the SWiP system.	True
`merchantOrderId`	path	string	Order ID in the merchant's system.	True

Request example

{
  "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

{
    "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

Important: 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	Parameter type	Type	Description	Required
`amount`	body	double	Amount of the payment cancellation.	False
`merchantId`	path	string	Merchant ID in the SWiP system.	True
`merchantOrderId`	path	string	Order ID in the merchant's system.	True

Request example

{
  "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

{
    "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	Parameter type	Type	Description	Required
`id`	path	string	Unique order ID in the SWiP system.	True
`amount`	body	double	Amount which the POS transmits to cancellation.	False

Request example

{  
   "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

{
  "apiVersion": 3,
  "authorizationCode": "string",
  "cash": false,
  "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": "CLOSED",
  "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
}

Calculate Anonymous discount

Sends a request to calculate available discounts for all customers.

In the request body, you must pass the order data with purchases to get available discount amount for this order.

Endpoint

POST /loyalty-calculations

Request format

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

Parameter	Parameter type	Type	Description	Required
`merchantOrderId`	path	string	Unique order ID.	True
`purchases`	body	object	List of purchases.
`total`	body	double	Order total amount.	True

Request example

{
  "merchantOrderId": "130ceaab-cc06-4f7c-bc58-2e86d336d723",		// Merchant unique order identifier
  "purchases": [													// List of 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
    }
  ],
  "total": 50.50													// Total amount of order
}

Response format

The response to the request will contain the discount calculation result for the current order.

Response example

{
  "discountCalcResult": {
    "discountOriginal": 19.80,						    // Original discount amount
  "discount": 20.0,									    // Final discount after rounding
    "lines": [
      {
        "programId": 584,								// SWiP loyalty program ID
        "description": "Discount for all customers",	// Description of loyalty program
        "discount": 19.80								// Calculated discount amount
      }
    ]
  },
  "totalBeforeCalc": 50.0,								// Total order amount befor loyalty calculation
  "total": 30.0 										// Total order amount after applying available loyalty programs
}

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 authentfiication.
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 (the 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": 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
    }
  ]
}

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

SWiP POS API

Terms and definitions

Using the API

Integration schema

SWiP loyalty calculation and payment inside the SWiP app

HTTP protocol

SWiP loyalty calculation without payment inside the SWIP app

HTTP protocol

Integration URL

Order and session identification

Transport and protocol

Authentification

Integration scenarios

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

Vending machine

Order object

Purchases object

Create an order

Endpoint

Request format

Response format

Get an order

Endpoint

Request format

Response format

Order status options and how they change

Close an order

Endpoint

Request format

Response format

Rounding

Refund

Endpoint

Request format

Response format

Cancel a payment

Endpoint

Request format

Response format

Cancel an order

Endpoint

Request format

Response format

Calculate Anonymous discount

Endpoint

Request format

Response format

Response codes

Error codes and description

Error object