Escrow API Reference

Endpoint reference

Get Customer

Retrieve customer details

URL

Method: GET
/2017-09-01/customer/me
/2017-09-01/customer/{customer_id}
/2017-09-01/customer/me/identification-documents
/2017-09-01/customer/{customer_id}/identification-documents

Path Parameters

Parameter
customer_id

This is the id of the customer you want to retrieve details about. You can also supply the value 'me' instead of the customer id to return the customer information about the current user.

Type: integer or 'me'
Required: No

Response

Customer
Returns the Customer object if you have access to the customers information, otherwise it will return an error.
Sample response:
{
    "address": {
        "city": "San Francisco",
        "country": "United States",
        "line1": "1234 Street Road",
        "post_code": "94104",
        "state": "CA"
    },
    "date_of_birth": "1980-12-30T00:00:00",
    "disbursement_methods": [
        {
            "account_name": "John Wick",
            "account_type": "savings",
            "bank_aba_routing_number": "123456789",
            "bank_account_number": "123456789",
            "bank_address": {
                "city": "San Francisco",
                "state": "CA"
            },
            "bank_name": "Bank of Coffee",
            "currency": "usd",
            "id": 35147,
            "type": "ach"
        }
    ],
    "email": "john.wick@test.escrow.com",
    "first_name": "John",
    "id": 900000,
    "last_name": "Wick",
    "middle_name": "Coffee",
    "phone_number": "+104433221111",
    "tax_numbers": [
        {
            "id": 123,
            "number": "FR03512803495",
            "type": "vat"
        }
    ],
    "username": "John Wick Domains",
    "verification": {
        "company": {
            "status": "not_verified"
        },
        "personal": {
            "status": "verified"
        }
    },
    "webhooks": [
        {
            "id": 7,
            "url": "https://www.escrow.com/webhook"
        }
    ]
}

Get API keys

Retrieve your API keys. Note, this does not return the full API key. You can only see the last 4 characters.

URL

Method: GET
/2017-09-01/customer/me/api_key
/2017-09-01/customer/{customer_id}/api_key

Path Parameters

Parameter
customer_id

This is the id of the customer you want to retrieve api keys for. You can also supply the value 'me' instead of the customer id.

Type: integer or 'me'
Required: No

Response

ApiKeys
Returns the API keys on the customer
Sample response:
{
    "api_keys": [
        {
            "date_created": "2017-01-01T00:00:00+00:00",
            "id": 192,
            "is_active": true,
            "key": "112;AktWI9898928928skjdlksjdkljDAK3R2912",
            "last_four_characters": "2912",
            "name": "Worker"
        },
        {
            "date_created": "2017-01-01T00:00:00+00:00",
            "id": 193,
            "is_active": true,
            "key": "113;AktWIALNKLrLR30BmCeEHnDAK3RAT0VpK",
            "last_four_characters": "0VpK",
            "name": "App"
        }
    ]
}

Update an API key

Updates an API key

URL

Method: PATCH
/2017-09-01/customer/me/api_key/{key_id}
/2017-09-01/customer/{customer_id}/api_key/{key_id}

Path Parameters

Parameter
customer_id

This is the id of the customer you want to create an api key for. You can also supply the value 'me' instead of the customer id.

Type: integer or 'me'
Required: No
key_id

This is the id API key you wish to update

Type: integer
Required: No

Body

Data type: ApiKey

Response

ApiKey
Returns the created API key.
Sample response:
{
    "date_created": "2017-01-01T00:00:00+00:00",
    "id": 192,
    "is_active": true,
    "key": "113;AktWIALNKLrLR30BmCeEHnDAK3RAT0VpK",
    "last_four_characters": "0VpK",
    "name": "Production"
}

Get customer disbursement methods

Get all the saved disbursement methods for the current user

URL

Method: GET
/2017-09-01/customer/me/disbursement_methods
/2017-09-01/customer/{customer_id}/disbursement_methods

Path Parameters

Parameter
customer_id

The id of the customer you want to get disbursement information on

Type: integer or 'me'
Required: No

Response

DisbursementMethods
Returns all the saved disbursement details for for the customer

Get customer disbursement method by id

Get a user's disbursement method given disbursement_id

URL

Method: GET
/2017-09-01/customer/me/disbursement_methods/{disbursement_id}
/2017-09-01/customer/{customer_id}/disbursement_methods/{disbursement_id}

Path Parameters

Parameter
customer_id

The id of the customer you want to get disbursement information on

Type: integer or 'me'
Required: No
disbursement_id

The id of the disbursement method to be fetched

Type: integer
Required: No

Response

DisbursementMethod
Returns the saved disbursement details for the specified id

Get webhooks

Lists the webhooks on the customer

URL

Method: GET
/2017-09-01/customer/me/webhook
/2017-09-01/customer/{customer_id}/webhook

Path Parameters

Parameter
customer_id

This is the id of the customer you want to list the webhooks for. You can also supply the value 'me' instead of the customer id.

Type: integer or 'me'
Required: No

Response

Webhooks
Returns the webhooks
Sample response:
{
    "webhooks": [
        {
            "id": 29292,
            "url": "https://www.example.com/webhook1"
        },
        {
            "id": 2020182,
            "url": "https://www.example.com/webhook2"
        }
    ]
}

Delete a webhook

Removes a webhook from the customer

URL

Method: DELETE
/2017-09-01/customer/me/webhook/{webhook_id}
/2017-09-01/customer/{customer_id}/webhook/{webhook_id}

Path Parameters

Parameter
customer_id

This is the id of the customer you want to delete the webhook on. You can also supply the value 'me' instead of the customer id.

Type: integer or 'me'
Required: No
webhook_id

This is the id of the webhook you want to remove.

Type: integer
Required: No

List partner transactions

Lists the partner transactions you own. We will return a number of transactions depending on the limit, and with the Transaction ID starting at the provided next_cursor field. It will be sorted by the value of sort_by, and ordered using the value provided in sort_direction. The result will be filtered based on the passed filter values.

URL

Method: GET
/2017-09-01/partner/transactions

Query Parameters

Parameter Description
limit

The amount of transactions you want to fetch

Type: integer
Required: Yes
Default value: 1
next_cursor

The start point of the transactions to be fetched

Type: integer
Required: Yes
Default value: 10
sort_by

How you would like to order the transactions in the result.

Type: string
Required: Yes
Default value: id
Valid values: id
sort_direction

The order in which to return the transactions

Type: string
Required: Yes
Default value: desc
Valid values: ascdesc
status

Filters the transactions by status

Type: string
Required: Yes
Default value: None
Valid values: ongoingcompleted
ids

Filters transactions which has the given ids

Type: list[int]
Required: Yes
Default value: None
Valid values: 654321
customer_ids

Filters transactions that involves the given customer ids

Type: list[int]
Required: Yes
Default value: None
Valid values: 123456
min_amount

Filters transactions greater than or equal to the min_amount

Type: float
Required: Yes
Default value: None
max_amount

Filters transactions less than or equal to the max_amount

Type: float
Required: Yes
Default value: None
initiation_start_date

Filters transactions created since the given start_date(inclusive)

Type: date
Required: Yes
Default value: None
initiation_end_date

Filters transactions created before the given initiation_end_date(inclusive)

Type: date
Required: Yes
Default value: None
closed_start_date

Filters transactions closed since the given initiation_end_date(inclusive)

Type: date
Required: Yes
Default value: None
closed_end_date

Filters transactions closed before the given initiation_end_date(inclusive)

Type: date
Required: Yes
Default value: None
exclude_draft

Filters out draft transactions from the result

Type: bool
Required: No

Response

TransactionCursoredList
A TransactionCursoredList object will be returned, which contains transactions depending on the specified limit. It will contain the queries used, along with a pointer to the next cursor which can be used to get the next set of transactions

List partner customers

Lists the customers of the transactions you own. We will return a number of customers depending on the limit, and with the Customer ID starting at the provided next_cursor field. It will be sorted by the value of sort_by, and ordered using the value provided in sort_direction.

URL

Method: GET
/2017-09-01/partner/customers

Query Parameters

Parameter Description
limit

The amount of customers to be fetched per page

Type: integer
Required: Yes
Default value: 1
next_cursor

The start point of customers to be fetched

Type: integer
Required: Yes
Default value: 10
sort_by

How you would like to order the customers in the result.

Type: string
Required: Yes
Default value: id
Valid values: id
sort_direction

The order in which to return the customers

Type: string
Required: Yes
Default value: desc
Valid values: ascdesc
ids

Filters customers which has the given ids

Type: list[int]
Required: Yes
Default value: None
Valid values: 654321
country

Filters customers from given country

Type: string
Required: Yes
Default value: None
Valid values: AUUS
verification_status

Filters customers with given verification status

Type: string
Required: Yes
Default value: None
Valid values: verifiednot_verifiedcompany_verified

Response

CustomerCursoredList
A CustomerCursoredList object will be returned, which contains customers depending on the specified limit. It will contain the queries used, along with a pointer to the next cursor which can be used to get the next set of customers

Get partner party details

Retrieves the customer details for the specified party user if the logged in partner is part of the transaction

URL

Method: GET
/2017-09-01/partner/customer

Path Parameters

Parameter
party_id

This is the party id of the user to retrieve the customer details for.

Type: integer
Required: No
customer_id

This is the customer id of the user to retrieve the customer details for.

Type: integer
Required: No

Response

CustomerPartnerView
Returns the Customer object if you have access to the customers information, otherwise it will return an error.

Get partner transactions_statistics

Lists the partner transaction statistics on transactions you own. The data will include time based data, aggregates, and the configuration used to call this endpoint

URL

Method: GET
/2017-09-01/partner/statistics/transactions/count

Response

V4StatisticsTransactionCountResultData
A V4StatisticsTransactionCountResultDataSchema object will be returned, which contains transaction data depending on the input constraints. It will contain the queries used, along with a time based data and aggregate data

Get partner customers_statistics

Lists the partner customer statistics on customers you own. The data will include time based data, aggregates, and the configuration used to call this endpoint

URL

Method: GET
/2017-09-01/partner/statistics/customers/count

Response

V4StatisticsCustomerCountResultData
A V4StatisticsCustomerCountResultDataSchema object will be returned, which contains customer data depending on the input constraints. It will contain the queries used, along with a time based data and aggregate data

Get partner customer saved payments in

Lists the saved CC information of a partnered customer, where the data that will be returned is limited to what a partner is allowed to view.

URL

Method: GET
/2017-09-01/partner/customer/{customer_id}/payments_in

Response

PartnerCustomerCCInfo
A list of PartnerCustomerCCInfoSchema objects will be returned containing the last four digits of the account number, expiration month, expiration year, brand, and the customer ID for a CC.

Get partner customer saved payments out

Lists the saved disbursement information of a partnered customer, where the data that will be returned is limited to what a partner is allowed to view.

URL

Method: GET
/2017-09-01/partner/customer/{customer_id}/payments_out

Response

PartnerCustomerCCInfo
A list of PartnerCustomerCCInfoSchema objects will be returned containing the last four digits of the account number, expiration month, expiration year, brand, and the customer ID for a CC.

List partner reports

Lists the reports that the calling partner generated.

URL

Method: GET
/2017-09-01/partner/reports
/2017-09-01/partner/reports/count

Response

