Questions? Feedback? powered by Olark live chat software

API Guide :: Creating a transaction

Creating your first transaction

Creating transactions with the Escrow.com API is straight forward. Consider a simple transaction between myself and a seller, where I am buying a domain name for $1000.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 1000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        }
    ]
}'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
    "id": 3300003,
    "parties": [
        {
            "customer": "michael.nyqvist@escrow.com",
            "agreed": true,
            "role": "buyer"
        },
        {
            "customer": "keanu.reaves@escrow.com",
            "agreed": false,
            "role": "seller"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "status": {
                "received": false,
                "rejected_returned": false,
                "rejected": false,
                "received_returned": false,
                "shipped": false,
                "accepted": false,
                "shipped_returned": false,
                "accepted_returned": false
            },
            "extra_attributes": {
                "concierge": false,
                "with_content": false
            },
            "description": "johnwick.com",
            "schedule": [
                {
                    "payer_customer": "michael.nyqvist@escrow.com",
                    "status": {
                        "secured": false
                    },
                    "amount": "1000.00",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ],
            "title": "johnwick.com",
            "fees": [
                {
                    "payer_customer": "michael.nyqvist@escrow.com",
                    "amount": "32.50",
                    "type": "escrow"
                }
            ],
            "type": "domain_name",
            "id": 3870000,
            "inspection_period": 259200,
            "quantity": 1
        }
    ]
}

We represent a transaction with a Transaction object. Within the transaction object, we have different attributes.

parties attribute

During transaction creation we use the parties attribute to determine the role of each customer in a transaction. There are four different roles: buyer, seller, broker and partner. It is important to set the customers to their correct role as it cannot be changed once the transaction has been started. Certain actions are only able to be performed be certain roles, such as accepting items.

The buyer in the transaction is the customer that is purchasing the items in the transaction. They are required to fund the transaction and accept the items after the inspection period.

The seller in the transaction is the customer that is providing the items in the transaction. They are required to ship the items to the buyer, and have their funds disbursed after the buyer accepts the items.

The broker in a transaction is the user that is setting up a transaction on behalf of other users. Brokers are able to set a broker commission, and able to set who pays this. If a broker is participating in a transaction, we also support the privacy attribute, which conceals information about the seller from the buyer and information about the buyer from the seller. This includes contact details and transaction amounts. This allows the broker to have a broker commission that is visible to one party, both parties or neither party.

Partners are similar to Brokers in a transaction, however approved partners are also able to perform actions on behalf of customers on a transaction. When a transaction is created on the Escrow.com API, the partner will automatically be set to the customer that makes the API call. There is no need to specify the party object for the partner.

Note

Currently there is a minimum of one buyer and one seller, and a maximum of one buyer, one seller, one broker and one partner is supported in a transaction. However the API may support more in the future.

Note

It is a requirement for the customer or partner creating the transaction to be a party in the transaction. The calling customer will automatically be added as the partner in a created transaction, however we will not automatically assign the buyer, seller or broker roles to any other party. For those roles, it needs to be set specifically.


Besides the role attribute on the party object, there is also the customer attribute. This is the email address of the customer, or simply me. The special value me is a shortcut value to refer to the current user that is making the request.

For more information on the party object, please refer to the reference documentation on the Party Object.

currency attribute

The currency attribute assigns which currency is being used for the transaction. Currently the only currencies that are supported is usd and euro. However we may add more currencies in the future.

description attribute

This is the description for the transaction. Here you can describe what the transaction is for.

items attribute

Every transaction must have at least one item on it. Items can both be transferable items and non transferable items.

Transferable items refer to goods or services that the buyer is purchasing. These include:

  • Domain names
  • General Merchandise
  • Motor Vehicles
  • Services

Non transferable items refer to items in the transaction that facilitate the transfer of transferable items to the buyer. Such items include:

  • Shipping fees
  • Broker fees
  • Partner fees

