Versions Compared

Old Version 48

changes.mady.by.user Liliya Vorontsova

Saved on

compared with

New Version 49

changes.mady.by.user RA

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

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

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

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

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

  3. The user confirms the payment.

  4. The 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 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.

  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.

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

Code Block
languagejson
{
  "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

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

Code Block
languagejson
{
  "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

Code Block
languagejson
{
  "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:

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

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

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

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

Code Block
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

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

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

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

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

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

Code Block
languagejson
{
  "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

Code Block
languagejson
{
  "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 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