Skip to navigation
Yoco API

Using the REST API

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

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

Environments

Both a live and a sandbox testing environment are available.

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.

Note that a live authentication token doesn’t work against sandbox.

Authentication

All requests to the 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:

GET
/v1/orders/
import requests
url = "https://api.yoco.com/v1/orders/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.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 the API reference.

HTTP methods

When interacting with the 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 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.

POST
/v1/payment_links/
import requests
url = "https://api.yoco.com/v1/payment_links/"
payload = {
"amount": {
"amount": 1500,
"currency": "ZAR"
},
"customer_reference": "Peter Parker",
"customer_description": "This description is visible to the customer on the payment page."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

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 the API are:

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

See error handling for more details.