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.
api_key_missing An secret key is required.
wrong_api_key You have provided a secret key that is incorrect.
public_key_missing A public key is required.
public_key_wrong You have provided a public key that is incorrect.
token_already_charged The token you are attempting to charge has already been charged.
object_not_found The object referenced in your request was not found on our system.
api_access_limitation You have reached some predefined limit related to your API access.
wrong_expiry_date You have provided the wrong expiry date.
3d_auth_failed 3D Authentication has failed.
charge_declined Your charge has been declined.