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:

1
curl https://api.yoco.com/v1/orders/ \
2
     -H "Authorization: Bearer <token>"

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>'

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 example makes a POST request to create a payment link.

1
curl -X POST https://api.yoco.com/v1/payment_links/ \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "amount": {
6
    "amount": 1500,
7
    "currency": "ZAR"
8
  },
9
  "customer_reference": "Peter Parker",
10
  "customer_description": "This description is visible to the customer on the payment page."
11
}'

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:

• 200 (OK)
• 201 (Created)
• 204 (No Content)

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

Please see our documentation on error handling for more details.