Methods

/api/v1/purchases/confirm/ - confirmation of the purchase

Method's Use

SailPlay has a mechanism in place that allows confirmation of bonus points received for purchases.

You can use it, for example, when the user is awarded bonus points for the purchase right after the order has been generated but later the user can cancel the order.

It is implemented the following way: the lifetime of "unconfirmed" bonus points is set up. After this date, if the payment has not been confirmed, bonus points will be written off automatically. In the period before the expiration date when the purchase has not been confirmed the user can not receive a gift.

Besides this, the method purchases/new has the mechanism of payment confirmation ( found here )

Attention

The request uses the parameter order_num - order / payment number (this is the number of the order in your system that has been included in the request for awarding of bonus points). Instead, you can use purchase_id - transaction ID in the SailPlay's system that returns in the response to the request for awarding of bonus points. If both parameters have been submitted, purchase_id has the priority ..

Request Parameters

Parameter required?	Parameter name	Parameter desciption
yes	token	See here
yes	store_department_id	See here
yes	order_num (or purchase_id)	Order number in your system (or transaction ID that returns in the response to the request for awarding of bonus points)
no	new_price	Current price (price after confirmation, if it was changed)
no	positions	Array of products in this purchase (cart's content). It has the format "positions = 1899,200: 101,379" - products IDs in your system and the cost are submitted in groups separated by colons. If there are several purchases with this product ID, you should submit this ID several times. Important: The amounts should be of type int.

Request Example

http://sailplay.net/api/v1/purchases/confirm/?store_department_id=1&token=b301f9928dda6499a74755491767208f3b156867&order_num=12344&new_price=12344&positions=1899,200:101,379

Server response

Identical to is It the server response the Received the when bonus points are Awarded See found here

/api/v1/purchases/delete/ - deleting of the purchase

Method's Use

It is used to delete the purchase and cancel bonus points awarded for the purchase.

Important

Let's assume that the user made a purchase and received 1,000 bonus points, and then received a gift for 100 bonus points. In this case, the request for the deleting of the purchase will return an error because after deleting the purchase the user will have a negative number of bonus points. To solve this problem you should first delete transaction related to the awarding of the gift.

Deleting tags

When you delete a purchase, the “Purchase” tag counter is decreased by 1. If a confirmed purchase is deleted, the tag “Purchase confirmation” is also decreased by 1. If either tag counter drops to 0, then that tag is deleted.

Request Parameters

The parameter is mandatory	Parameter name	Parameter desciption
yes	order_num or purchase_id	Order number, or transaction ID in the SailPlay's system (more detailed see 2.1)
yes	token	See here
yes	store_department_id	See here

Server Response

Parameter Name	Parameter Description
status
id	Unique ID for the deleted transaction
order_num	Deleted order number

Request Example

http://sailplay.ru/api/v1/purchases/delete/?store_department_id=32&token=0e96be0867401601df4c6e8691476bfaaa73f3&order_num=12345

Server Responses Examples

In case of success:

{


"Order_num": "12345" 


"Status": "ok", 


"Id": 9676


}

In case of failure (if the user does not have enough bonus poibts, ie if the gift has not been deleted previously):

{


  "Status": "error",


  "Status_code": -3001,


  "Message": "Impossible to delete purchase"


}

/api/v1/purchases/get/ - receiving information about the purchase

Method's Use

It is used to receive information about the purchase, its cost and awarded bonus points, as well as information about the client.

Request Parameters

The parameter is mandatory	Parameter name	Parameter desciption
yes	order_num	Order number
yes	token	See here
yes	store_department_id	See here

Server Response

Parameter Name	Parameter Description
status
purchase	object with the information about the purchase
is_completed	is the purchase confirmed?
store_department_id	purchase department id
completed_date	Confirmation date
order_num	ID Order
points_delta	awarded points amount
public_key	purchase confirmation key
user_id	internal user id in the SailPlay's system
purchase_date	purchase date
clerk_pin	Client PIN-code
price	Purchase amount
cart	cart description object

Request Example

http://sailplay.ru/api/v2/purchases/get/?store_department_id=435&token=b3c7ac443b9843bf4daa20f54292655b5f77bb4b&order_num=136

Server Responses Examples

In case of success:

{
    "Status": "ok",
    "Purchase": {
        "Is_completed": false,
        "Store_department_id": 435,
        "Completed_date": null,
        "Order_num": "42260"
        "Id": 11916548,
        "Points_delta": 25
        "Public_key": "7d46d2b7c74c418c9559621e85f97afcc1eddbe2",
        "User_id": 6556846,
        "Purchase_date": "2015-05-12T17: 49: 01"
        "Clerk_pin": "1231",
        "Price": 500
    }
    "Cart": {
        "Marketing_actions_applied": [
            {
                "Client_msg": "Success notification!",
                "Service_msg": "Possibility notification!",
                "Alias": "all"
            }
        ]
        "Possible_marketing_actions": [],
        "Cart": {
            "Total_points": 25
            "Positions": [
                {
                    "Category": {
                        "Sku": "default",
                        "Id": 707
                    }
                    "Product": {
                        "Sku": "ugly",
                        "Id": 485,226
                    }
                    "Num": "1",
                    "Points_rate": "0.05000",
                    "Price": "600.00",
                    "Quantity": "1.0000",
                    "New_price": "300.00",
                    "Points": 15
                }
                {
                    "Category": {
                        "Sku": "default",
                        "Id": 707
                    }
                    "Product": {
                        "Sku": "2"
                        "Id": 485,224
                    }
                    "Num": "2"
                    "Points_rate": "0.05000",
                    "Price": "400.00",
                    "Quantity": "1.0000",
                    "New_price": "200.00",
                    "Points": 10
                }
            ]
            "Positions_count": 2
            "Total_price": "500.00",
            "Id": 1547
        }
    }
}

/api/v1/purchases/new/ - creation of the purchase

Method's Use

Use this method to create a purchase in SailPlay. Logic related to the awarding of bonus points, badges and statuses will automatically run after this method invocation.

The process is as follows:

The user makes a purchase on your website.
HTTP (s) -request to SailPlay is sent from your server (website, POS-terminal, mobile app).

In response you will receive public_key that needs to be applied when displaying the next page in JS.

For cases when

you need to award different amount of points for certain products or product categories;
you need to separate users and receive analytics on the cart's content

we suggest using the mechanism of working with the cart.

It is working the following way: in the request for awarding / confirmation of bonus points the parameter positions is submitted. It has the following format:

postion_id_1, [category_id_1,] sum_1 [: ...: postion_id_N, [category_id_N,] sum_N]

where

The parameter is mandatory	Parameter Name	Parameter Description
yes	position_id	Product SKU in your catalog (it can include Latin characters and numbers)
yes	category_id	Category ID for this product in your catalog
yes	sum	Amount (the cost of this product)

As you see in the format, the category parameter is optional.

When processing the cart's content the following rules are applied:

If the product with this SKU or the group with this ID does not exist in SailPlay's database, they are created automatically.
If there is no special conversion rate for this product, it will be checked if there is a conversion rate for this category. If it does not exist, the default conversion rate is used.
If the same product is submitted in one array multiple times, the amounts are added first.

Request Parameters

Is the parameter mandatory?	Parameter Name	Parameter Description
yes	user_phone or email or origin_user_id	Client ID. Detailed.See More found here .
yes	token	See here
yes	store_department_id	See here
yes	pin_code	See here
yes	price	Total purchase amount in local currency.
no	fields	Additional fields that will be included in the JSON response. Additional fields are listed in comma-separated format, and they may take the following values: public_key, order_num. Example: & fields = public_key, order_num
no	points_rate	Conversion rate from rubles to points. It can take on a value from half-interval (0,1]. When this parameter is not specified, the value from settings is used. Format points_rate = 0.45
no	order_num	Your number in the Order system (IT USED is the when Mechanism with payment confirmation has Been Chosen. More detailed The see found here for more details)
no	force_complete	Checkbox. If this is checked (force_complete = 1), the transaction is considered confirmed despite the flag in settings. This attribute can be used, for example , when some payments have to be confirmed, and it is known that other payments have been confirmed already. See detailed The More found here
no	positions	Array of products in this purchase (cart 's content). It has the format "positions = 1899,13,200 : 101,10,379" - products IDs in your system, product groups ID (optional) and the cost are submitted in groups separated by colons. If there are several purchases with this product ID, you should submit this ID several times. It is used to award bonus points with different rates (ie if there is a need to award twice as many bonus points for products of a particular category). See detailed The More found here . Important: The amounts should be of type int.
no	user_category_name	User category. See found here

Server response

Parameter name	Parameter descvription
status
purchase	Transaction data
complete_date	Date and time of the completed transaction
price	Amount submitted in the request
id	Unique transaction ID
points_delta	Points awarded to the user for this purchase
user	Information about the user and his / her points
phone	The user's phone number in special format (if this information exists in the SailPlay's system)
full_name	The user's full name (if this information exists in the SailPlay's system)
email	Email address (if this information exists in the SailPlay's system)
public_key	It returns only if it was specified in the request in the parameter fields. Purchase transaction hash It is used in the popup's JS-code for the automated opening of the popup after the purchase.
order_num	It returns only if it was specified in the request in the parameter fields. Order number in your system.

Request Example

http://sailplay.ru/api/v1/purchases/new/?store_department_id=219&cart={"1 ": {" sku ":" 1 "," price ":" 100 "," quantity ": 3" discount_points ": 40}," 2 ": {" sku ":" 2 "," price ":" 100 "," quantity ": 3," discount_points ": 30}} & order_num = 327924 & pin_code = 1111 & origin_user_id = 25547 & token = 024e3bfbe50c8ef3d413caf19bf5380bbdd79df3 & attrs = { "processing_time": "249", "payment_type": "card"}

Server Response Example

{
    "Status": "ok",
    "Purchase": {
        "Complete_date": "2013-01-25T00: 31: 42,642,"
        "Price": "10"
        "Id": 8
        "Points_delta": 4
        "Public_key": "; ao08rj3tj09fu9jkwer20393urjflshg54h",
        "Order_num": 132,123
    }
    "User": {
        "Phone": "79000000000"
        "Points": 28,
        "Full_name": "Kirill Ivanovich Lavrov"
    }
    "Email": "sales@sailplay.ru"
}

/api/v2/purchases/confirm/ - confirmation of the purchase

Method's Use

The method is used to confirm purchases in SailPlay.

The difference from method /api/v1/purchases/confirm/ is the format of the cart's content transmsison - in version 2 this is a json-object like in /api/v2/purchases/new/.

Request Parameters

Parameter required?	Parameter name	Parameter desciption
yes	token	See here
yes	store_department_id	See here
yes	order_num (or purchase_id)	Order number in your system (or transaction ID that returns in the response to the request for awarding of bonus points)
no	new_price	Current price (price after confirmation, if it was changed)
no	cart	Json-object that includes information about the cart's content. For each position's object parameters sku - product ID, price - total cost of all products, products quantity are submitted.

/api/v2/purchases/new/ - adding a purchase

Method's Use

This method is needed to submit information about a new purchase to SailPlay's system.

In contrast to method /api/v1/purchases/new/, version 2 provides the calculation of promotions, and the cart contents becomes a mandatory parameter. Additionally, parameters that modify the amount of awarded points have been removed (this functionality has been moved to promotions section), and the cart's format has been slightly changed.

Request Parameters

Is the parameter mandatory	Parameter name	Parameter desciption
No	user_phone or email or origin_user_id	More detailed The ID the Client see found here
yes	token	See here
yes	store_department_id	See here
yes	pin_code	See here
yes	order_num	Order number in our system
yes	cart	Json-object that includes information about the cart's content. For each position's object parameters sku - product ID, price - total cost of all products, products quantity are submitted.
no	cart_id	Cart ID received at the stage of the preliminary calculation (method/api/v2/marketing-actions/calc/). If the cart_id is submitted, the cart's content (cart) does not have to be submitted.
no	force_complete	Checkbox. If this is checked (force_complete = 1), the transaction is considered confirmed despite the flag in settings. This attribute can be used, for example, when some payments have to be confirmed, and it is known that other payments have been confirmed already. More detailed http://docs.sailplay.ru/ru/page/api-back-purchases/">see here

Request Example

http://sailplay.ru/api/v2/purchases/new/?store_department_id=219&token=024e3bfbe50c8ef3d413caf1erwf5380bbdd79df3&order_num=171&cart={"1":{"sku":"1","price":1000, "quantity": 1 }, "2": { "sku": "2", "price": 300, "quantity": 3}} & origin_user_id = cart1 & pin_code = 104443

Server Response Example

{
    "Status": "ok",
    "Purchase": {
        "Is_completed": false,
        "Store_department_id": 219,
        "Completed_date": null,
        "Order_num": "171",
        "Id": 23141,
        "Points_delta": 410,
        "Public_key": "a45939f44e6c6783ad8d38562e083a6fda233e29",
        "User_id": 340774,
        "Purchase_date": "2015-06-02T15: 00: 16,129,"
        "Clerk_pin": "104443",
        "Price": "1200.00"
    }
    "Cart": {
        "Marketing_actions_applied": [
            {
                "Client_msg": "2"
                "Service_msg": "1",
                "Alias": "3"
            }
        ]
        "Possible_marketing_actions": [],
        "Cart": {
            "Total_points": 410,
            "Positions": [
                {
                    "Category": {
                        "Sku": "elphnt",
                        "Id": 271
                    }
                    "Product": {
                        "Sku": "1",
                        "Id": 203
                    }
                    "Num": 1,
                    "Marketing_actions": [],
                    "Price": "1000.00",
                    "New_price": "1000.00",
                    "Points": 400,
                    "Points_rate": "0.4000",
                    "Quantity": "1"
                }
                {
                    "Category": {
                        "Sku": "default",
                        "Id": 196
                    }
                    "Product": {
                        "Sku": "2"
                        "Id": 205
                    }
                    "Num": 2,
                    "Marketing_actions": [
                        "3"
                    ]
                    "Price": "300.00",
                    "New_price": "200.00",
                    "Points": 10,
                    "Points_rate": "0.0500",
                    "Quantity": "3"
                }
            ]
            "Positions_count": 2
            "Total_price": "1200.00",
            "Id": 1097
        }
    }
}

Cart Formatting Guide:

The cart should be a JSON object of this form:

{

"1": {

"sku": "sku1",

"quantity": 1,

"price": 50

"2": {

"sku": "sku2",

"quantity": 2,

"price": 23.42

"3": {

"sku": "sku3",

"quantity": 3,

"price": 19.2,

"attribute1": "value1",

"attribute2": "value2"

}

Each item is indexed, and contains an sku, quantity, and price field. Optionally, individual items can have attributes and values applied.