V4PartnerReports
A V4PartnerReportsSchema object will be returned, which contains a list of all the requested reports by the partner

Generate Report

Generates a report for partner owned transactions and customers given the filters

URL

Method: POST
/2017-09-01/partner/reports

Body

Data type: PartnerTransactionGetParams

Response

V4PartnerReportsPostSchema
A V4PartnerReportsPostSchema object will be returned. This will contain both transaction and customer information available on the dashboard.

Download partner reports

returns or redirects the partner report download url

URL

Method: GET
/2017-09-01/partner/reports/{task_id}/download

Query Parameters

Parameter Description
as_json

The constraints on the transactions to be included in the report.

Type: bool
Required: No

Response

V4PartnerReports
A V4PartnerReportsSchema object will be returned, which contains a list of all the requested reports by the partner

List transactions

Lists the transactions you are involved in, in a paginated form. We will return 10 transactions per page, ordered by the value in the sort_by parameter.

URL

Method: GET
/2017-09-01/transaction

Query Parameters

Parameter Description
page

The page of transactions you want to fetch

Type: integer
Required: Yes
Default value: 1
per_page

The amount of transactions to be fetched per page

Type: integer
Required: Yes
Default value: 10
sort_by

How you would like to order the transactions in the result.

Type: string
Required: Yes
Default value: id
Valid values: id
sort_direction

The order in which to return the transactions

Type: string
Required: Yes
Default value: desc
Valid values: ascdesc

Response

TransactionList
A TransactionList object will be returned, which contains a maximum of 10 transaction. The number of available pages will also be returned.
Sample response:
{
    "page": 1,
    "page_count": 1,
    "per_page": 50,
    "transactions": [
        {
            "currency": "usd",
            "description": "Sale of johnwick.com",
            "id": 190202,
            "items": [
                {
                    "description": "johnwick.com",
                    "extra_attributes": {
                        "concierge": false,
                        "with_content": false
                    },
                    "fees": [
                        {
                            "amount": "100.00",
                            "payer_customer": "john.wick@test.escrow.com",
                            "type": "escrow"
                        }
                    ],
                    "id": 1129292,
                    "inspection_period": 86400,
                    "quantity": 1,
                    "schedule": [
                        {
                            "amount": "1000.00",
                            "beneficiary_customer": "keanu.reeves@test.escrow.com",
                            "payer_customer": "john.wick@test.escrow.com"
                        }
                    ],
                    "status": {
                        "accepted": false,
                        "accepted_returned": false,
                        "received": true,
                        "received_returned": false,
                        "rejected": false,
                        "rejected_returned": false,
                        "shipped": true,
                        "shipped_returned": false
                    },
                    "title": "johnwick.com",
                    "type": "domain_name"
                }
            ],
            "parties": [
                {
                    "agreed": true,
                    "customer": "john@wick.com",
                    "role": "buyer"
                },
                {
                    "agreed": true,
                    "customer": "keanu.reeves@test.escrow.com",
                    "role": "seller"
                }
            ]
        }
    ]
}

Get transaction

This method allows you to fetch details about a transaction where you know the transaction id. You can only fetch transaction details for a given transaction if you are a party involved in that transaction. Transaction details may be different for each user.

URL

Method: GET
/2017-09-01/transaction/{transaction_id}

Path Parameters

Parameter
transaction_id

The id for the transaction you want to get the details of.

Type: integer
Required: No

Response

Transaction
This endpoint will return the transaction object for the transaction requested if you are able to access it. If not, an error will be returned.
Sample response:
{
    "currency": "usd",
    "description": "Sale of johnwick.com",
    "id": 190202,
    "items": [
        {
            "description": "johnwick.com",
            "extra_attributes": {
                "concierge": false,
                "with_content": false
            },
            "fees": [
                {
                    "amount": "100.00",
                    "payer_customer": "john.wick@test.escrow.com",
                    "type": "escrow"
                }
            ],
            "id": 1129292,
            "inspection_period": 86400,
            "quantity": 1,
            "schedule": [
                {
                    "amount": "1000.00",
                    "beneficiary_customer": "keanu.reeves@test.escrow.com",
                    "payer_customer": "john.wick@test.escrow.com"
                }
            ],
            "status": {
                "accepted": false,
                "accepted_returned": false,
                "received": true,
                "received_returned": false,
                "rejected": false,
                "rejected_returned": false,
                "shipped": true,
                "shipped_returned": false
            },
            "title": "johnwick.com",
            "type": "domain_name"
        }
    ],
    "parties": [
        {
            "agreed": true,
            "customer": "john@wick.com",
            "role": "buyer"
        },
        {
            "agreed": true,
            "customer": "keanu.reeves@test.escrow.com",
            "role": "seller"
        }
    ]
}

Perform a transaction action

Perform an action on a transaction

URL

Method: PATCH
/2017-09-01/transaction/{transaction_id}

Path Parameters

Parameter
transaction_id

Type: integer
Required: No

Body

Data type: TransactionAction

Response

Transaction
If the action of the transaction is successful, the new Transaction object will be returned.
Sample response:
{
    "currency": "usd",
    "description": "Sale of johnwick.com",
    "id": 190202,
    "items": [
        {
            "description": "johnwick.com",
            "extra_attributes": {
                "concierge": false,
                "with_content": false
            },
            "fees": [
                {
                    "amount": "100.00",
                    "payer_customer": "john.wick@test.escrow.com",
                    "type": "escrow"
                }
            ],
            "id": 1129292,
            "inspection_period": 86400,
            "quantity": 1,
            "schedule": [
                {
                    "amount": "1000.00",
                    "beneficiary_customer": "keanu.reeves@test.escrow.com",
                    "payer_customer": "john.wick@test.escrow.com"
                }
            ],
            "status": {
                "accepted": false,
                "accepted_returned": false,
                "received": true,
                "received_returned": false,
                "rejected": false,
                "rejected_returned": false,
                "shipped": true,
                "shipped_returned": false
            },
            "title": "johnwick.com",
            "type": "domain_name"
        }
    ],
    "parties": [
        {
            "agreed": true,
            "customer": "john@wick.com",
            "role": "buyer"
        },
        {
            "agreed": true,
            "customer": "keanu.reeves@test.escrow.com",
            "role": "seller"
        }
    ]
}

Get transaction by reference

This method allows you to fetch details about a transaction where you know the external reference. You can only fetch transaction details for a given transaction if you are a party involved in that transaction. Transaction details may be different for each user.

URL

Method: GET
/2017-09-01/transaction/reference/{reference}

Path Parameters

Parameter
reference

The external reference for the transaction you want to get the details of.

Type: string
Required: No

Response

Transaction
This endpoint will return the transaction object for the transaction requested if you are able to access it. If not, an error will be returned.

Get transaction timeline entries

This method allows you to fetch the timeline entries of a transaction where you know the transaction id. You can only fetch timeline entries for a given transaction if you are a party involved in that transaction.

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/timeline-entries

Path Parameters

Parameter
transaction_id

The id for the transaction you want to get the timeline entries of

Type: integer
Required: No

Response

TransactionTimelineNotes
This endpoint will return the timeline entries object for the transaction requested if you are able to access it. If not, an error will be returned

Get transaction disbursement methods

Gets transaction disbursement information. This endpoint can only be called by the seller and the broker in the transaction. The information that is returned is specific to the user that is calling the API as well. Different details will be returned for the seller than the broker.

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/disbursement_methods

Path Parameters

Parameter
transaction_id

The id of the transaction you want to get the disbursement information on.

Type: integer
Required: No

Response

DisbursementMethods
Returns the disbursement method details for the specified transaction
Sample response:
{
    "available_disbursement_methods": [
        {
            "total": "1890.00",
            "type": "wire_transfer"
        },
        {
            "total": "1895.00",
            "type": "wire_transfer_international"
        },
        {
            "total": "1895.00",
            "type": "ach"
        }
    ],
    "saved_disbursement_methods": [
        {
            "account_name": "John Wick",
            "bank_aba_routing_number": "219291291",
            "bank_address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "100 Montgomery Street",
                "post_code": "94104"
            },
            "bank_name": "American Savings Bank",
            "bank_swift_code": "SI2920",
            "beneficiary_address": {},
            "currency": "usd",
            "id": 129292,
            "type": "wire_transfer"
        }
    ],
    "selected_disbursement_method": null
}

Patch transaction disbursement method

Updates disbursement information on a transaction for the current user if it has been set already.

URL

Method: PATCH
/2017-09-01/transaction/{transaction_id}/disbursement_methods

Path Parameters

Parameter
transaction_id

The id of the transaction you want to set disbursement information on.

Type: integer
Required: No

Body

Data type: DisbursementMethodInput

Response

DisbursementMethods
Returns the disbursement method details for the specified transaction, with the selected disbursement method shown.

Perform an action on a milestone item

Perform actions on milestone items

URL

Method: PATCH
/2017-09-01/transaction/{transaction_id}/item/{item_id}

Path Parameters

Parameter
transaction_id

The id for the transaction for the milestone you wish to update

Type: integer
Required: No
item_id

The id of the milestone you want to update.

Type: integer
Required: No

Body

Data type: TransactionAction

Response

Transaction
Milestone item has been actioned, returns the details of the transaction
Sample response:
{
    "description": "johnwick.com",
    "extra_attributes": {
        "concierge": false,
        "with_content": false
    },
    "fees": [
        {
            "amount": "100.00",
            "payer_customer": "john.wick@test.escrow.com",
            "type": "escrow"
        }
    ],
    "id": 1129292,
    "inspection_period": 86400,
    "quantity": 1,
    "schedule": [
        {
            "amount": "1000.00",
            "beneficiary_customer": "keanu.reeves@test.escrow.com",
            "payer_customer": "john.wick@test.escrow.com"
        }
    ],
    "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": true,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": true,
        "shipped_returned": false
    },
    "title": "johnwick.com",
    "type": "domain_name"
}

Get transaction payment methods

Get a payment methods available for a particular transaction

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/payment_methods

Path Parameters

Parameter
transaction_id

The id of the transaction you want to get the available payment methods for.

Type: integer
Required: No

Response

PaymentMethods
Returns available payment methods and totals
Sample response:
{
    "available_payment_methods": [
        {
            "total": "2300.00",
            "type": "credit_card"
        },
        {
            "total": "2275.00",
            "type": "wire_transfer"
        }
    ],
    "conditionally_available_payment_methods": [
        {
            "conditions": [
                "verification_required"
            ],
            "total": "531.20",
            "type": "paypal"
        }
    ],
    "total_without_payment_fee": "500.00"
}

Select payment method to fund the transaction

Marks the transaction as being paid by the selected method, and returns a link to the credit card or PayPal checkout page.

URL

Method: POST
/2017-09-01/transaction/{transaction_id}/payment_methods/{payment_method_name}

Path Parameters

Parameter
transaction_id

The ID of the transaction the user is paying for.

Type: integer
Required: No
payment_method

The type of payment link you would like to retrieve

Type: string
Required: No
Valid values: credit_cardpaypalwire_transferpoli

Body

Data type: PaymentMethodInput

Response

LandingPage
If applicable, returns a URL which the customer can navigate to to make the payment.
Sample response:
{
    "landing_page": "https://my.escrow.com/transaction.asp?TID=29"
}

Get the paypal landing url

