Table of Contents

minLevel	1
maxLevel	7
outline	true
absoluteUrl	true

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.

Numberedheadings

number-format	decimal
skip-headings
start-numbering-with
h1
h2
h3
h4
h5
enabled	true
h6
start-numbering-at	H1

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.

1008716310114033181paymentbycash33https://swipsw.atlassian.net/wikiДиаграмма без названия-1670504786808.drawio0591471

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.

1008716310109445721paymentbycash33https://swipsw.atlassian.net/wikipaymentbycash0431472

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.

* This document is valid for API version 2 and higher.

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:

The user makes an order at the POS system.
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.
The user confirms the payment.
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 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.
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

json

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

json

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

json

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

json

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:

Order creation:
status=OPEN, totalOriginal=100, total=100, paid=0, unconfirmed=0
Payment:
status=OPEN, totalOriginal=100, total=100, paid=100, unconfirmed=100
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

json

Response format

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

json

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

json

Response format

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

Response example

json

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

json

Response format

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

Response example

json

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

json

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

json

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

json

Version	Old Version 6	New Version 7
Changes made by	Support team (Unlicensed)	Support team (Unlicensed)
Saved on	Dec 13, 2022	Dec 13, 2022

Page Comparison

Versions Compared

Key

Terms and definitions

Using the API

Intergration schema

SWiP loyalty calculation and payment inside SWiP app

HTTP protocol

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

HTTP protocol

Integration URL

Order and session identification

Transport and protocol

Authentication

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

Refund

Endpoint

Request format

Response format

Cancel a payment

Endpoint

Request format

Response format

Cancel an order

Endpoint

Request format

Response format

Response codes

Error codes and description

Error object