Qashier Online Payment API (1.0.0)

A Checkout Session represents your customer's session as they pay for one-time purchases through Checkout. We recommend creating a new Session each time your customer attempts to pay.

You can create a Checkout Session on your server and redirect to its URL to begin Checkout.

Related guide: Accept a payment

Qashier uses API keys to authenticate requests. You can view and manage your API keys in your Qashier Dashboard.

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, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value and leave the password empty:

curl https://api.qashier.com/v3/payment/qpay/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:

Alternatively, you can manually construct the Authorization header:

Authorization: Basic <base64(sk_test_4eC39HqLyjWDarjtT1zdp7dc:)>

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The API supports idempotency keys to prevent duplicate requests. When you include an Idempotency-Key header with your POST request, the server will ensure that:

• If a request with the same idempotency key has already been processed, the API returns the same response without processing the request again
• The idempotency key should be unique for each distinct request
• Keys are automatically removed from the system after 24 hours
• Maximum key length is 255 characters

Example with Idempotency Key

curl -X POST https://api.qashier.com/v3/payment/qpay/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "return_url": "https://your-site.com/return",
    "success_url": "https://your-site.com/success",
    "line_items": [...]
  }'

Each API request has an associated request identifier that is automatically generated by the server. You can find this value in the response headers, under Request-Id.

If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Request IDs follow the format req_ followed by alphanumeric characters and underscores.

Example Request

curl -X POST https://api.qashier.com/v3/payment/qpay/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "return_url": "https://your-site.com/return",
    "success_url": "https://your-site.com/success",
    "line_items": [...]
  }'

Response Headers

All API responses include a Request-Id header that you can use for debugging:

Request-Id: req_abc123def456ghi789

Qashier uses conventional HTTP response codes to indicate the success or failure of an API request. 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, authentication failed, etc.)
• Codes in the 5xx range indicate an error with Qashier's servers

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

HTTP Status Code Summary

• 200 - OK: Everything worked as expected
• 400 - Bad Request: The request was unacceptable, often due to missing a required parameter
• 401 - Unauthorized: No valid API key provided
• 403 - Forbidden: The API key doesn't have permissions to perform the request
• 404 - Not Found: The requested resource doesn't exist
• 409 - Conflict: The request conflicts with another request (perhaps due to using the same idempotency key)
• 500 - Server Errors: Something went wrong on Qashier's end

Error Types

• api_error: API errors cover any other type of problem (e.g., a temporary problem with Qashier's servers) and are extremely uncommon
• authentication_error: Failure to properly authenticate yourself in the request
• idempotency_error: Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters
• invalid_request_error: Invalid request errors arise when your request has invalid parameters

Error Object

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: return_url",
    "param": "return_url"
  }
}

Error Attributes

• type (string): The type of error returned. One of api_error, authentication_error, idempotency_error, invalid_request_error, or rate_limit_error
• code (string): For some errors that could be handled programmatically, a short string indicating the error code reported
• message (string): A human-readable message providing more details about the error
• param (string): If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field

API endpoints for managing payment online checkout sessions

Refund payments from completed checkout sessions

Webhook events sent to your server

Qashier signs webhook events it sends to your endpoints by including a signature in each event's Qashier-Signature header. This allows you to verify that the events were sent by Qashier, not by a third party.

Signature Header Format

The Qashier-Signature header contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid scheme is v1.

Qashier-Signature: t=1625669316,v1=abc123def456...

Verifying Signatures

Qashier generates signatures using SHA-256. To verify a signature, you'll need to:

1. Extract the timestamp and signatures from the header
2. Prepare the signed payload by concatenating:
   • The timestamp (as a string)
   • The character .
   • The raw request body
3. Compute a SHA256 hash function, using the webhook secret provided as the key and the signed payload as the message
4. Compare your signature to the signatures in the header using a constant-time comparison