API Overview

Our API is organized around REST and has predictable resource-oriented URLs. The API accepts both JSON and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

To initiate a request to any of our endpoints, you will need to provide your API secret key as part of the request. You can find your secret key in the Yoco Business Portal after signing up.

Test secret keys start with sk_test_ and live mode secret keys with sk_live_. See here for more information about the keys.

You can provide the secret key in one of two ways:

1. In the X-Auth-Secret-Key header. This is the preferred option.

   X-Auth-Secret-Key: sk_test_960bfde0VBrLlpK098e4ffeb53e1

2. Using Basic Authentication and the Authorization header. In this case the secret key acts as the username and the password should be left empty. To do this, append a colon to the end of your secret key and Base64 encode it. Now prepend Basic and insert it into the Authorization header. Many HTTP libraries will take care of this encoding for you.

   Authorization: Basic c2tfdGVzdF85NjBiZmRlMFZCckxscEswOThlNGZmZWI1M2UxOg==

Your API keys are used to identify you and enable payments, so be sure to keep them safe. Never share your secret key or publish it in code, such as on GitHub. All API requests must be made over HTTPS.

Errors

The API uses conventional HTTP response codes to indicate the success or failure of requests. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with our servers (these do not happen often).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

Attributes

Parameter	Description
errorType string	The type of error returned. Should be one of invalid_request_error, authentication_error, charge_error, refund_error
errorCode string	Error codes allow you to handle the error programmatically by providing you with a short string indicating the error code reported.

Error Codes

Below is a list of possible error codes that can be returned (this is not an exhaustive list), along with additional information to help you resolve the errors.

When initialising the sdk:

api_key_missing - Required secret key missing

wrong_api_key - Secret key is wrong

wrong_token - Token provided does not exist

wrong_currency - Currency provided in charge API call does not match the currency of the generated token

wrong_amount - Amount provided in charge API call does not match the amount of the generated token

missing_token_parameter - Token parameter is not present or named correctly in charge API call

missing_currency_parameter - Currency parameter is not present or named correctly in charge API call

missing_amount_parameter - Amount parameter is not present or named correctly in charge API call

not_passing_through_cents - Amount must be past through as cents with no decimal

3d_auth_failed - The card holder has failed 3D authentication

When executing a charge:

charge_declined - Charge declined by cardholder bank

token_already_charged - You cannot charge a token more than once

limit_exceeded - The card holder bank declined the transaction(limit exceeded)

wrong_expiry_date - Expiry date entered by card holder is wrong

When requesting a refund:

refund_already_processed - The charge you are trying to refund has already been refunded

refund_declined - Your refund could not be processed. Please contact support

General errors:

internal_error - Something has gone wrong please contact support

network_error - Something has gone wrong please contact support