Each item must contain at least one schedule object. This is how we determine the price of an item and who is paying for it. Currently the only item types that can have multiple schedules are milestone anddomain_name_holding.

Valid values for the item type are:

  • domain_name
  • domain_name_holding
  • general_merchandise
  • milestone
  • motor_vehicle
  • broker_fee
  • partner_fee
  • shipping_fee

Note

At the moment, the API only supports one type of transferable item type per transaction.

Each item can have a category field which gives classification for the type of item being sold.

The valid categories are based on the type of item as follows:

item_typecategory
motor_vehicleautomobiles_cars_and_trucks
boats
motorcycles
airplanes
other_motor_vehicles
general_merchandise
milestone
domain_name(with content)
antiques
appliances
adult_material
alcohol_and_wine
arts_and_crafts
automotive_or_industrial_parts
beauty_and_health
books_and_magazines
business_and_internet
cigarettes_and_tobacco
clothing_and_accessories
collectibles
computer_hardware_and_software
cosmetics
cryptocurrency
gambling_and_casino_games
home_and_garden
fx_and_currency
financial_instruments
furniture
heavy_equipment_and_machinery
jewellery_and_watches
movies_and_music
phamacuticals
automobiles_cars_and_trucks
social_media_accounts
sports_and_recreation
tickets_and_events
tools_and_hardware
toys_and_hobbies
video_games_and_consoles
weapons_and_firearms
other_merchandise

Note

We highly recommend providing a category to your items, as doing so can result in faster processing of your transactions.

fees attribute

The fees attribute refers to the Escrow.com transaction fees. Examples of these fees include:

  • General escrow fee
  • Paypal deposit fee
  • Creditcard deposit fee
  • Wire disbursement fee

type attribute

The valid types on the fee object are as follows:

  • cheque_disbursement
  • escrow
  • paypal_deposit
  • creditcard_deposit
  • wire_disbursement

split attribute

This attribute is only applicable to the fee type escrowand is only valid on transaction creation. This field is used to allow customers to determine who should pay the escrow fee. Valid values are decimal 0.5 (50% of the total) and 1 (100% of the total).

When creating a transaction it is not valid to pass an amount for the fee object. You must pass in the split attribute to the fee object instead. The split specified on each fee item in the list must add up to 1.0.

If no fee schedule is passed on transaction creation, by default the buyer will be set to pay 100% of the escrow type fee.

If a fee schedule is passed on transaction creation, the same fee schedule must be included on each item in the transaction.

schedule attribute

Each fee object must contain at least one schedule object. This determines who is paying for the fees. Currently the buyer must pay for the following fee types:

  • paypal_deposit
  • creditcard_deposit

And the seller must pay for the following fee types:

  • cheque_disbursement
  • wire_disbursement

For more information, have a look at theScheduledocumentation.

Schedule objects

The schedule object is used for representing who is paying for an item or fee.

amount

This field is used for determining the price of items or fees. This is a decimal value.

due_date

In transactions with multiple payment schedules, such as Domain Name Holding or transactions with items delivered at multiple times, you specify thedue_date. This field represents when Escrow.com expects a certain payment to be made, or delivery of an item to be made.

This field is required on schedules on domain name holding and milestone items. Setting this field on other item types is an invalid request and will result in an error.

payer_customer

This is the email address of the customer who will be paying for the item.

beneficiary_customer

This is the email address of the customer who will be receiving the funds. For transferable items this will always be the seller, and for broker fees it will be the broker. For escrow fees it will always be the value escrow.

Creating a domain name transaction with content

Beyond the basic transaction, we can create a transaction for a domain name with content. We do this simply by setting the extra_attributefield with_content to true. You are able to create the transaction for multiple domain names at a time, simply pass multiple item objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name",
            "inspection_period": 259200,
            "quantity": 1,
            "extra_attributes": {
                "with_content": true
            },
            "schedule": [
                {
                    "amount": 1000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ],
            "fees": [
                {
                    "payer_customer": "me",
                    "type": "escrow",
                    "split": 0.5
                },
                {
                    "payer_customer": "keanu.reaves@escrow.com",
                    "type": "escrow",
                    "split": 0.5
                }
            ]
        }
    ]
}'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