Retrieves the paypal url for the new paypal flow

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/payment_methods/paypal

Path Parameters

Parameter
transaction_id

The ID of the transaction the user is paying for.

Type: integer
Required: No

Query Parameters

Parameter Description
return_url

The redirect url that will be used after user has been redirected to the Escrow paypal success page.

Type: string
Required: No
redirect_type

If the redirect will happen automatically after a few seconds or manually via CTA click.

Type: string
Required: No

Response

LandingPage
If applicable, returns a URL which the customer can navigate to to make the payment.

Get wire transfer details

Get the wire transfer details for a particular transaction. Don't make the assumption that these will always be the same details for each transaction, as they are likely to change.

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/payment_methods/wire_transfer

Path Parameters

Parameter
transaction_id

The id of the transaction you want to get the wire details for.

Type: integer
Required: No

Response

WireTransferDetails
Returns the wire transfer details for the current transaction
Sample response:
{
    "additional_instructions": "Reference Escrow Transaction #12345",
    "bank_address": "420 Montgomery St., San Francisco, CA 94104",
    "bank_name": "Wells Fargo Bank, N.A",
    "credit_account_name": "Internet Escrow Services Inc",
    "credit_account_number": "7101167844",
    "routing_number": "121000248",
    "structured_bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "420 Montgomery Street",
        "post_code": "94104",
        "state": "CA"
    },
    "swift_code": "WFBIUS6S"
}

Get check details

Get the check payment details for a particular transaction. Don't make the assumption that these will always be the same details for each transaction, as they are likely to change.

URL

Method: GET
/2017-09-01/transaction/{transaction_id}/payment_methods/check

Path Parameters

Parameter
transaction_id

The id of the transaction you want to get the wire details for.

Type: integer
Required: No

Response

CheckDetails
Returns the check payment details for the current transaction

Post Buyer Payment Details

Sets the bank detail for a buyer when paying by wire for a particular transaction. This detail will be used to consider calculate which account Escrow.com will recieve funds to minimize international transfer fees.

URL

Method: POST
/2017-09-01/transaction/{transaction_id}/buyer_payment

Path Parameters

Parameter
transaction_id

The id of the transaction you want to set the bank details for.

Type: integer
Required: No

Body

Data type: BuyerPayment

Response

Type references

Address

The Address object is used to represent Addresses in the Escrow.com API. Required fields can depend on the context, e.g. the `DisbursementMethodSchemaInput` has requirements for the type of disbursement method.
Property Details
line1

The first line of the address

Type: string
line2

The second line of the address

Type: string
city

The city of the address

Type: string
state

The state of the address

Type: string
country

The country of the address as an ISO 3166-1 alpha-2 code

Type: string
Valid values:
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW
post_code

The post code or the zip code.

Type: string
{
    "city": "San Francisco",
    "country": "US",
    "line1": "600 Montgomery Street",
    "line2": "Apartment 20",
    "post_code": "94104",
    "state": "California"
}

AddressPatch

Property Details
line1

The first line of the address

Type: string
line2

The second line of the address

Type: string
city

The city of the address

Type: string
state

The state of the address

Type: string
country

The country of the address as an ISO 3166-1 alpha-2 code

Type: string
Valid values:
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW
post_code

The post code or the zip code.

Type: string
{
    "city": "San Francisco",
    "country": "US",
    "line1": "600 Montgomery Street",
    "line2": "Apartment 20",
    "post_code": "94104",
    "state": "California"
}

Visibility

Property Details
hidden_from

This is the list of email addresses that the party is hidden from. This is only available in brokered transactions.

Type: Array[string]
Required: No
{
    "hidden_from": [
        "john.wick@test.escrow.com"
    ]
}

CustomTimeout

The CustomTimeout object specify the timeout event needs to be triggered after a specific amount of time.
Property Details
name

The name of a specific event which will be triggered

Type: string
Required: Yes

Valid values:
  • marked_as_paid
period

The period before triggering the timeout in seconds.

Type: integer
Required: Yes
{
    "name": "marked_as_paid",
    "period": 86400
}

Party

The Party object is used to specify a customer that is part of a transaction and their status in the transaction. This object also contains the role of the customer, which determines what actions they are able to perform.
Property Details
customer

The email address of the party. You may also pass the value 'me' if the party object is representing you.

Type: string
Required: Yes
Maximum Length: 254
role

This is the role that the party is in the transaction. Buyers are the customers that are funding the transaction and will be receiving the items. Sellers are the customers that will be sending the items to the buyer and will be receiving the funds at the end of the transaction. Brokers are a third party to the transaction and are commonly a third party between the buyer and seller. Brokers can also take an optional broker commission. A partner is similar to a broker however partners may also be able to perform actions on behalf of users.

Type: string
Required: Yes

Valid values:
  • broker
  • buyer
  • partner
  • seller
agreed

This field indicates whether or not the party has agreed to the transaction.

Type: boolean
Required: No
initiator

This field indicates whether or not the party was the initiator of the transaction.

Type: boolean
Required: No
verification_required

This field indicates whether or not the party requires additional verification in order to complete this transaction.

Type: boolean
Required: No
visibility

This field contains the visibility object for the party which defines who their email address should be hidden from

Type: Visibility
next_step

This field provides a link that will appear for a user to a relevant part of the Escrow.com site when further action is required before proceeding.

Type: string
disbursement_method_selected

This field indicates whether or not the party has selected their disbursement method. Will only be returned on the seller/broker

Type: boolean
id

The unique Id for this party in this transaction

Type: integer
phone_number

This field contains the phone number of the non-initiator party

Type: string
{
    "agreed": false,
    "customer": "john.wick@test.escrow.com",
    "initiator": false,
    "role": "buyer"
}
{
    "customer": "me",
    "role": "seller"
}
{
    "agreed": false,
    "customer": "john.wick@test.escrow.com",
    "initiator": false,
    "role": "buyer",
    "visibility": {
        "hidden_from": [
            "viggo.tarasov@escrow.com"
        ]
    }
}

ScheduleStatus

This object represents the status of a Schedule.
Property Details
disbursed_to_beneficiary

This shows whether or not the schedule payment has been disbursed to the beneficiary.

Type: boolean
disbursed_to_payer

This shows whether or not the schedule payment has been disbursed to the payer (for returned items).

Type: boolean
secured

This shows whether or not the schedule payment has been secured by Escrow.com.

Type: boolean
payment_sent

This shows whether or not the schedule payment has been sent to Escrow.com.

Type: boolean
payment_received

This shows whether or not the schedule payment has been received by Escrow.com.

Type: boolean
refund_created

This shows whether or not a refund has been initiated for this schedule payment.

Type: boolean
refund_resolved

This shows whether or not a refund has been resolved for this schedule payment. If a refund is resolved, it will be payed out. Currently for milestone transactions, this will only reflect the latest refund.

Type: boolean
refund_rejected

This shows whether or not a refund has been rejected for this schedule payment. If a refund is rejected, it will not be payed out. Currently for milestone transactions, this will only reflect the latest refund.

Type: boolean
{
    "secured": false
}
{
    "disbursed_to_beneficiary": false,
    "disbursed_to_payer": true,
    "secured": true
}
{
    "disbursed_to_beneficiary": false,
    "disbursed_to_payer": true,
    "refund_created": true,
    "refund_rejected": false,
    "refund_resolved": false,
    "secured": true
}

Schedule

The Schedule object is the way that we represent monetary amounts.
Property Details
amount Type: number
Required: Yes
payer_customer

The email address of the customer that will be paying for the item or fee. This field may also contain the value 'me', which refers to the currently logged in customer.

Type: string
Required: Yes
beneficiary_customer

The email address of the party that will be receiving the funds from the item or fee. This field may also contain the value 'me' (which refers to the currently logged in customer) or the value 'escrow' which refers to Escrow.com.

Type: string
Required: Yes
status

The status of the monetary amount.

Type: ScheduleStatus
due_date

Due date of schedule item. This is only used in schedules on domain name holding transactions

Type: string
Required: No
custom_timeouts

This field contains a list of timeout events that have been set by the creator of the transaction to be different from default values.

Type: Array[CustomTimeout]
percentage

This is an optional field that allows the broker fee to be calculated as as percentage.

Type: number
Required: No
reference

This can be used as a reference to the schedule item e.g. for broker fees.

Type: string
parent_reference

Used to refer to the parent item for this schedule item

Type: string
description Type: string
required_before_shipment Type: boolean
paid_date Type: string
{
    "amount": "10020.10",
    "beneficiary_customer": "john.wick@test.escrow.com",
    "payer_customer": "keanu.reeves@test.escrow.com",
    "status": {
        "disbursed_to_beneficiary": true,
        "secured": true
    }
}

ModifySchedule

Property Details
amount Type: number

Tax

The Tax object is the way we represent taxes - the amount, type and who pays that tax.
Property Details
type

The type of tax being displayed.

Type: string
Required: Yes

Valid values:
  • gst
  • hst
  • vat
amount

The amount to be paid.

Type: number
Required: No
{
    "amount": "123.45",
    "type": "gst"
}

Fee

The Fee object is the way we represent fees - the amount, the type of fee, and who pays that fee.
Property Details
type

The type of fee being displayed.

Type: string
Required: Yes

Valid values:
  • concierge
  • credit_card
  • disbursement
  • domain_name_holding
  • escrow
  • intermediary
  • lien_holder_payoff
  • motor_vehicle
  • other
  • title_collection
amount

The amount to be paid.

Type: number
Required: No
amount_without_taxes

The amount paid before taxes.

Type: number
Required: No
payer_customer

The party who will pay the fee.

Type: string
Required: Yes
split

Split of total fee to be paid by payer_customer.

Type: number
Required: No

Valid values:
  • 0
  • 0.5
  • 1
taxes

A list of taxes paid for a particular fee.

Type: Array[Tax]
{
    "amount": "1002.00",
    "payer_customer": "john@wick.com",
    "type": "escrow"
}
{
    "amount": "100.20",
    "payer_customer": "john@wick.com",
    "type": "concierge"
}
{
    "amount": "20.00",
    "payer_customer": "seller@example.com",
    "type": "disbursement"
}
{
    "payer_customer": "seller@example.com",
    "split": "0.5",
    "type": "escrow"
}
{
    "payer_customer": "buyer@example.com",
    "split": "0.5",
    "type": "escrow"
}
{
    "amount": "1102.20",
    "payer_customer": "john.wick@test.escrow.com",
    "taxes": [
        {
            "amount": "100.20"
        }
    ],
    "type": "escrow"
}

ItemExtraAttributes

This object is used for specifying extra information about items.
Property Details
vin

The vehicle's vehicle identification number (VIN). Only applicable on motor vehicle transactions.

Type: string
Maximum Length: 20
odometer

The value of the vehicle's odometer. Only applicable on motor vehicle transactions.

Type: string
year

The year the vehicle was manufactured. Only applicable on motor vehicle transactions.

Type: integer
Minimum Value: 1850
make

The manufacturer of the vehicle. Only applicable on motor vehicle transactions.

Type: string
Maximum Length: 75
model

The model of the vehicle. Only applicable on motor vehicle transactions.

Type: string
Maximum Length: 75
title_collection

Enable the title collection service. Only applicable on motor vehicle transactions.

Type: boolean
lien_holder_payoff

