| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
...
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
...
...
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
...
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
...
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
...
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=0Payment:
status=OPEN, totalOriginal=100, total=100, paid=100, unconfirmed=100Order 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
...
Response format
The response to the request will contain the Order object with the current status.
...
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
...
Response format
The response to the request will contain the refund status and its description.
Response example
...
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
...
Response format
The response to the request will contain the payment cancellation status and its description.
Response example
...
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
...
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
...
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.