/
API SWiP Wallet P-o-S

API SWiP Wallet P-o-S

Terms and definitions

SWiP Wallet - a SWiP product that provides by mobile SWiP aaps on following platforms: Apple, Google, Huawei.

P-o-S (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 P-o-S / merchant / third-party who connects the merchant's P-o-S 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

P-o-S API - a programming interface for:

  • culculating discounts by SWiP Loyalty

  • 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 P-o-S system creates an order.

Step 2. The P-o-S 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 P-o-S system sends a request to get the information about the current order status.

Step 10. The P-o-S system receives the paid order with applied loyalty.

Step 11. The P-o-S 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 P-o-S system creates an order.

Step 2. The P-o-S 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 P-o-S system sends a request to get the information about the current order status.

Step 7. The P-o-S system receives unpaid order with applied loyalty.

Step 8. The P-o-S accepts payment by cash or card in bank terminal.

Step 9. The P-o-S 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

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

Field name

Description

sessionCode

The session identifier (the text value encrypted in the QR code). If the P-o-S 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

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

P-o-S 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 P-o-S system.

  2. The P-o-S 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 P-o-S 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 P-o-S is not using yet. They should be ignored.

*- the fields that are filled in by the P-o-S 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

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

P-o-S 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,

  • LOYALTY_CALCULATION,

  • LOYALTY_CALCULATED

  • 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

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

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