Enable the lien holder payoff service. Only applicable on motor vehicle transactions.

Type: boolean
with_content

Indicate that a domain name includes content. Only applicable on domain name transactions. If this field is set to true, then 'concierge' must not also be set.

Type: boolean
concierge

Indicate that a domain name requires the concierge service. Only applicable on domain name transactions. If this field is set to true, then the 'with_content' field must not be set.

Type: boolean
dns_manager

The party that will be managing the domain name. Only applicable on DNH transactions.

Type: string

Valid values:
  • buyer
  • escrow
term_period

The duration of the domain name holding service in months. Only applicable on DNH transactions.

Type: integer
Minimum Value: 3
Maximum Value: 60
image_url

Image URL representing the merchandise item

Type: string
merchant_url

URL leading to the item's listing in the partner's page

Type: string
{
    "lien_holder_payoff": false,
    "make": "Make",
    "model": "Model",
    "odometer": "100230",
    "title_collection": true,
    "vin": "19UUA66215A080924",
    "year": 1920
}
{
    "with_content": true
}
{
    "concierge": true
}

ItemStatus

ItemStatus represents the status of the item. This includes whether or not the item has been shipped, received and accepted.
Property Details
accepted

This shows whether or not the item has been accepted by the buyer.

Type: boolean
accepted_returned

This shows whether or not the returned item has been accepted by the seller.

Type: boolean
received

This shows whether or not the item has been received by the buyer.

Type: boolean
received_date

This shows the timestamp for when the item was received by the buyer. This is only applicable for non-milestone transactions.

Type: string
received_returned

This shows whether or not the returned item has been received by the seller.

Type: boolean
rejected

This shows whether or not the item has been rejected by the buyer.

Type: boolean
rejected_returned

This shows whether or not the returned item has been rejected by the seller.

Type: boolean
shipped

This shows whether or not the item has been shipped by the seller.

Type: boolean
shipped_returned

This shows whether or not the returned item has been shipped by the buyer.

Type: boolean
canceled

This shows whether or not the item has been canceled.

Type: boolean
in_dispute

This shows whether the transaction is in arbitration period or not

Type: boolean
{
    "accepted": false,
    "accepted_returned": false,
    "received": true,
    "received_returned": false,
    "rejected": false,
    "rejected_returned": false,
    "shipped": true,
    "shipped_returned": false
}

TrackingInformation

This object is used when marking a transaction as shipped to provide information about how the item was shipped.
Property Details
carrier

The name of the shipping provider

Type: string
Required: Yes
carrier_contact

Contact number of the shipping provider

Type: string
Required: No
carrier_id

The id of the shipping provider

Type: string
Required: No
tracking_id

The tracking ID or number for the shipment

Type: string
Required: Yes
{
    "carrier": "USPS",
    "tracking_id": "EA 999 999 999 US"
}

ShippingInformation

This object is used when marking a transaction or item as shipped.
Property Details
tracking_information

Information required for tracking a physical delivery

Type: TrackingInformation
authorization_type

The selected authorization type for a domain name transaction

Type: string

Valid values:
  • authorization_code
  • push
  • username_password
shipping_party

The party which initiated the shipment

Type: string

Valid values:
  • buyer
  • seller
{
    "tracking_information": {
        "carrier": "USPS",
        "tracking_id": "EA 999 999 999 US"
    }
}
{
    "authorization_type": "authorization_code"
}

Item

Items represent what is in the transaction. Items can be both transferable and non-transferable. Transferable items are the items that are being sold by the seller to the buyer. Non-transferable items are the items in the transaction that help facilitate the transaction. Such items may be shipping fees, broker fees or partner fees.
Property Details
id

The id of the item, this is used in milestone transactions where you are able to mark individual items as shipped, received and accepted.

Type: integer
title

The name of the item being transferred.

Type: string
Minimum Length: 1
Maximum Length: 200
description

A brief description of the item being transferred.

Type: string
Minimum Length: 1
Maximum Length: 500
parent_item_id

Id of the parent item that this entry is related to

Type: integer
reference

This can be used to refer to the item while creating the transaction

Type: string
parent_reference

Used to refer to the parent item for this entity

Type: string
type

The item type - can affect behaviour of the transaction and can also be used to specify party-specific fees.

Type: string

Valid values:
  • broker_fee
  • domain_name
  • domain_name_holding
  • general_merchandise
  • milestone
  • motor_vehicle
  • partner_fee
  • shipping_fee
inspection_period

The length of the inspection period in seconds. Currently the inspection period must be in whole multiples of days. e.g half a day (43200 seconds) is invalid where as 1 day (86400 seconds) and 2 days (172800 seconds) would be valid.

Type: integer
Minimum Value: 86400
Maximum Value: 2592000
quantity

The number of the item that is being sold. NOTE: this value does not factor into the price and is purely informative. All values shown in the schedules are the total amount, not the unit price.

Type: integer
Minimum Value: 1
Maximum Value: 10000
schedule

The way that we represent monetary amounts.

Type: Array[Schedule]
fees

The way that we represent fees - the amount, type of fee, and who pays the fee.

Type: Array[Fee]
extra_attributes

Additional attributes relevant to an item

Type: ItemExtraAttributes
visibility

This field contains the visibility object for the item which defines who can see the cost of the item. Note it is only available for broker_fee.

Type: Visibility
status

A group of fields representing actions that have been taken with respect to this item.

Type: ItemStatus
category

The type of category for the item. See the example docs for a list of valid categories based on item type

Type: string
Maximum Length: 128
custom_category

The custom category for the item as set by the user.

Type: string
Maximum Length: 128
shipping_information

The information required for tracking delivery of the item

Type: Array[ShippingInformation]
shipping_type

This signifies the shipping type for general merchandise transactions

Type: string

Valid values:
  • cargo_shipping
  • no_shipping
  • standard_shipping
{
    "description": "johnwick.com",
    "extra_attributes": {
        "concierge": false,
        "with_content": false
    },
    "fees": [
        {
            "amount": "100.00",
            "payer_customer": "john.wick@test.escrow.com",
            "type": "escrow"
        }
    ],
    "id": 1129292,
    "inspection_period": 86400,
    "quantity": 1,
    "schedule": [
        {
            "amount": "1000.00",
            "beneficiary_customer": "keanu.reeves@test.escrow.com",
            "payer_customer": "john.wick@test.escrow.com"
        }
    ],
    "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": true,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": true,
        "shipped_returned": false
    },
    "title": "johnwick.com",
    "type": "domain_name"
}
{
    "description": "johnwick.com",
    "parent_item_id": 1129292,
    "schedule": [
        {
            "amount": "100.00",
            "beneficiary_customer": "keanu.reeves@test.escrow.com",
            "payer_customer": "john.wick@test.escrow.com"
        }
    ],
    "title": "johnwick.com",
    "type": "broker_fee",
    "visibility": {
        "hidden_from": [
            "viggo.tarasov@escrow.com"
        ]
    }
}

ModifyItem

Property Details
id Type: integer
schedule Type: Array[ModifySchedule]
description Type: string

ModifyTermsSchedule

Property Details
amount Type: number
Required: Yes
payer_customer

The email address of the customer that will be paying for the item or fee. This field may also contain the value 'me', which refers to the currently logged in customer.

Type: string
Required: Yes
beneficiary_customer

The email address of the party that will be receiving the funds from the item or fee. This field may also contain the value 'me' (which refers to the currently logged in customer) or the value 'escrow' which refers to Escrow.com.

Type: string
Required: No
status

The status of the monetary amount.

Type: ScheduleStatus
due_date

Due date of schedule item. This is only used in schedules on domain name holding transactions

Type: string
Required: No
custom_timeouts

This field contains a list of timeout events that have been set by the creator of the transaction to be different from default values.

Type: Array[CustomTimeout]
percentage

This is an optional field that allows the broker fee to be calculated as as percentage.

Type: number
Required: No
reference

This can be used as a reference to the schedule item e.g. for broker fees.

Type: string
parent_reference

Used to refer to the parent item for this schedule item

Type: string
description Type: string
required_before_shipment Type: boolean
paid_date Type: string
{
    "amount": "10020.10",
    "beneficiary_customer": "john.wick@test.escrow.com",
    "payer_customer": "keanu.reeves@test.escrow.com",
    "status": {
        "disbursed_to_beneficiary": true,
        "secured": true
    }
}

ModifyFee

Property Details
type

The type of fee being displayed.

Type: string
Required: Yes

Valid values:
  • escrow
amount

The amount to be paid.

Type: number
Required: No
amount_without_taxes

The amount paid before taxes.

Type: number
Required: No
payer_customer

The party who will pay the fee.

Type: string
Required: Yes
split

Split of total fee to be paid by payer_customer.

Type: number
Required: No

Valid values:
  • 0
  • 0.5
  • 1
taxes

A list of taxes paid for a particular fee.

Type: Array[Tax]
{
    "amount": "1002.00",
    "payer_customer": "john@wick.com",
    "type": "escrow"
}
{
    "amount": "100.20",
    "payer_customer": "john@wick.com",
    "type": "concierge"
}
{
    "amount": "20.00",
    "payer_customer": "seller@example.com",
    "type": "disbursement"
}
{
    "payer_customer": "seller@example.com",
    "split": "0.5",
    "type": "escrow"
}
{
    "payer_customer": "buyer@example.com",
    "split": "0.5",
    "type": "escrow"
}
{
    "amount": "1102.20",
    "payer_customer": "john.wick@test.escrow.com",
    "taxes": [
        {
            "amount": "100.20"
        }
    ],
    "type": "escrow"
}

ModifyTermsItem

Property Details
id

The id of the item, this is used in milestone transactions where you are able to mark individual items as shipped, received and accepted.

Type: integer
title

The name of the item being transferred.

Type: string
Minimum Length: 1
Maximum Length: 200
description

A brief description of the item being transferred.

Type: string
Minimum Length: 1
Maximum Length: 500
parent_item_id

Id of the parent item that this entry is related to

Type: integer
reference

This can be used to refer to the item while creating the transaction

Type: string
parent_reference

Used to refer to the parent item for this entity

Type: string
type

The item type - can affect behaviour of the transaction and can also be used to specify party-specific fees.

Type: string

Valid values:
  • domain_name
  • general_merchandise
  • motor_vehicle
  • shipping_fee
inspection_period

The length of the inspection period in seconds. Currently the inspection period must be in whole multiples of days. e.g half a day (43200 seconds) is invalid where as 1 day (86400 seconds) and 2 days (172800 seconds) would be valid.

Type: integer
Minimum Value: 86400
Maximum Value: 2592000
quantity

The number of the item that is being sold. NOTE: this value does not factor into the price and is purely informative. All values shown in the schedules are the total amount, not the unit price.

Type: integer
Minimum Value: 1
Maximum Value: 10000
schedule

The way that we represent monetary amounts.

Type: Array[ModifyTermsSchedule]
fees

The way that we represent fees - the amount, type of fee, and who pays the fee.

Type: Array[ModifyFee]
extra_attributes

Additional attributes relevant to an item

Type: ItemExtraAttributes
visibility

This field contains the visibility object for the item which defines who can see the cost of the item. Note it is only available for broker_fee.

Type: Visibility
status

A group of fields representing actions that have been taken with respect to this item.

Type: ItemStatus
category

The type of category for the item. See the example docs for a list of valid categories based on item type

