API Documentation

API Basics

The Escrow.com API allows you to create transactions between yourself and another party, or between two other parties. The API also allows you to update details on your account, such as setting your disbursement method.

Base URL

All URLs referenced in the documentation have the following base url: https://api.escrow.com/2017-09-01/The Escrow.com API is served over HTTPS and unencrypted HTTP connections are not supported.

Escrow.com also provides a sandbox environment that you can use for development and testing. This environment acts the same way as production. All user accounts, passwords and transactions are independent of the production environment. If you are using the Escrow.com API within the sandbox environment, your base URL will be https://api.escrow-sandbox.com/2017-09-01/

Authentication

The Escrow.com API supports basic authentication as defined in RFC2617. There are two supported methods for authentication, using your username and password and using API keys. While using a user name and password allows you to start using the API immediately, all of the examples in the documentation are using API keys. We recommend that users switch to using API keys in production before deploying their implementations.

Most clients will implement basic authentication for you, however if you need to implement it yourself, you need to base64 encode your email address and password or API key seperated by a colon. For example, if your email address is [email protected] and your API key is myhorseisamazing, then you would base64 encode [email protected]:myhorseisamazing, which would result in a2VhbnUucmVldmVzQGVzY3Jvdy5jb206bXlob3JzZWlzYW1hemluZw==. Using this value, you would then pass the Authorizationheader with the value: Basic a2VhbnUucmVldmVzQGVzY3Jvdy5jb206bXlob3JzZWlzYW1hemluZw==

Example: Authentication with email address and password

This is the easiest method of authentication you can use with the API as you can start using it as soon as you have signed up for an Escrow.com account. However, this tightly couples any integration with us that you have to your user credentials. For this reason, it is recommended that you use API keys, which you can have multiple of.

Consider this example where your Escrow.com email address is[email protected], and your Escrow.com password isEscrow1234. The code snippets below show how you can use your chosen client to perform authentication.

1
2
curl "https://api.escrow.com/2017-09-01/transaction/100"  \
  -u [email protected]:Escrow1234

Note that the rest of the documentation and guides will simply includeemail-address and api-keyfor the examples. You must include your authentication header for all requests.

Example: Authentication with API keys

From within the account settings page, you can generate API keys associated with your account. This is preferable to using your user name and password, as it allows you to recycle your credentials without changing the password on your account. Using an API key is almost identical to using a username and password for authentication. Simply provide your API key as your password and we will handle the rest.

Consider this example where your Escrow.com email address is[email protected], and you have created an API key with value99_ABCDefGHIKFD93423489023eejkfjkdjkjkjkjkjkjkabcdefgyz4534343kdlPp. The code snippets below show how you can use your chosen client to perform authentication.

1
2
curl "https://api.escrow.com/2017-09-01/customer/me"  \
  -u [email protected]:99_ABCDefGHIKFD93423489023eejkfjkdjkjkjkjkjkjkabcdefgyz4534343kdlPp

Note that the rest of the documentation and guides will simply includeemail-address and api-keyfor the examples. You must include your authentication header for all requests.

Performing actions on behalf of customers in a transaction

It is possible for approved partners to perform certain actions on a transaction on behalf of customers. Once approved, you may perform the agree, ship, receive, reject, ship return, receive return and reject return actions on a transaction on behalf of another party. You may also check available payment methods and choose a payment method for that party.

The way that this is accomplished is by setting the As-Customer header to the email address of the party you want to perform the action on behalf of.

1
2
3
4
5
curl "https://api.escrow.com/2017-09-01/transaction/9292"  \
  -X PATCH \
  -u email-address:api-key \
  -H 'As-Customer: [email protected]' \
  -d '{"action": "receive"}'

Rate limiting

In order to provide a stable platform to all users of the API, we enforce rate limiting on all Escrow.com API endpoints. The rate limiting is implemented per endpoint and the number of remaining requests you have is returned in the HTTP header RateLimit-Remaining on every API call you make. If you require higher rate limits, please contact us and we will consider your use case.

Errors

We do our best to ensure that the Escrow.com API is error free, however sometimes we will have to return an error. If an error occurs, we will always set the HTTP response code appropriately. See below for a list of HTTP codes we return.