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 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:
X-Auth-Secret-Keyheader. This is the preferred option.X-Auth-Secret-Key: sk_test_960bfde0VBrLlpK098e4ffeb53e1
Using Basic Authentication and the
Authorizationheader. 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
Basicand insert it into the
Authorizationheader. Many HTTP libraries will take care of this encoding for you.Authorization: Basic c2tfdGVzdF85NjBiZmRlMFZCckxscEswOThlNGZmZWI1M2UxOg==
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 |
|Error codes allow you to handle the error programmatically by providing you with a short string indicating the error code reported.|
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
internal_error - Something has gone wrong please contact support
network_error - Something has gone wrong please contact support