API

Using the REST API

Overview

The following document gives an overview of how to use our REST API. It includes high-level information on our live and sandbox environments, authentication, making a request and handling responses.

For further information on a specific subject, please consult the relevant section of the documentation.

Environments

We have both a live and a sandbox (testing) environment.

The live environment is accessible at https://api.yoco.com. You must use a valid live authentication token when making requests to this API URL.

For testing, you can use the sandbox environment accessible at https://api.yocosandbox.com. Similar to the live environment, you must use a valid sandbox authentication token when making requests.

Please note that a live authentication token will not work against sandbox.

Authentication

All requests to our API must be accompanied by a valid authentication token issued via the OAuth 2.0 flow.

It must be specified using the Authorization header.

Example:

$curl https://api.yoco.com/v1/orders/ \
>  -H 'Authorization: Bearer <access token>' \
>  -H 'Content-Type: application/json'

Resources

A resource is a thing you act upon, such as an order, payment or refund.

You can view a full list of available resources in our API Reference.

HTTP methods

When interacting with our API, you use an HTTP method to act upon a resource.

The common actions are:

  • GET: Retrieve information about a resource.
  • POST: Create a new resource.
  • PUT: Update a resource.
  • DELETE: Remove a resource.
  • PATCH: Perform a partial update to a resource.

The following fictitious examples illustrate practical use:

  • Retrieve an order: GET /v1/orders/1851231235
  • Retrieve a list of open orders: GET /v1/orders/?status=OPEN
  • Update an order: PUT /v1/orders/1851231235
  • Delete (or cancel) an order: DELETE /v1/orders/1851231235
  • Perform a partial update to an order: PATCH /v1/orders/1851231235

Making a request

When making a GET request to retrieve a single resource or list of resources, you will often use query string parameters to add additional context to your request.

The following example makes a GET request to retrieve a paginated list of open orders.

$curl https://api.yoco.com/v1/orders/?status=OPEN \
>  -H 'Authorization: Bearer <access token>' \
>  -H 'Content-Type: application/json'

Unless noted otherwise, most PUT, PATCH, and POST requests require you to send the resource data as a JSON payload in the request body.

The following fictitious example makes a POST request to create an order.

$curl https://api.yoco.com/v1/orders/ \
>  -H 'Authorization: Bearer <access token>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>    "payment_method": "CARD",
>    "order_number": "1234"
>  }'

Handling a response

All API calls return a JSON response, unless stated otherwise.

A successful response is indicated by a 2XX HTTP status code.

The most common HTTP 2XX status codes returned by our API are:

An error response is indicated by a 4XX or 5XX HTTP status code.

Please see our documentation on error handling for more details.