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:
In the
X-Auth-Secret-Key
header. This is the preferred option.X-Auth-Secret-Key: sk_test_960bfde0VBrLlpK098e4ffeb53e1Using 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 prependBasic
and insert it into theAuthorization
header. Many HTTP libraries will take care of this encoding for you.Authorization: Basic c2tfdGVzdF85NjBiZmRlMFZCckxscEswOThlNGZmZWI1M2UxOg==
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