Type: string
Maximum Length: 128
custom_category

The custom category for the item as set by the user.

Type: string
Maximum Length: 128
shipping_information

The information required for tracking delivery of the item

Type: Array[ShippingInformation]
shipping_type

This signifies the shipping type for general merchandise transactions

Type: string

Valid values:
  • cargo_shipping
  • no_shipping
  • standard_shipping
{
    "description": "johnwick.com",
    "extra_attributes": {
        "concierge": false,
        "with_content": false
    },
    "fees": [
        {
            "amount": "100.00",
            "payer_customer": "john.wick@test.escrow.com",
            "type": "escrow"
        }
    ],
    "id": 1129292,
    "inspection_period": 86400,
    "quantity": 1,
    "schedule": [
        {
            "amount": "1000.00",
            "beneficiary_customer": "keanu.reeves@test.escrow.com",
            "payer_customer": "john.wick@test.escrow.com"
        }
    ],
    "status": {
        "accepted": false,
        "accepted_returned": false,
        "received": true,
        "received_returned": false,
        "rejected": false,
        "rejected_returned": false,
        "shipped": true,
        "shipped_returned": false
    },
    "title": "johnwick.com",
    "type": "domain_name"
}
{
    "description": "johnwick.com",
    "parent_item_id": 1129292,
    "schedule": [
        {
            "amount": "100.00",
            "beneficiary_customer": "keanu.reeves@test.escrow.com",
            "payer_customer": "john.wick@test.escrow.com"
        }
    ],
    "title": "johnwick.com",
    "type": "broker_fee",
    "visibility": {
        "hidden_from": [
            "viggo.tarasov@escrow.com"
        ]
    }
}

Transaction

Property Details
v4_trx_shadow Type: boolean
id

ID for the transaction. When creating a transaction, you should not pass this in as Escrow.com will generate this ID for you.

Type: integer
parties

The list of parties involved in the transaction

Type: Array[Party]
currency

The currency for the transaction. Currently only usd and euro is supported for new transactions.

Type: string
description

This is a brief description of what the transaction is for.

Type: string
Required: Yes
Maximum Length: 256
reference

An external reference to a transaction that can be passed in.

Type: string
Maximum Length: 24
listing_reference

An external reference to an item listing that can be passed in.

Type: string
Maximum Length: 256
creation_date

The date at which the transaction was created. This field will be populated by Escrow.com when you create the transaction, so there is no need to populate it when creating a transaction.

Type: string
close_date

The date at which the transaction was closed. This field will be populated by Escrow.com when the transaction is complete, so there is no need to populate it when creating a transaction.

Type: string
items

The items of the transaction, including transferable and non transferable items. This includes the items being sold, applicable shipping fees, applicable broker fees and applicable partner fees.

Type: Array[Item]
is_cancelled

This signifies if the transaction has been cancelled.

Type: boolean
auction_id

This is a reference to an auction, if the transaction is created from an auction.

Type: integer
is_draft

This signifies if the transaction is a draft. Usually when it is an offer that has not been accepted yet.

Type: boolean
{
    "currency": "usd",
    "description": "Sale of johnwick.com",
    "id": 190202,
    "items": [
        {
            "description": "johnwick.com",
            "extra_attributes": {
                "concierge": false,
                "with_content": false
            },
            "fees": [
                {
                    "amount": "100.00",
                    "payer_customer": "john.wick@test.escrow.com",
                    "type": "escrow"
                }
            ],
            "id": 1129292,
            "inspection_period": 86400,
            "quantity": 1,
            "schedule": [
                {
                    "amount": "1000.00",
                    "beneficiary_customer": "keanu.reeves@test.escrow.com",
                    "payer_customer": "john.wick@test.escrow.com"
                }
            ],
            "status": {
                "accepted": false,
                "accepted_returned": false,
                "received": true,
                "received_returned": false,
                "rejected": false,
                "rejected_returned": false,
                "shipped": true,
                "shipped_returned": false
            },
            "title": "johnwick.com",
            "type": "domain_name"
        }
    ],
    "parties": [
        {
            "agreed": true,
            "customer": "john@wick.com",
            "role": "buyer"
        },
        {
            "agreed": true,
            "customer": "keanu.reeves@test.escrow.com",
            "role": "seller"
        }
    ]
}

TransactionList

This object represents a list of Escrow.com transactions.
Property Details
page

The current page being returned

Type: integer
per_page

The number of transactions listed per page

Type: integer
page_count

The total number of pages available

Type: integer
transactions

A list of transactions as per the provided query

Type: Array[Transaction]
{
    "page": 1,
    "page_count": 1,
    "per_page": 50,
    "transactions": [
        {
            "currency": "usd",
            "description": "Sale of johnwick.com",
            "id": 190202,
            "items": [
                {
                    "description": "johnwick.com",
                    "extra_attributes": {
                        "concierge": false,
                        "with_content": false
                    },
                    "fees": [
                        {
                            "amount": "100.00",
                            "payer_customer": "john.wick@test.escrow.com",
                            "type": "escrow"
                        }
                    ],
                    "id": 1129292,
                    "inspection_period": 86400,
                    "quantity": 1,
                    "schedule": [
                        {
                            "amount": "1000.00",
                            "beneficiary_customer": "keanu.reeves@test.escrow.com",
                            "payer_customer": "john.wick@test.escrow.com"
                        }
                    ],
                    "status": {
                        "accepted": false,
                        "accepted_returned": false,
                        "received": true,
                        "received_returned": false,
                        "rejected": false,
                        "rejected_returned": false,
                        "shipped": true,
                        "shipped_returned": false
                    },
                    "title": "johnwick.com",
                    "type": "domain_name"
                }
            ],
            "parties": [
                {
                    "agreed": true,
                    "customer": "john@wick.com",
                    "role": "buyer"
                },
                {
                    "agreed": true,
                    "customer": "keanu.reeves@test.escrow.com",
                    "role": "seller"
                }
            ]
        }
    ]
}

TransactionCursoredList

This object represents a cursored list of Escrow.com transactions.
Property Details
sort_direction

Query used for the order of sorting

Type: string
next_cursor

A pointer to the start of the next set of transactions

Type: integer
sort_by

Query used for sorting

Type: string
transactions

A list of transactions as per the provided query

Type: Array[Transaction]
limit

Number of transactions queried starting from next_cursor

Type: integer
{
    "limit": 1,
    "next_cursor": 190203,
    "sort_by": "id",
    "sort_direction": "asc",
    "transactions": [
        {
            "currency": "usd",
            "description": "Sale of johnwick.com",
            "id": 190202,
            "items": [
                {
                    "description": "johnwick.com",
                    "extra_attributes": {
                        "concierge": false,
                        "with_content": false
                    },
                    "fees": [
                        {
                            "amount": "100.00",
                            "payer_customer": "john.wick@test.escrow.com",
                            "type": "escrow"
                        }
                    ],
                    "id": 1129292,
                    "inspection_period": 86400,
                    "quantity": 1,
                    "schedule": [
                        {
                            "amount": "1000.00",
                            "beneficiary_customer": "keanu.reeves@test.escrow.com",
                            "payer_customer": "john.wick@test.escrow.com"
                        }
                    ],
                    "status": {
                        "accepted": false,
                        "accepted_returned": false,
                        "received": true,
                        "received_returned": false,
                        "rejected": false,
                        "rejected_returned": false,
                        "shipped": true,
                        "shipped_returned": false
                    },
                    "title": "johnwick.com",
                    "type": "domain_name"
                }
            ],
            "parties": [
                {
                    "agreed": true,
                    "customer": "john@wick.com",
                    "role": "buyer"
                },
                {
                    "agreed": true,
                    "customer": "keanu.reeves@test.escrow.com",
                    "role": "seller"
                }
            ]
        }
    ]
}

PaymentMethod

This represents a payment method that is available on a transaction.
Property Details
type

The payment method type.

Type: string

Valid values:
  • check
  • credit_card
  • direct_debit
  • paypal
  • poli
  • wire_transfer
total

The total amount the buyer is required to pay in order to fund the transaction using this payment method.

Type: number
payment_gateway Type: string
conditions

Conditions that need to be satisfied.

Type: Array[string]
fee_for_outstanding_balance

The additional fee the buyer is required to pay in order to fund the transaction's outstanding balance using this payment method.

Type: number
fees

The way that we represent fees - the amount and the type of fee.

Type: Array[object]
{
    "conditions": [
        "verification_required"
    ],
    "total": "200.20",
    "type": "credit_card"
}

PaymentMethods

This contains a list of available payment methods on a transaction.
Property Details
available_payment_methods

The available payment methods for a transaction.

Type: Array[PaymentMethod]
conditionally_available_payment_methods

Payment methods will become available when specific conditions are satisfied.

Type: Array[PaymentMethod]
total_without_payment_fee

The total cost before applying fees related to the payment method selected

Type: number
selected_payment_method

The selected payment method for the transaction

Type: string
{
    "available_payment_methods": [
        {
            "total": "2300.00",
            "type": "credit_card"
        },
        {
            "total": "2275.00",
            "type": "wire_transfer"
        }
    ],
    "conditionally_available_payment_methods": [
        {
            "conditions": [
                "verification_required"
            ],
            "total": "531.20",
            "type": "paypal"
        }
    ],
    "total_without_payment_fee": "500.00"
}

RejectInformation

Property Details
rejection_reason

The reason for rejecting the item

Type: string
{
    "rejection_reason": "Not happy with item"
}

CancelInformation

Property Details
flow

The type of draft upgrade desired

Type: string
Required: Yes

Valid values:
  • create
{
    "flow": "create"
}

ModifyPartyInformationParty

Property Details
id

The unique Id for this party in this transaction

Type: integer
Required: Yes
customer

The email address of the party.

Type: string
Required: Yes
{
    "customer": "john.wick@test.escrow.com",
    "id": 123
}

ModifyPartyInformation

Property Details
party

The party object, supplying any field that should be modified

Type: ModifyPartyInformationParty
Required: Yes
{
    "party": {
        "customer": "john.wick@test.escrow.com",
        "id": 123
    }
}

TransactionAction

TransactionAction is the body that is passed to the Escrow.com API when performing an action on a transaction or item.
Property Details
action Type: string
Required: Yes
Valid values:
accept accept_return agree authenticator_rejects batch cancel float_cancel float_release modify modify_party modify_terms receive receive_return reject reject_return ship ship_return update_tracking upgrade_draft
action_to Type: string

Valid values:
  • buyer
  • seller
batch_information

Information relevant to the batch action

Type: object
shipping_information

Information relevant to the ship and ship_return actions

Type: ShippingInformation
Required: No
cancel_information

Additional information for the cancellation of the transaction

Type: CancelInformation
Required: No
rejection_information

Information describing why items were rejected.

Type: RejectInformation
Required: No
reject_return_information

Information describing why rejected items were returned.

Type: RejectInformation
Required: No
upgrade_draft_information

Information pertinent to upgrading a draft transaction

Type: CancelInformation
Required: No
modify_party_information

Information relevant to modifying a party

Type: ModifyPartyInformation
Required: No
modify_terms_information

Information relevant to modifying a transaction

Type: object
transaction

Information relevant to modifying a transaction

