How-to make a purchase
Introduction
In this guide, we are going to see the process behind a customer purchase and the API calls involved. When a customer makes a purchase, there are different resources of the API used:
oauth: An access token is required to get the info of the customercustomer: We will need information about the customer making the purchaseproduct: The customer will get info about one or more products to purchase them.cart: The customer will store products in a cart before making an order.order: The confirmation of the purchase by the client.payment: This is the API that will process the payment of the order. For security reasons is in an isolated server
This are the steps needed to make an order:
- Get and access_token for the customer
- Get info about the products that the customer wants to buy
- Create a cart with the products
- Create the order
- Process the payment using the specif Payment API
Getting an access token
In the previous guide, we have seen how to get an access_token to use the API as a merchant. In this case we are going to use the API as a customer. In any case, the process is the same as the one described in the "Getting Started" section, but instead of using the credentials given by Scalefast, we will need to provide the customer's credentials.
To get the access_token we will make the following request:
curl -X POST 'https://sandbox-api.scalefast.ninja/oauth/access_token'
-H 'accept: application/json'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'request_data=%7B%22clientID%22%3A%20%22%7BclientID%7D%22%2C%22grant_type%22%3A%20%22password%22%2C%22userID%22%3A%20%22%7BuserID%7D%22%2C%22user_credential%22%3A%20%22%7BuserPassword%7D%22%2C%22rand%22%3A%20%22%7Brandom_string%7D%22%7D'
Which will give a response like this one:
{
'result': {
'status': 'OK',
'errcode': 0,
'msg': ''
},
'response_data': {
'access_token': '{acces_token}',
'expires_in': 14400,
'scope': '{List of scopes for the user}'
}
}
This is the most basic way to sign-in as a user. You can check more advanced options, like using the Scalefast CAPTCHA system, "here"
Customer info
With the access token, we can get information about the customer. Some of the personal info of the customer is needed to create a cart, and we can check if the customer has already some shipping and billing addresses defined. To get this information, we must do a request like this:
curl -X GET 'https://sandbox-api.scalefast.ninja/user/me?access_token={access_token}' -H 'accept: application/json'
Which will give a response like this one:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"userID": "1",
"state": "VALIDATED",
"type": "individual",
"email": "[email protected]",
"username": "username",
"preferred_language": "EN",
"subscribe_newsletter": "false",
"subscribe_promotion": "false",
"last_connection_date": "0000-00-00 00:00:00",
"provider": [""],
"creation_date": "2017-11-29 10:11:06",
"refID": "2147483647",
"info": {
"address": "address",
"zipcode": "28016",
"city": "city",
"state": "",
"country": "ES",
"address2": "",
"phone": "1234565487",
"fax": "",
"birthday": "1984-11-18",
"mobile_phone": "",
"title": "Mr",
"firstname": "name",
"lastname": "lastname"
},
"ip": "192.168.56.1",
"shipping_info": {
"type": "individual",
"address": "shipping address",
"zipcode": "28016",
"city": "city",
"country": "ES",
"phone": "1234565487",
"birthday": "0000-00-00",
"title": "Mr",
"firstname": "name",
"lastname": "lastname"
},
"badges": [{
...
}],
"subscriptions_productIDs": [],
"points": "50",
"member_since": "2017-11-29 10:11:06",
"affiliation_track_id": null,
"territory": "ROW"
}
}
Some of this information can be used in the cart creation, like billing and shipping address infos, points, etc.
If we only want to get information about the addresses of the customer (billing and shipping), we can use this endpoint:
GET /customer/{customerID}/addresses
Check the reference to see how to use this request
Get products
Using the API, we can get information about the products. This is mandatory in order to add them to the cart. The request to get products accepts different parameters to filter the products. There is only one parameter that is required (note that in this case no access token is needed because products is public):
clientID: Application ID provided by Scalefast.
So the most basic request to get products looks like this:
curl -X GET "https://api.scalefast.com/products?clientID=B1FDB1F9A4C576D69CF49BA8ED5D0ADC" -H "accept: application/json"
This request accepts more parameters that can be used to filter the products. A detailed explanaition of these parameters can be found in the API reference
The response to the GET products request gives us a list or products, each one containing the required data to add it to the cart. This is example of the response:
{
'result': {
'status': 'OK',
'errcode': '0',
'msg': '',
'client_rand': 'r+pTwkjToWFCZ18WVTeiWxo9l04\/jz54O3UpNSyDwFHs8QfSddQ9qgRhWUlV7KMtv9YG3ETeDFzQmpB\/1HvR4w=='
},
'response_data': {
'count': '{nomber of products that have been retrieved}',
'objects': [{
'productID': '1',
'state': 'VALIDATED',
'creation_date': '2018-11-15 20:27:34',
'type': 'SOFT',
'refID': '00001',
'ean': '',
'upc': '00001',
'isbn': '',
'jan': '',
'country': 'ROW',
'geoID': '',
'specific': {
},
'price_info': {
},
'descriptions': [{
}],
'image': '',
'categories': [{
}],
'stock': {
'stock': 'STOCK_TYPE',
'current_stock': '499',
'policy': 'SHOW',
'low_stock_alert': '50'
},
'note': '0',
'totalSalesValidated': '1'
}]
}
}
You can check all the fields of the response in the API reference
The client application can get information of as many products as it needs with different calls, but to create a cart if needs to specify all the products that are going to be added to the cart at the same time, so it is the duty of the client application to keep the info of the products that the customer is interested in.
Create the cart
Once the customer has finished choosing products and proceeds to the checkout, the cart object is created. The cart will hold the information of the customer, of the products, and can be updated if once the customer provides shipping and billing information. With this information the cart will show the customer the available shipping options and costs, and it will also calculate the taxes for the different products showing the customer the total cost of the order before confirming the order.
To create (an later update) the cart we are going to use this endpoint:
POST cart
This are the basic fields that are most likely to be used in the first request. All the available fields can be seen in the API reference
| Field | Description |
|---|---|
| userID | Internal user identifier of the merchant (provided by Scalefast) |
| flashID | Internal identifier for the territory of the project (provided by Scalefast) |
| currency | Main currency that will be used in the purchase (ISO code) |
| cart | Array of the products that the customer wants to purchase |
| shipping | Delivery information |
| invoicing | Billing address information |
This is the structure of a product element inside cart:
| Field | Description |
|---|---|
| productID | Internal identifier of the product |
| quantity | Quantity added to cart |
| license | Internal license of the product |
| price | Expected price of the product |
| currency | Currency of the product (ISO code) |
This is the structure of the invoicing field:
| Field | Description |
|---|---|
| country | Country of the customer in ISO code format |
| type | Address type(individual, company, pro or particular) |
| state | State, province or region of the customer |
| zipcode | Zip code of the customer |
| city | City of the customer |
| address | Address (street and number) of the customer |
| address2 | Address (apartment, suite, unit, building, floor, etc) of the customer |
The shipping field consist of an array called methods that holds information about the different methods available in the purchase. Each of the elements of that array has this structure:
| Field | Description |
|---|---|
| sellerID | The client ID from which this shipment is sent |
| products | List of productIDs in this shipment |
| shipment | State, province or region of the customer |
| shippingID | Delivery method internal identifier |
| availableDate | Date when order has shipped |
We can see in the response how the cart has already calculated the taxes for the product:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"userID": "2072312",
"flashID": "1",
"voucher": "*",
"region": "ROW",
"region_check": false,
"currency": "USD",
"lang": "EN",
"cart": [{
"productID": "425297",
"quantity": "1",
"license": "5",
"price": "59.95",
"currency": "USD"
}, {
"productID": "402183",
"quantity": "1",
"license": "5",
"price": "59.95",
"currency": "USD"
}, {
"productID": "425272",
"quantity": "1",
"license": "5",
"price": "59.95",
"currency": "USD"
}],
"save": false,
"entity": "pepitainc",
"customerID": "5889521",
"shipping": {
"general": {
"sellers": [{
"sellerID": 2072312
}],
"total": 0
},
"sellers": [{
"sellerID": "2072312",
"methods": [{
"shipment": 0,
"shippingID": "UPS_Surepost",
"amount": 0,
"title": "Super Saver (5 to 10 days *)",
"text": "UPS Surepost",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}, {
"shipment": 0,
"shippingID": "UPS_Ground",
"amount": 12.99,
"title": "Standard (3 to 7 days)",
"text": "UPS Ground",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}, {
"shipment": 0,
"shippingID": "USPS_PriorityMail",
"amount": 8.99,
"title": "Priority (2 to 5 days *)",
"text": "USPS Priority Mail",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}, {
"shipment": 0,
"shippingID": "USPS_PriorityMailIntl",
"amount": 43.99,
"title": "Priority (2 to 5 days *)",
"text": "USPS Priority Mail Intl",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}, {
"shipment": 0,
"shippingID": "UPS_2day",
"amount": 16.99,
"title": "2 day",
"text": "UPS 2 day",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}, {
"shipment": 0,
"shippingID": "UPS_NextDayAirSaver",
"amount": 28.99,
"title": "Overnight (next day PM)",
"text": "UPS NextDayAirSaver",
"options": [],
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"is_selected": false
}]
}]
},
"invoicing": {
"22311": {
"products": {
"7": [{
"productID": "425297",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "19.95",
"originalPriceWithoutVat": "19.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "29.95",
"vat_percent": 7,
"vat": 1.4,
"priceWithVat": 21.35,
"originalPriceWithVat": 21.35,
"rePriceWithVat": 32.05,
"crossedPriceWithVat": 0
}, {
"productID": "402183",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "19.95",
"originalPriceWithoutVat": "19.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "19.95",
"vat_percent": 7,
"vat": 1.4,
"priceWithVat": 21.35,
"originalPriceWithVat": 21.35,
"rePriceWithVat": 21.35,
"crossedPriceWithVat": 0
}, {
"productID": "425272",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "29.95",
"originalPriceWithoutVat": "29.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "29.95",
"vat_percent": 7,
"vat": 2.1,
"priceWithVat": 32.05,
"originalPriceWithVat": 32.05,
"rePriceWithVat": 32.05,
"crossedPriceWithVat": 0
}]
},
"infos": {
"name": "Scalefast Inc",
"address": "2415 third street, suite 231",
"initials": "CA",
"initials_country": "USA",
"cp": "94107",
"city": "California",
"country": "US",
"rcs": "- authorized seller of the products - a Delaware corporation registered at<br>",
"signatureCity": "San Francisco",
"signatureName": "",
"signatureCharge": "CEO"
}
}
},
"output": "discount,loyalty,shipping,summary",
"discount": {
"products": [{
"productID": "425297",
"license": "5",
"quantity": 1,
"extension": null
}, {
"productID": "402183",
"license": "5",
"quantity": 1,
"extension": null
}, {
"productID": "425272",
"license": "5",
"quantity": 1,
"extension": null
}],
"executed_rules": {
"274": {
"364": 7.99
}
}
},
"customer": {
"currency": "13",
"points": 110,
"spent_points": 0,
"rules": {
"428": {
"538": [{
"type": "on_product",
"products": {
"425297": {
"points": 60
},
"402183": {
"points": 20
},
"425272": {
"points": 30
}
},
"points": 110
}]
}
}
},
"vat": {
"products": {
"7": [{
"productID": "425297",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "19.95",
"originalPriceWithoutVat": "19.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "29.95",
"vat_percent": 7,
"vat": 1.4,
"priceWithVat": 21.35,
"originalPriceWithVat": 21.35,
"rePriceWithVat": 32.05,
"crossedPriceWithVat": 0
}, {
"productID": "402183",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "19.95",
"originalPriceWithoutVat": "19.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "19.95",
"vat_percent": 7,
"vat": 1.4,
"priceWithVat": 21.35,
"originalPriceWithVat": 21.35,
"rePriceWithVat": 21.35,
"crossedPriceWithVat": 0
}, {
"productID": "425272",
"quantity": 1,
"isDigital": "0",
"tax_type": null,
"priceWithoutVat": "29.95",
"originalPriceWithoutVat": "29.95",
"crossedPriceWithoutVat": "0",
"rePriceWithoutVat": "29.95",
"vat_percent": 7,
"vat": 2.1,
"priceWithVat": 32.05,
"originalPriceWithVat": 32.05,
"rePriceWithVat": 32.05,
"crossedPriceWithVat": 0
}]
},
"total": {
"7": {
"nbProducts": 3,
"vat": 4.9,
"totalPriceWithVat": 74.75,
"totalPriceWithoutVat": 69.85
}
}
},
"summary": {
"ncart": "425297:5::1:::19.95:::-1:;402183:5::1:::19.95:::-1:;425272:5::1:::29.95:::-1:;0:::::0",
"ncart_price": "425297:5::1::19.95::-1:;402183:5::1::19.95::-1:;425272:5::1::29.95::-1:;0:::::7.99",
"totalPriceWithVat": 74.75,
"totalPriceWithoutVat": 69.85,
"totalVat": 4.9,
"nbProducts": 3,
"price_type": "1",
"totalShippingPriceWithoutVat": 0,
"totalShippingPriceWithVat": 0,
"totalShippingPercent": 7,
"totalShippingVat": 0
}
}
}
Create the order
When the cart has all the required data, the consumer can place an order. We will use this endpoint for that.
POST https://sandbox-api.scalefast.ninja/orders
And this is an example of the body for the request:
{
"currency": "USD",
"email": "[email protected]",
"lang": "EN",
"custom": "",
"type": "pepita",
"billing": {
"action": "preop"
},
"flashID": "1",
"trackID": "0",
"country": "ROW",
"url": "https://store.scalefast.com/cart",
"amount": 113.84,
"voucher": null,
"cart": [{
"productID": "425297",
"license": 5,
"quantity": 1,
"currency": "USD"
}, {
"productID": "402183",
"license": 5,
"quantity": 1,
"currency": "USD"
}, {
"productID": "425272",
"license": 5,
"quantity": 1,
"currency": "USD"
}],
"entity": "pepitainc",
"shipping": {
"amount": 43.99,
"methods": [{
"shippingID": "USPS_PriorityMailIntl",
"sellerID": 2072312,
"identifierID": null,
"shipment": 0,
"products": [{
"productID": "425297"
}, {
"productID": "402183"
}, {
"productID": "425272"
}],
"options": {}
}],
"infos": {
"title": "Mr",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]",
"address": "C/Mendez Alvaro 9",
"zipcode": "28045",
"city": "Madrid",
"state": "",
"country": "ES",
"birthday": "0000-00-00"
},
"options": {
"split": true,
"split_per_preorder": true
}
},
"analytics": {
"accountID": "UA-446189-15,UA-118283914-3",
"clientID": "494606587.1534158466",
"air360ID": "vvsklkzg4bl3wg7i"
},
"invoicing": {
"title": "Mr",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]",
"address": "C/Mendez Alvaro 9",
"zipcode": "28045",
"city": "Madrid",
"state": "",
"country": "ES"
},
"profiling": {
"keyID": 11055439143195,
"infoID": "1"
}
}
Response:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"orderID": "19489281",
"token": "b6e18bb6a5535ad03b6c7843e75ca16b34bcf69d1f33e8ec5f49183f171062b4",
"email": "[email protected]",
"payment_infos": {
"type": "authorization"
}
}
}
Order payment
For security reasons, the payment of the order is handled by another API. So once the order has been created, another call before the purchase process is finished. This request is made to another server:
POST https://pepayment.pepitastore.com
{
"uniqueID": "19489281",
"currency": "USD",
"flashID": "1",
"country": "ROW",
"userID": 2072312,
"amount": 113.84,
"shipping_total": 43.99,
"discount_total": 0,
"tax_total": 0,
"lang": "EN",
"entity": "pepitainc",
"token": "b6e18bb6a5535ad03b6c7843e75ca16b34bcf69d1f33e8ec5f49183f171062b4",
"voucher": null,
"shippingIDs": "USPS_PriorityMailIntl",
"mode": "sandbox",
"cashrun_session_id": "fjetlifba6m",
"cashrun_site_id": "a2556d26qa04fcjn40bbaa82d030f289osf6e233",
"billing": {
"cardType": "visa",
"cb": "{card_number}",
"crypto": "{card_crypto_code}",
"date": "{card_date}"
},
"cart": [{
"productID": "425297",
"refID": "WS12074",
"quantity": 1,
"price": 19.95,
"title": "Digimon World: Next Order (PlayStation 4)",
"type": "Physical"
}, {
"productID": "402183",
"refID": "WS12070",
"quantity": 1,
"price": 19.95,
"title": "Tales of Berseria (Playstation 4)",
"type": "Physical"
}, {
"productID": "425272",
"refID": "WS22027",
"quantity": 1,
"price": 29.95,
"title": "Dragon Ball Xenoverse 2 (Xbox One)",
"type": "Physical"
}],
"isSubscription": "NO",
"domain": "https://store.scalefast.com/cart"
}
Response:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"uniqueID": "19489281",
"status": "AUTHORIZED",
"code_status": "0",
"amount": 11384,
"currency": "USD",
"type": "adyen",
"fraud_status": "ACCEPT",
"paymentID": "1",
"infos[hashCB]": "68bfb396f35af3876fc509665b3dc23a0930aab1",
"infos[cardEnding]": "{cardEnding}",
"infos[bin]": "{bin}",
"infos[cardType]": "{visa}",
"errcode": "0"
}
}
Updated almost 6 years ago