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 life time 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 the, the method purchases / new has the Mechanism of payment confirmation (see 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 poibts, 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 purchases 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

  1. you need to award different amount of points for certain products or product categories;
  2. 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:

  1. If the product with this SKU or the group with this ID does not exist in SailPlay's data base, they are created automatically.

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

  3. 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": "79060054602"
        "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 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.