{
  "id": 3300000,
  "currency": "usd",
  "description": "The sale of johnwick.com",
  "items": [
    {
      "description": "johnwick.com",
      "extra_attributes": {
        "concierge": false,
        "with_content": true
      },
      "fees": [
        {
          "amount": "16.25",
          "payer_customer": "michael.nyqvist@escrow.com",
          "type": "escrow"
        },
        {
          "amount": "16.25",
          "payer_customer": "keanu.reaves@escrow.com",
          "type": "escrow"
        }
      ],
      "id": 3877634,
      "inspection_period": 259200,
      "quantity": 1,
      "schedule": [
        {
          "amount": "1000.00",
          "beneficiary_customer": "keanu.reaves@escrow.com",
          "payer_customer": "michael.nyqvist@escrow.com",
          "status": {
            "secured": false
          }
        }
      ],
      "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": false,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": false,
        "shipped_returned": false
      },
      "title": "johnwick.com",
      "type": "domain_name"
    }
  ],
  "parties": [
    {
      "agreed": true,
      "customer": "michael.nyqvist@escrow.com",
      "role": "buyer"
    },
    {
      "agreed": false,
      "customer": "keanu.reaves@escrow.com",
      "role": "seller"
    }
  ]
}

Creating a domain name transaction without content

Unlike creating a domain name transaction for a domain with content, you do not need to set the extra_attributewith_content to a value. It will automatically default to false.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name",
            "inspection_period": 259200,
            "quantity": 1,
            "extra_attributes": {
                "with_content": false
            },
            "schedule": [
                {
                    "amount": 1000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        }
    ]
}'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
    "id": 2320000,
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "parties": [
        {
            "customer": "michael.nyqvist@escrow.com",
            "agreed": true,
            "role": "buyer"
        },
        {
            "customer": "keanu.reaves@escrow.com",
            "agreed": false,
            "role": "seller"
        }
    ],
    "items": [
        {
            "status": {
                "received": false,
                "rejected_returned": false,
                "rejected": false,
                "received_returned": false,
                "shipped": false,
                "accepted": false,
                "shipped_returned": false,
                "accepted_returned": false
            },
            "extra_attributes": {
                "concierge": false,
                "with_content": false
            },
            "description": "johnwick.com",
            "schedule": [
                {
                    "payer_customer": "michael.nyqvist@escrow.com",
                    "status": {
                        "secured": false
                    },
                    "amount": "1000.00",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ],
            "title": "johnwick.com",
            "inspection_period": 259200,
            "fees": [
                {
                    "payer_customer": "michael.nyqvist@escrow.com",
                    "amount": "32.50",
                    "type": "escrow"
                }
            ],
            "type": "domain_name",
            "id": 3800000,
            "quantity": 1
        }
    ]
}

Creating a domain name holding transaction

Creating a domain name holding transaction is very similar to creating a normal domain name transaction. The only difference is that you specify multipleschedule objects, and set typeto domain_name_holding

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
% curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name_holding",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 20000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com",
                    "due_date": "2018-01-01T00:00:00Z"
                },
                {
                    "amount": 15000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com",
                    "due_date": "2018-02-01T00:00:00Z"
                },
                {
                    "amount": 15000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com",
                    "due_date": "2018-03-01T00:00:00Z"
                },
                {
                    "amount": 15000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com",
                    "due_date": "2018-04-01T00:00:00Z"
                },
                {
                    "amount": 15000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com",
                    "due_date": "2018-05-01T00:00:00Z"
                }
            ]
        }
    ]
}'

Creating a motor vehicle transaction