Type: object
{
    "action": "agree"
}
{
    "action": "accept"
}
{
    "action": "accept_return"
}
{
    "action": "receive"
}
{
    "action": "receive_return"
}
{
    "action": "reject"
}
{
    "action": "reject_return"
}
{
    "action": "ship",
    "shipping_information": {
        "tracking_information": {
            "carrier": "USPS",
            "tracking_id": "EA 999 999 999 US"
        }
    }
}
{
    "action": "ship",
    "shipping_information": {
        "authorization_type": "authorization_code"
    }
}
{
    "action": "ship_return",
    "shipping_information": {
        "tracking_information": {
            "carrier": "USPS",
            "tracking_id": "EA 999 999 999 US"
        }
    }
}
{
    "action": "ship_return",
    "shipping_information": {
        "authorization_type": "authorization_code"
    }
}

PaymentMethodInput

This object is passed into the payment_method endpoint, allowing the user to select how they wish to fund a transaction.
Property Details
wire_reference

The wire reference number (if paid via wire)

Type: string
return_url

The URL to return the user to after the transaction has been funded. This is only used with the paypal and credit_card payment methods.

Type: string
payment_method_name

The payment method you want to select

Type: string

Valid values:
  • check
  • credit_card
  • direct_debit
  • paypal
  • poli
  • wire_transfer
{
    "wire_reference": "0980810982"
}
{
    "return_url": "https://www.google.com/checkout"
}

PaymentMethodRedirectInput

This object is passed into the payment_method endpoint, allowing the user to select how they wish to fund a transaction.
Property Details
redirect_type

Indicates whether the redirect to return_url will" happen automatically or manually via CTA click.

Type: string

Valid values:
  • automatic
  • manual
return_url

The URL to return the user to after the transaction has been funded. This is only used with the paypal and credit_card payment methods.

Type: string
{
    "return_url": "https://www.google.com/checkout"
}

BuyerPayment

Property Details
bank_country

2 Letter code of the country of the bank (if paid via wire)

Type: string
Valid values:
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW
bank_name

The name of the bank the buyer will be paying through (if paid via wire)

Type: string
account_name

The name of the account holder paying to Escrow.com (if paid via wire)

Type: string
third_party_email

The email of the third party account paying to Escrow

Type: string
bank_state

State code (ISO 3166-2) of the bank (if paid via wire)

Type: string

LandingPage

This object provides details about what URL to send a user to.
Property Details
landing_page

The URL to send the user to

Type: string
{
    "landing_page": "https://my.escrow.com/transaction.asp?TID=29"
}

WireTransferDetails

Bank account details that can be used to make wire transfers to Escrow.com
Property Details
routing_number

Routing number to be used in the wire transfer. Applicable to USD wire transfers

Type: string
sort_code

A number to identify the bank and branch in theUnited Kingdom and Ireland.

Type: string
credit_account_number

Number of the credit account to make wire transfers to

Type: string
bank_name

Bank name of the account.

Type: string
Required: Yes
intermediary_bank_name

Name of intermediary bank. To be used for Euro wire transfers

Type: string
bank_number

Also known as institution number, a bank number is used toidentify a certain bank

Type: string
credit_account_name

Name of the credit account to make wire transfers to

Type: string
transit_number

A number used in Canada for banks to identify their branches

Type: string
bank_iban

The international bank account number, or IBAN

Type: string
structured_bank_address

The structured form of the bank address.

Type: Address
bsb

A number to identify the bank and branch in Australia.

Type: string
wire_beneficiary_address

Address of the wire beneficiary bank.

Type: string
swift_code

SWIFT code of the bank.

Type: string
Required: Yes
intermediary_bank_swift_code

SWIFT code of intermediary bank. To be used for Euro wire transfers

Type: string
bank_address

Address of the bank. Applicable to USD wire transfers.

Type: string
additional_instructions

Additional instructions for making the wire transfer.

Type: string
Required: Yes
bank_account_number

Bank account number to make wire transfer to. To be used for Eurowire transfers

Type: string
structured_wire_ben_address

The structured form of the wire beneficiary bank address.

Type: Address
{
    "additional_instructions": "Reference Escrow Transaction #12345",
    "bank_address": "420 Montgomery St., San Francisco, CA 94104",
    "bank_name": "Wells Fargo Bank, N.A",
    "credit_account_name": "Internet Escrow Services Inc",
    "credit_account_number": "7101167844",
    "routing_number": "121000248",
    "structured_bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "420 Montgomery Street",
        "post_code": "94104",
        "state": "CA"
    },
    "swift_code": "WFBIUS6S"
}
{
    "additional_instructions": "Reference Escrow Transaction #12345",
    "bank_account_number": "94002528",
    "bank_name": "City National Bank, Los Angeles, California USA",
    "intermediary_bank_name": "Citibank N.A., London, England, U.K",
    "intermediary_bank_swift_code": "CITIGB2L",
    "structured_bank_address": {
        "city": "London",
        "country": "UK",
        "line1": "Canada Square",
        "line2": "Canary Wharf",
        "post_code": "E145LB"
    },
    "swift_code": "CINAUS6L"
}

CheckDetails

Bank account details that can be used to make check payments to Escrow.com
Property Details
structured_check_ben_address

The structured form of the check beneficiary bank address.

Type: Address
check_beneficiary_address

Address of the check beneficiary bank.

Type: string

TransactionTimelineNotes

A timeline of events that has happened to the transaction.
Property Details
date_added

The date the timeline entry was generated.

Type: string
Required: Yes
notes

Describes an event that has happened within the transaction.

Type: string
Required: Yes

PartnerTransactionGetParams

Property Details
first_time_either Type: boolean
customer_ids Type: Array[integer]
sort_by Type: string

Valid values:
  • id
ids Type: Array[integer]
sort_direction Type: string

Valid values:
  • asc
  • desc
next_cursor Type: integer
first_time_buyer Type: boolean
initiation_start_date Type: string
days_taken Type: integer
end_condition Type: integer
Valid values:
0 1 3 5 6 9 10 15 18 19 20 21 22 23 25 26 30 31 32 35 40 43 45 46 50 55 60 65 66 67 68 70 75 80 85
status_code Type: integer
Valid values:
0 1 3 5 6 9 10 15 18 19 20 21 22 23 25 26 30 31 32 35 40 43 45 46 50 55 60 65 66 67 68 70 75 80 85
show_cancelled Type: boolean
first_time_seller Type: boolean
max_amount Type: number
sources Type: Array[string]
exclude_draft Type: boolean
min_amount Type: number
status Type: string

Valid values:
  • blocked
  • completed
  • ongoing
limit Type: integer
start_condition Type: integer
Valid values:
0 1 3 5 6 9 10 15 18 19 20 21 22 23 25 26 30 31 32 35 40 43 45 46 50 55 60 65 66 67 68 70 75 80 85
closed_start_date Type: string
closed_end_date Type: string
initiation_end_date Type: string

V4ExtraDetailsArgsSchema

Property Details
fields Type: Array[string]

GenericError

Property Details
code

A code identifying the type of error

Type: string

GenericErrorResponse

Property Details
errors

A list of errors

Type: Array[GenericError]

SingleErrorResponse

A SingleErrorResponse object is used to return error output when only a single error, for instance, when a particular action is forbidden.
Property Details
error

A description of the error that occurred.

Type: string
{
    "error": "An error has occurred."
}

ApiKeyErrors

ApiKeyErrors shows the errors that occurred on the fields of a created API key.
Property Details
name

Errors that occurred on the name field.

Type: Array[string]
{
    "name": [
        "Name field required for creating an API key"
    ]
}

ApiKeyValidationResponse

ApiKeyValidationResponse is used to return error output when validating a created API key.
Property Details
errors

Errors encountered in validating the api key body

Type: ApiKeyErrors
{
    "errors": {
        "name": [
            "Name field required for creating an API key"
        ]
    }
}

WebhookErrors

WebhookErrors shows the errors that occurred on the fields of a created webhook.
Property Details
url

Errors that occurred on the url field.

Type: Array[string]
{
    "url": [
        "An active webhook with this url already exists"
    ]
}

WebhookValidationResponse

WebhookValidationResponse is used to return error output when validating a created webhook.
Property Details
errors

Errors encountered in validating the webhook body

Type: WebhookErrors
{
    "errors": {
        "url": [
            "An active webhook with this url already exists"
        ]
    }
}

CustomerErrors

CustomerErrors shows the errors that occurred on the fields of a created customer.
Property Details
email

Errors that occurred on the email field.

Type: Array[string]
name_and_dob

Errors that occurred on the name fields or the dob field.

Type: Array[string]
company

Errors that occurred in the company fieldset

Type: Array[string]
{
    "email": [
        "Email address must be set"
    ]
}

CustomerValidationResponse

CustomerValidationResponse is used to return error output when validating a created customer.
Property Details
errors

Errors encountered in validating the customer body

Type: CustomerErrors
{
    "errors": {
        "email": [
            "Email address must be set"
        ]
    }
}

ExtraAttributesErrors

ExtraAttributesErrors shows the errors that occurred on the fields of an item's extra_attributes object.
Property Details
with_content

Errors that occurred on the with_content field.

Type: Array[string]
lien_holder_payoff

Errors that occurred on the lien_holder_payoff field.

Type: Array[string]
all

Errors that occurred on the extra_attributes object overall.

Type: Array[string]
concierge

Errors that occurred on the concierge field.

Type: Array[string]
title_collection

Errors that occurred on the title_collection field.

Type: Array[string]
make

Errors that occurred on the make field.

Type: Array[string]
model

Errors that occurred on the model field.

Type: Array[string]
year

Errors that occurred on the year field.

Type: Array[string]
{
    "year": [
        "year is a required field for motor_vehicle extra_attributes"
    ]
}

ItemValidationErrors

ItemValidationErrors shows the errors that occurred on the fields of an item within a created transaction.
Property Details
description

Errors that occurred on the description field.

Type: Array[string]
extra_attributes

Errors that occurred on the extra_attributes object.

Type: ExtraAttributesErrors
fees

An indexed list of validation errors for each fee item.

Type: string
inspection_period

Errors that occurred on the inspection_period field.

Type: Array[string]
visibility

Errors that occured on the visibility field.

Type: Array[string]
schedule

An indexed list of validation errors for each schedule item.

Type: string
title

Errors that occurred on the title field.

Type: Array[string]
type

Errors that occurred on the type field.

Type: Array[string]
category

Errors that occured on the category field

Type: Array[string]
custom_category

Errors that occured on the custom_category field

Type: Array[string]
{
    "extra_attributes": {
        "year": [
            "year is a required field for motor_vehicle extra_attributes"
        ]
    }
}

TransactionValidationErrors

TransactionValidationErrors shows the errors that occurred on the fields of a created transaction.
Property Details
parties

An indexed list of validation errors for each party.

Type: string
items

An indexed list of validation errors for each item.

Type: string
reference

A list of errors on the reference field

Type: string
currency

A list of errors on the currency item

Type: Array[string]
{
    "items": {
        "0": {
            "extra_attributes": {
                "year": [
                    "year is a required field for motor_vehicle extra_attributes"
                ]
            }
        }
    },
    "parties": {
        "0": [
            "Transaction must have 1 seller"
        ]
    }
}

TransactionValidationResponse

TransactionValidationResponse is used to return error output when validating a created transaction.
Property Details
errors

