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.


To initiate a request to any of our endpoints, you will need to provide an API key in the Authorization header. Unless otherwise specified, you should use your secret key.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code etc.

All API requests must be made over HTTPS.

curl https://online.yoco.com/v1/charges \
-u sk_test_960bfde0VBrLlpK098e4ffeb53e1:
# The colon prevents curl from asking for a password.


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.


The type of error returned. Should be one of invalid_request_error, authentication_error, charge_error, refund_error
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