Creating a motor vehicle transaction is a little different to creating a domain name transaction. For motor vehicles, we also collect the:

  • VIN number
  • Odometer reading
  • Year of manufacture
  • Make of car
  • Model of car

We also have two additional upgrades on motor vehicles, lien holder payoff and title collection. All of these additional attributes are set in theextra_attributes field.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
% curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of the 1969 Mustang used in the movie John Wick",
    "items": [
        {
        "description": "1969 Mustang Mach 1 Fastback",
            "type": "motor_vehicle",
            "inspection_period": 259200,
            "quantity": 1,
            "extra_attributes": {
              "vin": "19329304",
              "odometer": "10000",
              "year": 1969,
              "make": "Ford",
              "model": "Mustang Mach 1 Fastback",
              "title_collection": true,
              "lien_holder_payoff": false
            },
            "schedule": [
                {
                    "amount": 50000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        }
    ]
}'

Creating a general merchandise transaction

Creating a general merchandise is as simple as setting the item types togeneral_merchandise

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
% curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "2 Original signed copies of a movie poster for John Wick",
    "items": [
        {
            "title": "2 movies posters",
            "description": "John Wick movie poster",
            "type": "general_merchandise",
            "inspection_period": 259200,
            "quantity": 2,
            "schedule": [
                {
                    "amount": 10000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        }
    ]
}'

Creating a milestone transaction

In order to create a milestone transaction, you specify multiple items with thetype set to milestone.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
% curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "buyer",
            "customer": "me"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "John Wick 3",
    "items": [
        {
            "title": "Script",
            "description": "Reading the script",
            "type": "milestone",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 10000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        },
        {
            "title": "Story boards",
            "description": "Doing the story boards",
            "type": "milestone",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 1000000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        },
        {
            "title": "Acting 1",
            "description": "Acting for car crash scene 1",
            "type": "milestone",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 200000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        },
        {
            "title": "Acting 2",
            "description": "Acting for helicopter jump scene 2",
            "type": "milestone",
            "inspection_period": 259200,
            "quantity": 1,
            "schedule": [
                {
                    "amount": 50000.0,
                    "payer_customer": "me",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        }
    ]
}'

Creating a brokered transaction with broker commission.

It is possible to create brokered transactions with a broker commission. This is done by adding one or more broker_fee items to the transaction. You can specify more than one broker fee item if you wish to charge a broker fees to both the buyer or seller. There is no requirement that the broker fees be the same for both the buyer and seller, allowing you to have one party pay more if you wish. There must be a broker in the transaction if you include broker fee items.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "broker",
            "customer": "me"
        },
        {
            "role": "buyer",
            "customer": "john.wick@escrow.com"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com"
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name",
            "inspection_period": 259200,
            "quantity": 1,
            "extra_attributes": {
                "with_content": false
            },
            "schedule": [
                {
                    "amount": 1000.0,
                    "payer_customer": "john.wick@escrow.com",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        },
        {
            "type": "broker_fee",
            "schedule": [
                {
                    "amount": 2500,
                    "payer_customer": "john.wick@escrow.com",
                    "beneficiary_customer": "me"
                }
            ]
        },
        {
            "type": "broker_fee",
            "schedule": [
                {
                    "amount": 200,
                    "payer_customer": "keanu.reaves@escrow.com",
                    "beneficiary_customer": "me"
                }
            ]
        }
    ]
}'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "creation_date": "2017-09-28T06:06:28.210000+00:00",
  "currency": "usd",
  "description": "The sale of johnwick.com",
  "id": 1133945,
  "items": [
    {
      "description": "johnwick.com",
      "extra_attributes": {
        "concierge": false,
        "with_content": false
      },
      "fees": [
        {
          "amount": "113.75",
          "payer_customer": "john.wick@escrow.com",
          "type": "escrow"
        }
      ],
      "id": 1607038,
      "inspection_period": 1800,
      "quantity": 1,
      "schedule": [
        {
          "amount": "1000.00",
          "beneficiary_customer": "keanu.reaves@escrow.com",
          "payer_customer": "john.wick@escrow.com",
          "status": {
            "secured": false
          }
        }
      ],
      "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": false,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": false,
        "shipped_returned": false
      },
      "title": "johnwick.com",
      "type": "domain_name"
    }
  ],
  "parties": [
    {
      "agreed": false,
      "customer": "john.wick@escrow.com",
      "role": "buyer"
    },
    {
      "agreed": false,
      "customer": "keanu.reaves@escrow.com",
      "role": "seller"
    },
    {
      "agreed": true,
      "customer": "broker@escrow.com",
      "role": "broker"
    },
    {
      "agreed": true,
      "customer": "broker@escrow.com",
      "role": "partner"
    }
  ]
}