Errors encountered in validating the transaction body

Type: TransactionValidationErrors
{
    "errors": {
        "items": {
            "0": {
                "type": [
                    "Cannot mix general_merchandise, domain_name, motor_vehicle and milestone items"
                ]
            },
            "1": {
                "extra_attributes": {
                    "year": [
                        "year is a required field for motor_vehicle extra_attributes"
                    ]
                },
                "fees": {
                    "0": [
                        "percentage fields must all sum to 1.0",
                        "All values for payer_customer must be specified in transaction parties. Partners cannot pay the escrow fee"
                    ],
                    "1": [
                        "percentage fields must all sum to 1.0"
                    ],
                    "all": [
                        "Fee schedule must be the same for all items"
                    ]
                },
                "inspection_period": [
                    "Inspection periods must match for non-milestone transactions"
                ],
                "type": [
                    "Cannot mix general_merchandise, domain_name, motor_vehicle and milestone items"
                ]
            },
            "2": {
                "schedule": {
                    "0": [
                        "Broker fee beneficiary must be a broker"
                    ]
                }
            }
        },
        "parties": {
            "0": [
                "Transaction must have 1 seller"
            ]
        }
    }
}

TaxNumberValidationErrors

Property Details
type

A list of errors on the type column

Type: Array[string]
number

A list of errors on the number column

Type: Array[string]

TaxNumberValidationResponse

Property Details
errors

Errors encountered in validating the tax number

Type: TaxNumberValidationErrors

BatchActionValidationResponse

Property Details
actions Type: Array[object]
transaction

The current state of the transaction

Type: Transaction

V4CustomerKYCValidationErrors

Property Details
account Type: Array[string]
documents Type: Array[string]

IntermediaryBank

This represents the details about an intermediary bank.
Property Details
bank_aba_routing_number

The aba routing number of the intermediary bank account.

Type: string
bank_name

The name of the intermediary bank.

Type: string
member_id

The member ID for the bank

Type: string
clearing_system_code

The type of clearing system used for the member id given

Type: string

Valid values:
  • USABA
bank_address Type: Address
bank_swift_code

The SWIFT code identifying the intermediary bank.

Type: string
bank_account_number

The account number of the intermediary bank account.

Type: string

DisbursementMethod

This represents bank account details for funds to be disbursed to.
Property Details
id

The id of the disbursement method. This is used when selecting a previously saved disbursement method for disbursement.

Type: integer
account_name

The name of the account to which money will be disbursed.

Type: string
account_type

The type of the account to which money will be disbursed.

Type: string

Valid values:
  • checking
  • savings
bank_aba_routing_number

The aba routing number of the bank account to which money will be disbursed.

Type: string
bank_account_number

The account number of the account to which money will be disbursed.

Type: string
bank_address Type: Address
bank_branch_number

The branch number of the account to which money will be disbursed.

Type: string
bank_iban

The international bank account number of the account to which money will be disbursed.

Type: string
bank_name

The name of the bank under which the disbursement details fall.

Type: string
bank_swift_code

The SWIFT code identifying the bank to which disbursement is to be made.

Type: string
bank_sort_code

The IRC Sort Code for the disbursement bank account

Type: string
international_routing_code

The Internation Routing code for the bank to which disbursement is to be made.

Type: string
beneficiary_address Type: Address
currency

The currency accepted for the specified disbursement method.

Type: string

Valid values:
  • aud
  • cad
  • euro
  • gbp
  • usd
intermediary_bank Type: IntermediaryBank
intermediary_banks Type: Array[IntermediaryBank]
additional_information

Any additional field required for the account

Type: string
clearing_system_code

The type of clearing system used for the member id given

Type: string
Valid values:
ATBLZ AUBSB BRSTN CACPA CHBCC DEBLZ ESNCC GBDSC INFSC ITNCC NZNCC USABA
member_id

The member ID for the bank

Type: string
type

The type of the disbursement method. Determines the associated disbursement fee.

Type: string

Valid values:
  • ach
  • wire_transfer
  • wire_transfer_international
{
    "account_name": "John Smith",
    "account_type": "savings",
    "bank_aba_routing_number": "12345678",
    "bank_account_number": "1929231",
    "bank_address": {
        "city": "San Francisco",
        "state": "CA"
    },
    "bank_name": "Amazing Savings Bank of California",
    "currency": "usd",
    "id": 55523,
    "type": "ach"
}
{
    "account_name": "John Smith",
    "bank_aba_routing_number": "2923031",
    "bank_account_number": "2303120",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "post_code": "292910",
        "state": "CA"
    },
    "bank_branch_number": "9292932",
    "bank_iban": "2929292",
    "bank_name": "Amazing Savings Bank of California",
    "bank_swift_code": "29292902",
    "beneficiary_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1829 West Lane",
        "line2": "Apartment 301020",
        "post_code": "10203",
        "state": "CA"
    },
    "currency": "usd",
    "id": 59912,
    "intermediary_bank": {
        "bank_aba_routing_number": "290303030",
        "bank_account_number": "202001",
        "bank_address": {
            "city": "San Francisco",
            "line1": "310 Montgomery St",
            "post_code": "292910",
            "state": "CA"
        },
        "bank_name": "Not-so-amazing Bank",
        "bank_swift_code": "199292"
    },
    "international_routing_code": "2901011",
    "type": "wire"
}

DisbursementMethodInput

Property Details
id

The id of the disbursement method. This is used when selecting a previously saved disbursement method for disbursement.

Type: integer
account_name

The name of the account to which money will be disbursed.

Type: string
account_type

The type of the account to which money will be disbursed.

Type: string

Valid values:
  • checking
  • savings
bank_aba_routing_number

The aba routing number of the bank account to which money will be disbursed.

Type: string
bank_account_number

The account number of the account to which money will be disbursed.

Type: string
bank_address Type: Address
bank_branch_number

The branch number of the account to which money will be disbursed.

Type: string
bank_iban

The international bank account number of the account to which money will be disbursed.

Type: string
bank_name

The name of the bank under which the disbursement details fall.

Type: string
bank_swift_code

The SWIFT code identifying the bank to which disbursement is to be made.

Type: string
bank_sort_code

The IRC Sort Code for the disbursement bank account

Type: string
international_routing_code

The Internation Routing code for the bank to which disbursement is to be made.

Type: string
beneficiary_address Type: Address
currency

The currency accepted for the specified disbursement method.

Type: string

Valid values:
  • aud
  • cad
  • euro
  • gbp
  • usd
intermediary_bank Type: IntermediaryBank
intermediary_banks Type: Array[IntermediaryBank]
additional_information

Any additional field required for the account

Type: string
clearing_system_code

The type of clearing system used for the member id given

Type: string
Valid values:
ATBLZ AUBSB BRSTN CACPA CHBCC DEBLZ ESNCC GBDSC INFSC ITNCC NZNCC USABA
member_id

The member ID for the bank

Type: string
type

The type of the disbursement method. Determines the associated disbursement fee.

Type: string

Valid values:
  • ach
  • wire_transfer
  • wire_transfer_international
{
    "id": 12345
}
{
    "account_name": "John Smith",
    "account_type": "savings",
    "bank_aba_routing_number": "123456789",
    "bank_account_number": "56789123",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "state": "CA"
    },
    "bank_name": "Bank of Wyong",
    "currency": "usd",
    "type": "ach"
}
{
    "account_name": "John Smith",
    "bank_aba_routing_number": "2923031",
    "bank_account_number": "2303120",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "post_code": "292910",
        "state": "CA"
    },
    "bank_name": "Amazing Savings Bank of California",
    "beneficiary_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1829 West Lane",
        "line2": "Apartment 301020",
        "post_code": "10203",
        "state": "CA"
    },
    "currency": "usd",
    "intermediary_bank": {
        "bank_aba_routing_number": "290303030",
        "bank_account_number": "202001",
        "bank_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "310 Montgomery St",
            "post_code": "292910",
            "state": "CA"
        },
        "bank_name": "Not-so-amazing Bank",
        "bank_swift_code": "199292"
    },
    "type": "wire_transfer"
}
{
    "account_name": "John Smith",
    "bank_account_number": "2303120",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "post_code": "292910",
        "state": "CA"
    },
    "bank_name": "Amazing Savings Bank of California",
    "bank_swift_code": "2923031",
    "beneficiary_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1829 West Lane",
        "line2": "Apartment 301020",
        "post_code": "10203",
        "state": "CA"
    },
    "currency": "usd",
    "intermediary_bank": {
        "bank_aba_routing_number": "290303030",
        "bank_account_number": "202001",
        "bank_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "310 Montgomery St",
            "post_code": "292910",
            "state": "CA"
        },
        "bank_name": "Not-so-amazing Bank",
        "bank_swift_code": "199292"
    },
    "type": "wire_transfer"
}
{
    "account_name": "John Smith",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "post_code": "292910",
        "state": "CA"
    },
    "bank_iban": "2929292",
    "bank_name": "Amazing Savings Bank of California",
    "bank_swift_code": "2923031",
    "beneficiary_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1829 West Lane",
        "line2": "Apartment 301020",
        "post_code": "10203",
        "state": "CA"
    },
    "currency": "usd",
    "intermediary_bank": {
        "bank_aba_routing_number": "290303030",
        "bank_account_number": "202001",
        "bank_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "310 Montgomery St",
            "post_code": "292910",
            "state": "CA"
        },
        "bank_name": "Not-so-amazing Bank",
        "bank_swift_code": "199292"
    },
    "type": "wire_transfer"
}
{
    "account_name": "John Smith",
    "bank_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "380 Montgomery St",
        "post_code": "292910",
        "state": "CA"
    },
    "bank_name": "Amazing Savings Bank of California",
    "bank_swift_code": "2923031",
    "beneficiary_address": {
        "city": "San Francisco",
        "country": "US",
        "line1": "1829 West Lane",
        "line2": "Apartment 301020",
        "post_code": "10203",
        "state": "CA"
    },
    "currency": "usd",
    "intermediary_bank": {
        "bank_aba_routing_number": "290303030",
        "bank_account_number": "202001",
        "bank_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "310 Montgomery St",
            "post_code": "292910",
            "state": "CA"
        },
        "bank_name": "Not-so-amazing Bank",
        "bank_swift_code": "199292"
    },
    "international_routing_code": "2901011",
    "type": "wire_transfer"
}

AvailableDisbursementMethod

Property Details
type

The type of the disbursement method. Determines the associated disbursement fee.

Type: string

Valid values:
  • ach
  • wire_transfer
total

Total amount to be disbursed from this transaction

Type: number
{
    "total": "1890.00",
    "type": "wire_transfer"
}
{
    "total": "1895.00",
    "type": "ach"
}
{
    "total": "1895.00",
    "type": "wire_transfer_international"
}

DisbursementMethods

This object lists the disbursement methods available on a transaction. It also contains the disbursement method you have selected.
Property Details
available_disbursement_methods

A list of available disbursement method types available for a transaction

Type: Array[AvailableDisbursementMethod]
saved_disbursement_methods

A list of saved disbursement methods available for a transaction

Type: Array[DisbursementMethod]
selected_disbursement_method

The selected disbursement method for the transaction. There will only be one disbursement method selected, even for milestone transactions.

Type: DisbursementMethod
available_currencies

A list of available currencies for disbursement

