Introduction
This is Toman's Escrow Service API Reference (Draft).
How does it work?
Toman's Escrow Service, allows you to open and close deals safely. To use Toman's Escrow Service, you (seller) need to create deals using our API, and redirect your buyers to our services using the trace number we've provided you with upon creation of deal.
Afterwards, buyers will interact with our dashboard and pay/followup their deals. Your wallet will be charged if the deal ends successfully and you will be able to withdraw the amount from your own dashboard on our website.
We also provide you with many callbacks on your deals updates. For example, we will call your API's back if a deal gets accepted or paid by the buyer. You need to provide us with your callback url upon creating your shop in your dashboard.
Your role and interaction as a seller with Toman's Escrow Service is very important in system's flow.
Here are some of your duties to have a sweat deal:
* Beside the deal's items, your lead time prediction for your deals is very important in Toman's Escrow Service, and also for buyer.
* After buyer's payment, it would be very nice to check the deal's items personaly and decide to prceed or reject it by calling Toman's Escrow Service APIs.
* If your decision is to proceed the deal, you should submit your shipment's information (or any details that can help your buyer to receive the deal's consignment) in Toman's Escrow Service, otherwise the deal will be expired after a certain period of time.
Authentication
Toman Escrow Service uses Basic HTTP authentication to authorize requests. In this doc, we will explain the usage of this method.
Basic Steps
After signing up and creating your Shop on the Toman Escrow Service website and be activated by our CRM, you will be provided with two secret
identifiers. One is your shop_slug(شناسه فروشگاه) and the other is your shop's authentication_code (کد فعالسازی).
These two identifiers will be used to authorize your requests to our servers.
Please note that these identifiers are unique per shop and you need to obtain
a new pair for your other shops in the future.
Example:
shop_slug = 1jmo0edqag153
authentication_code = !7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92
How to authorize my requests
As mentioned above, Toman uses Basic HTTP authentication. To set the authentication header you need to:
1) Concat the shop_slug and authentication_code, separated by a colon.
1jmo0edqag153:!7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92
2) Encode the result string using Base64 encoding.
echo -n 1jmo0edqag153:!7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92 | base64
MWptbzBlZHFhZzE1MzohN3MyNTlTOW5QZXRJVUlheW80NWx1b1ZKQXZYY044dTVoV3BuUUs5Mgo==
3) Put the value in your request's HTTP headers with the prefix Basic:
POST /some/path/ HTTP/1.1
Authorization: Basic MWptbzBlZHFhZzE1MzohN3MyNTlTOW5QZXRJVUlheW80NWx1b1ZKQXZYY044dTVoV3BuUUs5Mgo==
my=data
Sample Code
import base64
shop_slug = "1jmo0edqag153"
authentication_code = "!7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92"
shop_auth_token = base64.b64encode(bytes(f"{shop_slug}:{authentication_code}", "ascii")).decode("ascii")
export shop_slug='1jmo0edqag153'
export authentication_code = "!7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92"
export shop_auth_token=$(echo -n $shop_slug:$authentication_code= | base64)
<?php
$shop_slug = "1jmo0edqag153";
$auth = "7s259S9nPetIUIayo45luoVJAvXcN8u5hWpnQK92";
$shop_auth_token = base64_encode(sprintf("%s:%s", $shop_slug, $auth));
?>
Models
Deal
The entity representing the deal between the customer and the shop.
| Parameter | Type | Description | Example |
|---|---|---|---|
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created. | "15827367396329749332" |
| res_number | String | The identifier of this deal, assigned by the shop when creating the deal. Note that the uniqueness of this field's value is not guaranteed. | "1234567" |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that. | "15 00:00:00" |
| items | List[Item] | A collection of items in the deal. | [{"name": "گل", "price": 15, "quantity": 2},{"name": "کاج", "price": 1, "quantity": 2}] |
| state | String | The state of the deal. | "failed" |
| sub_state | String | More details about the current status of the deal in the current state. | "seller_shipment_expired" |
| payable_amount | Integer | The amount should be paid for this deal in IRR. | 100000 |
| return_to | String | The shop's requested callback API after buyer funds the deal. | "https://your_domain.smth/your_callback" |
| items_count | Integer | The number of items in this deal. | 3 |
| shipment | Shipment | The shipment details of this deal. | 3 |
Item
The entity representing the items of a deal.
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | A unique string which identifies the item. This field is generated by Toman when the deal is created. | "15827367396329749332" |
| quantity | Integer | The number of items of this type included in the deal. | 2 |
| name | String | This name of the item. | "Samsung Galaxy Note 11 Plus" |
| price | Integer | The price of this item in IRR. | 2000000 |
Deal State
This model represents the state of the deal.
| Id | Name | Description |
|---|---|---|
| 1 | Created | The deal is created. |
| 2 | Funded | The deal is paid by the user. |
| 3 | Success | This deal has been ended successfully by user receiving the items on itme without any complaints. |
| 4 | Failed | The deal has been ended unsuccessfully. |
| 5 | Jury | The user has submitted a complaint about the items they've received and is waiting for the decision by CRM team. |
Deal Sub-State
This model represents the status of the deal in its current state.
| Id | Name | Description |
|---|---|---|
| 1 | Init | The deal has been created and is waiting for user's to accept or make a payment. |
| 2 | Expired | The deal has not been accepted or paid by the user, and is expired. |
| 3 | BuyerCanceled | This user has cancelled the deal. |
| 4 | BuyerAccepted | The user has accepted the deal. |
| 5 | SellerRejected | The shop has cancelled the deal, usually due to shortage of the items. |
| 6 | SellerShipmentExpired | The shop has not acquired the deal with the shipment detail and the deal is assumed to be expired due to not shipping the items. |
| 7 | Sent | The shop has sent the items to the user and has filled the shipment details in the deal. |
| 8 | LeadTimeExhausted | The items are expected to have been delivered to the user, and the deal is waiting for the user's action to verify or reject the items wellness. |
| 9 | AutoAccepted | The items are expected have been delivered to the user, and user has not rejected the receipt of the items nor filed a complaint about the items. The deal is assumed to be accepted by the user. |
| 10 | Overruled | The user has filed a complaint about the deal, and the CRM team has decided that the seller is right, marking the deal as successful. |
| 11 | Sustained | The user has filed a complaint about the deal, and the CRM team has decided that the buyer is right, marking the deal as failed. |
Deal Shipment
This model represents the shipment details of a deal.
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | The type of shipment chosen by the shop. | "snapp_box" |
| inquiry_code | String | The inquiry code of the shipment in the postal service the shop has used. | "7346856395" |
| description | String | The description of the shipment written by the shop | ".پیک در مقصد برای تحویل بسته تماس خواهدگرفت" |
Deal Shipment Types
This model represents the types of shipment shops can use.
| Id | Name |
|---|---|
| 1 | post |
| 2 | tipox |
| 3 | snapp_box |
| 4 | miare |
| 5 | other |
Endpoints
Base URL
The base URL for our productions API servers is:
| Environment | URL |
|---|---|
| Production | https://api.tomanpay.net/escrow/api/v1 |
Note: Please pay attention to trailing slash at the end of the urls for all endpoints.
Create Deal
Creates a new Deal.
Sample Code
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals"
payload = json.dumps(
{
"res_number": "12345",
"return_to":"https://your_domain.smth/your_callback",
"lead_time": "3 00:00:00",
"items": [
{
"quantity": 3,
"name": "میز",
"price": 3000
}
]
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("POST", url, headers=headers, json=payload)
curl -X POST $base_url/users/me/shops/3h4sex41fbtgn/deals -v \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token " \
--data-raw '{"res_number":"12345", "return_to":"https://your_domain.smth/your_callback","lead_time":"3 00:00:00", "items": [{"quantity": 3, "name": "میز", "price": 10000}]}'
<?php
$url = sprintf("%s/users/me/shops/%s/deals", $base_url, $shop_slug);
$payload = json_encode(
array(
"res_number" => "12345",
"return_to" => "https://your_domain.smth/your_callback",
"lead_time" => "3 00:00:00",
"items" => array(
array(
"quantity" => 3,
"name" => "میز",
"price" => 3000
)
)
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
POST /users/me/shops/<shop_slug>/deals
Request Body
| Parameter | Type | Description | Example |
|---|---|---|---|
| res_number | String | The identifier of this deal, assigned by the shop when creating the deal. Note that the uniqueness of this field's value is not guaranteed. | "1234567" |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that. | "15 00:00:00" |
| return_to | String | The shop's requested callback API after buyer funds the deal. | "https://your_domain.smth/your_callback" |
| items | List[Item] | A collection of items in the deal. | [{"name": "گل", "price": 15, "quantity": 2},{"name": "کاج", "price": 1, "quantity": 2}] |
Response Body
| Parameter | Type | Description | Example |
|---|---|---|---|
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created. | "15827367396329749332" |
| res_number | String | The identifier of this deal, assigned by the shop when creating the deal. Note that the uniqueness of this field's value is not guaranteed. | "1234567" |
Request Data Example
{
"res_number": "12345",
"lead_time": "3 00:00:00",
"items": [
{
"quantity": 3,
"name": "میز",
"price": 3000
}
]
}
Response Data Example
{
"trace_number": "7456632113438322882",
"res_number": "12345"
}
Get Deal
Get details of a Deal.
Sample Code
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}"
headers = {
"Authorization": f"Basic {auth_token}",
"Content-Type": "application/json",
}
response = requests.request("GET", url, headers=headers)
curl --location '$base_url/api/v1/users/me/shops/3h4sex41fbtgn/deals/15827367386329749332' \
--header 'Authorization: Basic $auth_token'
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
GET /users/me/shops/<shop_slug>/deals/<trace_number>
Response Body
| Parameter | Type | Description | Example |
|---|---|---|---|
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created. | "15827367396329749332" |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that. | "15 00:00:00" |
| items | List[Item] | A collection of items in the deal. | [{"name": "گل", "price": 15, "quantity": 2},{"name": "کاج", "price": 1, "quantity": 2}] |
| state | String | The state of the deal. | "failed" |
| sub_state | String | More details about the current status of the deal in the current state. | "seller_shipment_expired" |
| payable_amount | Integer | The amount should be paid for this deal in IRR. | 100000 |
| items_count | Integer | The number of items in this deal. | 3 |
| shipment | Shipment | The shipment details of this deal. | 3 |
Response Data Example
{
"trace_number": "14257385787090628216",
"state": "created",
"sub_state": "init",
"buyer": null,
"buyer_mobile_number": null,
"payable_amount": 21000,
"lead_time": "15 00:00:00",
"delivery_eta": null,
"items": [
{
"name": "گل مصنوعی",
"quantity": 1,
"price": 21000
}
],
"shipment": null,
"complaints": [],
"created_at": "2023-09-18T12:42:42.631340Z",
"payer_accepted_at": null,
"funded_at": null,
"sent_at": null,
"failed_at": null,
"suspended_at": null,
"succeed_at": null
}
Redirect To Toman
After creating deal, you need to redirect your buyer to our services.
GET /deals/<trace_number>/redirect
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created. | "15827367396329749332" |
Response Body
empty
Request Data Example
GET /deals/<trace_number>/redirect HTTP/2
Host: escrow-api.toman.ir
Referer: your_domain.smth
Authorization: Basic MWptbzBlZHFhZzE1MzohN3MyNTlTOW5QZXRJVUlheW80NWx1b1ZKQXZYY044dTVoV3BuUUs5Mgo==
Response Data Example
empty
Shop Payment Callback
After user redirection to Toman's Escrow Service and funding the deal by him/her, we redirect buyer to your requested API(return_to) and feed it with transaction information as form-data.
curl -X POST --location 'https://your_domain.smth/your_callback' \
-H 'Authorization: Basic $shop_auth_code' \
--form 'trace_number="<deal_trace_number>"' \
--form 'state="<deal_state>"' \
--form 'sub_state="<deal_sub_state>"' \
--form 'payable_amount="<deal_paid_amount>"' \
--form 'res_number="<deal_reserved_number>"'
Deal Verification
After the return of the user to the shop's website, the seller must verify the deal payment and call this endpoint to inform Toman's escrow service that they have received the new state of the deal.
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Workflow
Deal States:
Each Deal entity has a State and Sub-State attribute which combination of them represents the current deal's status.
| State | Sub_State | Description |
|---|---|---|
| created | init | When the deal is created by the shop. |
| created | buyer_accepted | When the deal is accepted by the buyer after creation. |
| failed | buyer_rejected | When the deal is rejected by the buyer after creation. |
| failed | expired | When no actions has been taken on the deal by the buyer after creation. |
| funded | new | When buyer funds the deal, which has been accepted by himself/herself previously. |
| funded | init | When the seller's shop verifies the funded deal by buyer. |
| failed | seller_rejected | When the deal is rejected by the seller after the buyer's payment. |
| failed | seller_shipment_expired | When no actions have been taken on the deal by the seller after the buyer's payment |
| funded | sent | When the seller submits the deal's shipment information. |
| funded | lead_time_exhausted | When the deal has not been received by the buyer in the predicted time. |
| success | buyer_accepted | When the deal is received and accepted by the buyer. |
| success | auto_accepted | When the deal is assumed to be received by the buyer if he/she takes no action. |
| jury | init | When the buyer submits a complaint on the deal. |
| success | overruled | When the buyer submits a complaint on the deal and Toman's CRM team rejects his/her complaint. |
| failed | dismissed | When the buyer submits a complaint on the deal and Toman's CRM team accepts his/her complaint. |
| Types | Description |
|---|---|
| post | National Post Company |
| tipax | Tipax Courier Service |
| snapp_box | Snapp Box Courier Service |
| other | Other than above services |
Scenarios:
Assume that you(seller) have created a Deal and Redirected the buyer to Toman's escrow service successfully and Toman's escrow service called back the seller's shop's callback API after the buyer's payment.
Scenario 1: Reject Deal By Buyer
When: Deal is created by shop
-> Deal state: created
-> Deal sub_state: init
Then: Buyer tries to reject your created deal.
-> Deal state: failed
-> Deal sub_state: buyer_rejected
Scenario 2: Expired Deal(Buyer)
When: Deal is created by shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer takes no action in a specific delta time on your created deal.
-> Deal state: failed
-> Deal sub_state: expired
Scenario 3: Seller Reject Deal
When: Deal is created by shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal you have created.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal you have created.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller decides to reject the deal for some reason.
-> Deal state: failed
-> Deal sub_state: seller_rejected
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/reject
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/reject \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/reject"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/reject", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Scenario 4: Expired Deal(Seller)
When: Deal is created by shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller takes no actions, e.g. not submitting the shipment information in a specific time.
-> Deal state: failed
-> Deal sub_state: seller_shipment_expired
Scenario 5: Buyer Receive And Accept Deal Without Exhausting Time
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts the deal's shipment information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer receives the consignment in predicted delta time(specified by shop) and accept it.
-> Deal state: success
-> Deal sub_state: buyer_accepted
Scenario 6: Buyer Receive And Accept Deal With Exhausting Time
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts deal's shipments information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer takes no action in order to receive the consignment in predicted delta time(specified by shop).
-> Deal state: funded
-> Deal sub_state: lead_time_exhausted
Then: Buyer receives the consignment in predicted delta time(specified by shop) and accept it.
-> Deal state: success
-> Deal sub_state: buyer_accepted
Scenario 7: Deal Auto Acceptance
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer takes no action in order to receive the consignment in predicted delta time(specified by shop).
-> Deal state: funded
-> Deal sub_state: lead_time_exhausted
Then: Buyer takes no action on deal in order to receive the consignment, and we assume he/she received it.(Your Shop will be notified by callback)
-> Deal state: success
-> Deal sub_state: auto_accepted
Scenario 8: Buyer Submit A Complaint(Before Lead Time Exhausted) And He/She Is Right
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts deal's shipments information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer submit a complaint on deal.
-> Deal state: jury
-> Deal sub_state: init
Then: Toman CRM team investigate the situation and give right to buyer
-> Deal state: failed
-> Deal sub_state: dismissed
Scenario 9: Buyer Submit A Complaint(Before Lead Time Exhausted) And He/She Is Wrong
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts deal's shipments information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer submit a complaint on deal.
-> Deal state: jury
-> Deal sub_state: init
Then: Toman CRM team investigate the situation and give right to seller
-> Deal state: success
-> Deal sub_state: sustained
Scenario 10: Buyer Submit A Complaint(After Lead Time Exhausted) And He/She Is Wrong
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts deal's shipments information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Buyer takes no action in order to receive the consignment in predicted delta time(specified by shop).
-> Deal state: funded
-> Deal sub_state: lead_time_exhausted
Then: Buyer submit a complaint on deal.
-> Deal state: jury
-> Deal sub_state: init
Then: Toman CRM team investigate the situation and give right to buyer
-> Deal state: failed
-> Deal sub_state: dismissed
Scenario 11: Buyer Submit A Complaint(After Lead Time Exhausted) And He/She Is Wrong
When: The Deal is created by the shop
-> Deal state:created
-> Deal sub_state: init
Then: Buyer accepts the deal.
-> Deal state: created
-> Deal sub_state: buyer_accepted
Then: Buyer funds the deal.
-> Deal state: funded
-> Deal sub_state: new
Then: Seller should verify the deal after callback.
-> Deal state: funded
-> Deal sub_state: init
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/verify
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/verify \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/verify"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/verify", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller inserts deal's shipments information.
-> Deal state: funded
-> Deal sub_state: init
POST /users/me/shops/<shop_slug>/deals/<trace_number>/shipments
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Response
Body:
| Parameter | Type | Description | Example |
|---|---|---|---|
| slug | String | Unique identifier as slug generated by Toman's Escrow service | "1vxlga39u9lzl" |
| type | String | Shipping method types that could be post or tipax or snapp_box or miare or other |
"post" |
| inquiry_code | String (Optional) | Unique Identifier that a shipment service gives to you and must share it with buyer(if type is one of post or tipax or snapp_box or miare) |
"798847393765105487163111" |
| description | String (Optional) | Arbitrary description about shipment to share with buyer with buyer (if type is other) |
"some description about shipment method that buyer needs to know." |
| lead_time | Timedelta [DD] [HH:[MM:]]ss[.uuuuuu] (Optional) |
This value represents the maximum time which is guaranteed by shop to deliver the goods before that and you can modify this specified lead_time at this moment if you want. | "12 00:00:00" |
Status Code: 200
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "post", "inquiry_code": "798847393765105487163111", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "post",
"inquiry_code": "798847393765105487163111",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "post",
"inquiry_code" => "798847393765105487163111",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
curl -X POST $base_url/users/me/shops/$shop_slug/deals/$trace_number/shipments \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token" \
--data-raw '{"type": "other", "description": "some description about shipment method that buyer needs to know", "lead_time": "12 00:00:00"}'
import requests
import json
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/shipments"
payload = json.dumps(
{
"type": "other",
"description": "some description about shipment method that buyer needs to know",
"lead_time": "12 00:00:00"
}
)
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers, json=payload)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/shipments", $base_url, $shop_slug, $trace_number);
$payload = json_encode(
array(
"type" => "other",
"description" => "some description about shipment method that buyer needs to know",
"lead_time" => "12 00:00:00"
)
);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
PATCH /users/me/shops/<shop_slug>/deals/<trace_number>/ship
Path Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| shop_slug | String | A unique string which identifies your shop. | "3h4sex41fbtgn" |
| trace_number | String | A unique string which identifies the deal. This field is generated by Toman when the deal is created | "15827367396329749332" |
Request
Body: empty
Response
Body: empty
Status Code: 204
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
import requests
url = f"{base_url}/users/me/shops/{shop_slug}/deals/{trace_number}/ship"
headers = {
"Authorization": f"Basic {shop_auth_token}",
"Content-Type": "application/json",
}
requests.request("PATCH", url, headers=headers)
<?php
$url = sprintf("%s/users/me/shops/%s/deals/%s/ship", $base_url, $shop_slug, $trace_number);
$headers = array(
sprintf("Authorization: Basic %s", $shop_auth_token),
"Content-Type: application/json"
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>
Then: Seller verifies and informs Toman's escrow service about sent consignment to buyer event.
-> Deal state: funded
-> Deal sub_state: sent
curl -X PATCH $base_url/users/me/shops/$shop_slug/deals/$trace_number/ship \
-H "Content-Type: application/json" \
-H "Authorization: Basic $shop_auth_token"
Then: Buyer takes no action in order to receive the consignment in predicted delta time(specified by shop).
-> Deal state: funded
-> Deal sub_state: lead_time_exhausted
Then: Buyer submit a complaint on deal.
-> Deal state: jury
-> Deal sub_state: init
Then: Toman CRM team investigate the situation and give right to seller
-> Deal state: success
-> Deal sub_state: sustained
Diagram Model
