NAV
shell python php

Introduction

This is Toman's Escrow Service API Reference.

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/v2

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.

Shipping Method Types

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