Type: Array[string]
{
    "available_disbursement_methods": [
        {
            "total": "1890.00",
            "type": "wire_transfer"
        },
        {
            "total": "1895.00",
            "type": "wire_transfer_international"
        },
        {
            "total": "1895.00",
            "type": "ach"
        }
    ],
    "saved_disbursement_methods": [
        {
            "account_name": "John Wick",
            "bank_aba_routing_number": "219291291",
            "bank_address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "100 Montgomery Street",
                "post_code": "94104"
            },
            "bank_name": "American Savings Bank",
            "bank_swift_code": "SI2920",
            "beneficiary_address": {},
            "currency": "usd",
            "id": 129292,
            "type": "wire_transfer"
        }
    ],
    "selected_disbursement_method": null
}
{
    "available_disbursement_methods": [
        {
            "total": "1890.00",
            "type": "wire_transfer"
        },
        {
            "total": "1895.00",
            "type": "wire_transfer_international"
        },
        {
            "total": "1895.00",
            "type": "ach"
        }
    ],
    "saved_disbursement_methods": [
        {
            "account_name": "John Wick",
            "bank_aba_routing_number": "219291291",
            "bank_address": {
                "city": "San Francisco",
                "country": "US",
                "line1": "100 Montgomery Street",
                "post_code": "94104"
            },
            "bank_name": "American Savings Bank",
            "bank_swift_code": "SI2920",
            "beneficiary_address": {},
            "currency": "usd",
            "id": 129292,
            "type": "wire_transfer"
        }
    ],
    "selected_disbursement_method": {
        "account_name": "John Wick",
        "bank_aba_routing_number": "219291291",
        "bank_address": {
            "city": "San Francisco",
            "country": "US",
            "line1": "100 Montgomery Street",
            "post_code": "94104"
        },
        "bank_name": "American Savings Bank",
        "bank_swift_code": "SI2920",
        "beneficiary_address": {},
        "currency": "usd",
        "id": 129292,
        "type": "wire_transfer"
    }
}

ApiKey

This object represents a single API key. It is returned both when you create an API key and when you list your own API keys. Please note that because the API keys are stored in a non-reversible format, the API key is only available on creation. It cannot be retrieved afterwards.
Property Details
id

The API key's id

Type: integer
name

A name given to the API key.

Type: string
Required: Yes
key

The full key - only available on creation.

Type: string
date_created

The key's creation date.

Type: string
is_active

Whether or not the key is currently active (usable).

Type: boolean
last_four_characters

The last 4 characters of the original full key.

Type: string
{
    "date_created": "2017-01-01T00:00:00+00:00",
    "id": 192,
    "is_active": true,
    "key": "113;AktWIALNKLrLR30BmCeEHnDAK3RAT0VpK",
    "last_four_characters": "0VpK",
    "name": "Production"
}

ApiKeys

This object is returned when listing the API keys on your account.
Property Details
api_keys

A list of API keys.

Type: Array[ApiKey]
{
    "api_keys": [
        {
            "date_created": "2017-01-01T00:00:00+00:00",
            "id": 192,
            "is_active": true,
            "key": "112;AktWI9898928928skjdlksjdkljDAK3R2912",
            "last_four_characters": "2912",
            "name": "Worker"
        },
        {
            "date_created": "2017-01-01T00:00:00+00:00",
            "id": 193,
            "is_active": true,
            "key": "113;AktWIALNKLrLR30BmCeEHnDAK3RAT0VpK",
            "last_four_characters": "0VpK",
            "name": "App"
        }
    ]
}

Webhook

Property Details
id

The id of the webhook, may be used for deletion. This is not required when creating a webhook.

Type: integer
url

The url that will receive events from Escrow.com

Type: string
Required: Yes
{
    "id": 219292,
    "url": "http://www.example.com/webhook"
}

Webhooks

This object contains a list of webhooks
Property Details
webhooks

A list of active webhooks.

Type: Array[Webhook]
{
    "webhooks": [
        {
            "id": 29292,
            "url": "https://www.example.com/webhook1"
        },
        {
            "id": 2020182,
            "url": "https://www.example.com/webhook2"
        }
    ]
}

CustomerAddress

Property Details
line1

The first line of the address

Type: string
line2

The second line of the address

Type: string
city

The city of the address

Type: string
state

The state of the address

Type: string
country

The country of the address as an ISO 3166-1 alpha-2 code

Type: string
Valid values:
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW
post_code

The post code or the zip code.

Type: string
{
    "city": "San Francisco",
    "country": "US",
    "line1": "600 Montgomery Street",
    "line2": "Apartment 20",
    "post_code": "94104",
    "state": "California"
}

CustomerTaxNumbers

This object represents a tax number
Property Details
id

Tax number ID. May be used for editing or deletion

Type: integer
type Type: string

Valid values:
  • vat
number

The tax number of the type specified in the type field

Type: string
{
    "id": 123,
    "number": "FR03512803495",
    "type": "vat"
}

CustomerVerification

Property Details
extended

The customer's extended kyc verification details

Type: CustomerVerification
company

The customer's company verification details

Type: CustomerVerification
personal

The customer's personal verification details

Type: CustomerVerification

ElectronicVerificationStatus

Property Details
documents_supported Type: Array[string]
available Type: boolean

CustEmailVerificationSchema

Property Details
verified Type: boolean
date_added_utc Type: string

CustomerCompany

Property Details
company_name Type: string
address

The company's address

Type: CustomerAddress

CustomerPartnerView

Property Details
id

The customer's id.

Type: integer
first_name

The customer's first name.

Type: string
middle_name

The customer's middle name.

Type: string
last_name

The customer's last name.

Type: string
username

The customer's username.

Type: string
display_name

The display name is what is shown to other parties during a transaction. Please note this will only be shown in the initial stages of a transaction.

Type: string
disbursement_methods

Details via which money can be disbursed to the customer

Type: Array[DisbursementMethod]
address

The customer's address.

Type: CustomerAddress
email

The customer's email address.

Type: string
electronic_verification

The customer's electronic verification eligibility.

Type: ElectronicVerificationStatus
verification

The customer's verification status.

Type: CustomerVerification
company

The company the customer is acting as.

Type: CustomerCompany
{
    "address": {
        "city": "San Francisco",
        "country": "United States",
        "line1": "1234 Street Road",
        "post_code": "94104",
        "state": "CA"
    },
    "disbursement_methods": [
        {
            "account_name": "John Wick",
            "account_type": "savings",
            "bank_aba_routing_number": "123456789",
            "bank_account_number": "123456789",
            "bank_address": {
                "city": "San Francisco",
                "state": "CA"
            },
            "bank_name": "Bank of Coffee",
            "currency": "usd",
            "id": 35147,
            "type": "ach"
        }
    ],
    "email": "john.wick@test.escrow.com",
    "first_name": "John",
    "id": 900000,
    "last_name": "Wick",
    "middle_name": "Coffee",
    "username": "John Wick Domains",
    "verification": {
        "company": {
            "status": "not_verified"
        },
        "personal": {
            "status": "verified"
        }
    }
}

Customer

Property Details
id

The customer's id.

Type: integer
first_name

The customer's first name.

Type: string
middle_name

The customer's middle name.

Type: string
last_name

The customer's last name.

Type: string
username

The customer's username.

Type: string
display_name

The display name is what is shown to other parties during a transaction. Please note this will only be shown in the initial stages of a transaction.

Type: string
date_of_birth

The customer's date of birth.

Type: string
phone_number

The customer's phone number.

Type: string
disbursement_methods

Details via which money can be disbursed to the customer

Type: Array[DisbursementMethod]
address

The customer's address.

Type: CustomerAddress
email

The customer's email address.

Type: string
webhooks

A list of active webhooks.

Type: Array[Webhook]
tax_numbers

A list of tax numbers

Type: Array[CustomerTaxNumbers]
electronic_verification

The customer's electronic verification eligibility.

Type: ElectronicVerificationStatus
verification

The customer's verification status.

Type: CustomerVerification
company

The company the customer is acting as.

Type: CustomerCompany
shipping_address

The customer's shipping address.

Type: CustomerAddress
customer_email_verification

The customer's email verification status.

Type: CustEmailVerificationSchema
{
    "address": {
        "city": "San Francisco",
        "country": "United States",
        "line1": "1234 Street Road",
        "post_code": "94104",
        "state": "CA"
    },
    "date_of_birth": "1980-12-30T00:00:00",
    "disbursement_methods": [
        {
            "account_name": "John Wick",
            "account_type": "savings",
            "bank_aba_routing_number": "123456789",
            "bank_account_number": "123456789",
            "bank_address": {
                "city": "San Francisco",
                "state": "CA"
            },
            "bank_name": "Bank of Coffee",
            "currency": "usd",
            "id": 35147,
            "type": "ach"
        }
    ],
    "email": "john.wick@test.escrow.com",
    "first_name": "John",
    "id": 900000,
    "last_name": "Wick",
    "middle_name": "Coffee",
    "phone_number": "+104433221111",
    "tax_numbers": [
        {
            "id": 123,
            "number": "FR03512803495",
            "type": "vat"
        }
    ],
    "username": "John Wick Domains",
    "verification": {
        "company": {
            "status": "not_verified"
        },
        "personal": {
            "status": "verified"
        }
    },
    "webhooks": [
        {
            "id": 7,
            "url": "https://www.escrow.com/webhook"
        }
    ]
}

CustomerCursoredList

This object represents a cursored list of Escrow.com customers.
Property Details
sort_direction

Query used for the order of sorting

Type: string
next_cursor

A pointer to the start of the next set of customers

Type: integer
sort_by

Query used for sorting

Type: string
limit

Number of customers queried starting from next_cursor

Type: integer
customers

A list of customers as per the provided query

Type: Array[CustomerPartnerView]
{
    "customers": [
        {
            "address": {
                "city": "San Francisco",
                "country": "United States",
                "line1": "1234 Street Road",
                "post_code": "94104",
                "state": "CA"
            },
            "disbursement_methods": [
                {
                    "account_name": "John Wick",
                    "account_type": "savings",
                    "bank_aba_routing_number": "123456789",
                    "bank_account_number": "123456789",
                    "bank_address": {
                        "city": "San Francisco",
                        "state": "CA"
                    },
                    "bank_name": "Bank of Coffee",
                    "currency": "usd",
                    "id": 35147,
                    "type": "ach"
                }
            ],
            "email": "john.wick@test.escrow.com",
            "first_name": "John",
            "id": 900000,
            "last_name": "Wick",
            "middle_name": "Coffee",
            "username": "John Wick Domains"
        }
    ],
    "limit": 1,
    "next_cursor": 900001,
    "sort_by": "id",
    "sort_direction": "asc"
}

PartnerCustomerListGetParams

Property Details
sort_direction Type: string

Valid values:
  • asc
  • desc
next_cursor Type: integer
verification_status Type: Array[string]
sort_by Type: string

Valid values:
  • id
country Type: string
limit Type: integer
ids Type: Array[integer]

PartnerCustomerGetParams

Property Details
customer_id

The customer's id.

Type: integer
party_id

The customer's party id.

Type: integer

CustomerCountryIdentification

Property Details
field

The identification document field to be updated.

Type: string
country

The country of the address as an ISO 3166-1 alpha-2 code

Type: string
Valid values:
AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW
type