Escrow API Documentation

Escrow API Basics

The Escrow API allows you to create transactions between yourself and another party, or between two other parties. It 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 /2017-09-01/The Escrow API is served over HTTPS and unencrypted HTTP connections are not supported.

Escrow 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 API within the sandbox environment, your base URL will behttps://api.escrow-sandbox /2017-09-01/

Authentication

The Escrow API supports basic authentication as defined inRFC2617.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 ismyhorseisamazing,then you would base64 encode[email protected]:myhorseisamazing,which would result ina2VhbnUucmVldmVzQGVzY3Jvdy5jb206bXlob3JzZWlzYW1hemluZw==.Using this value, you would then pass theAuthorizationheader with the value:Basic a2VhbnUucmVldmVzQGVzY3Jvdy5jb206bXlob3JzZWlzYW1hemluZw==

Example: Authentication with email address and password

This is the easiest method of authentication you can use with the Escrow API as you can start using it as soon as you have signed up for an Escrow 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 email address is[email protected],and your Escrow password isEscrow1234.The code snippets below show how you can use your chosen client to perform authentication.

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

Note that the rest of the documentation and guides will simply includeemail-addressandapi-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 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 /2017-09-01/customer/me"\
-u [email protected]:99_ABCDefGHIKFD93423489023eejkfjkdjkjkjkjkjkjkabcdefgyz4534343kdlPp

Note that the rest of the documentation and guides will simply includeemail-addressandapi-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 theAs-Customerheader 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 /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 Escrow API, we enforce rate limiting on all Escrow API endpoints. The rate limiting is implemented per endpoint and the number of remaining requests you have is returned in the HTTP header RateLimit-Remainingon 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 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.