Overview

General Structure

All requests and responses to and from IceCharge's servers can be in either XML or JSON. To account for future upgrades to the API, we added a version specification to the URI. Our API is RESTful; it supports the two most widely used HTTP methods: POST and GET.

Design Considerations

IceCharge's entire ecosystem is asynchronous and fully reentrant, and our API reflects this.

Uniform Resource Identifier

The URI format is designed such that there is no need to add headers to requests that specify the desired language (XML, JSON, etc) for a request or response.

URL Structure

https://[merchant_id]:[apikey]@api.icecharge.com/[version]/[format]/[base]/[id]/[action]/[subaction]

• [merchant_id] Merchant ID, auto-generated and handed out at time of sign up.
• [apikey] API key given to the merchant upon signing up.
• [version] indicates the version of the API, currently the latest version is "v1".
• [format] can take one of two options, "xml" or "json".
• [base] indicates the type of resource that this request going to work on.
• [id] the ID of the resource which this request going to work on. (optional)
• [action] the action that will be applied on the resource specified by [id] (optional)
• [subaction] a sub action of the action specified to be applied on the resource specified by [id] (optional, but if specified, [action] and [id] are required).

Authentication

IceCharge utilizes Digest Authentication to authenticate clients.

HTTP Codes

• 200 OK
• 400 Bad Request
• 401 Unauthorized
• 402 Payment Required
• 403 Forbidden
• 404 Not Found
• 405 HTTP Method Not Allowed
• 500 Internal Server Error
• 505 HTTP Version Not Supported (IceCharge supports HTTP/1.1 only)