You may also hide the broker_fee from a party in the transaction by setting the visibility object on the item. All broker_fee items must have the same visibility set and all parties that the fees are hidden from must also appear in the parties visibility objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
curl "https://api.escrow.com/2017-09-01/transaction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
    "parties": [
        {
            "role": "broker",
            "customer": "me"
        },
        {
            "role": "buyer",
            "customer": "john.wick@escrow.com"
        },
        {
            "role": "seller",
            "customer": "keanu.reaves@escrow.com",
            "visibility": {
                "hidden_from": ["john.wick@escrow.com"]
            }
        }
    ],
    "currency": "usd",
    "description": "The sale of johnwick.com",
    "items": [
        {
            "title": "johnwick.com",
            "description": "johnwick.com",
            "type": "domain_name",
            "inspection_period": 259200,
            "quantity": 1,
            "extra_attributes": {
                "with_content": false
            },
            "schedule": [
                {
                    "amount": 1000.0,
                    "payer_customer": "john.wick@escrow.com",
                    "beneficiary_customer": "keanu.reaves@escrow.com"
                }
            ]
        },
        {
            "type": "broker_fee",
            "visibility": {
                "hidden_from": ["john.wick@escrow.com"]
            },
            "schedule": [
                {
                    "amount": 250,
                    "payer_customer": "john.wick@escrow.com",
                    "beneficiary_customer": "me"
                }
            ]
        },
        {
            "type": "broker_fee",
            "visibility": {
                "hidden_from": ["john.wick@escrow.com"]
            },
            "schedule": [
                {
                    "amount": 200,
                    "payer_customer": "keanu.reaves@escrow.com",
                    "beneficiary_customer": "me"
                }
            ]
        }
    ]
}'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "creation_date": "2017-09-28T06:06:28.210000+00:00",
  "currency": "usd",
  "description": "The sale of johnwick.com",
  "id": 1133945,
  "items": [
    {
      "description": "johnwick.com",
      "extra_attributes": {
        "concierge": false,
        "with_content": false
      },
      "fees": [
        {
          "amount": "113.75",
          "payer_customer": "john.wick@escrow.com",
          "type": "escrow"
        }
      ],
      "id": 1607038,
      "inspection_period": 1800,
      "quantity": 1,
      "schedule": [
        {
          "amount": "1000.00",
          "beneficiary_customer": "keanu.reaves@escrow.com",
          "payer_customer": "john.wick@escrow.com",
          "status": {
            "secured": false
          }
        }
      ],
      "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": false,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": false,
        "shipped_returned": false
      },
      "title": "johnwick.com",
      "type": "domain_name"
    }
  ],
  "parties": [
    {
      "agreed": false,
      "customer": "john.wick@escrow.com",
      "role": "buyer"
    },
    {
      "agreed": false,
      "customer": "keanu.reaves@escrow.com",
      "role": "seller"
    },
    {
      "agreed": true,
      "customer": "broker@escrow.com",
      "role": "broker"
    },
    {
      "agreed": true,
      "customer": "broker@escrow.com",
      "role": "partner"
    }
  ]
}