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 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
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