API Introduction

The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API in test mode, which does not affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Authentication

Http basic authentication is adopted for merchant identity authentication. Use your key as username and leave password blank.

Test mode keys have the prefix sk_test_/pk_test and live mode keys have the prefix sk_live_/pk_live.

Test domain: https://apitest.wooshpay.com
Live domain: https://api.wooshpay.com

Use the return value of the above method as the Authorization HTTP header

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

Error

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, there are three status code ranges you can expect:

2xx success status codes confirm that your request worked as expected

4xx error status codes indicate an error because of the information provided (for example, a required parameter was omitted)

5xx error status codes are rare and indicate an error with internal servers

Http Satus	Description
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.
402 - Request Failed	The parameters were valid but the request failed.
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 idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on internal end.

Error Types and Code

Error Types	Description
api_error	API errors cover any other type of problem (e.g., a temporary problem with internal servers), and are extremely uncommon.
card_error	Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.
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 Code

Error Object

Field	Type	Desc
type	string	One of api_error, card_error, idempotency_error, or invalid_request_error
code	string	For some errors that could be handled programmatically, a short string indicating the error code reported.
decline_code	string	For card errors resulting from a card issuer decline, a short string indicating the card issuer’s reason for the decline if they provide one.
message	string	A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
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.
payment_intent	object	The PaymentIntent object for errors returned on a request involving a PaymentIntent.
charge	string	For card errors, the ID of the failed charge.

Errors Example

{
  "error": {
    "message": "You did not provide an API key. ",
    "type": "invalid_request_error"
  }
}

Expanding Responses

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only. Responses can be expanded in two ways.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

Expansions on list requests start with the data property. For example, you would expand data.customers on a request to list charges and associated customers. Many deep expansions on list requests can be slow.

Expansions have a maximum depth of four levels.

You can expand multiple objects at once by identifying multiple items in the expand array.

{
  "id": "pi_3KCKoxL6kclEVx6M0kQ4ETTl",
  "object": "payment_intent",
  "amount": 1400,
	....
	"payment_method": {
    "billing_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
			   ....  
		},
	....
}

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice.

To perform an idempotent request, provide an additional Idempotency-Key element to the request options.

Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long.

Keys are eligible to be removed from the system automatically after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Wooshpay utilizes cursor-based pagination via the starting_after and ending_before parameters. Both parameters take an existing object ID value (see below) and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. These parameters are mutually exclusive -- only one of starting_after or**ending_before** may be used.

Request IDs

Each API request has an associated request identifier. 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.

Access Rate Limit

The API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession may see error responses that show up as status code 429. We have several limiters in the API, including:

A rate limiter that limits the number of requests received by the API within any given second.

For most APIs, Wooshpay allows up to 100 read operations per second and 100 write operations per second in live mode, and 25 operations per second for each in test mode.

For the Files API, Wooshpay allows up to 20 read operations per second and 20 write operations per second. Live mode and test mode limits are separate and equal.

A concurrency limiter that limits the number of requests that are active at any given time. Problems with this limiter are less common compared to the request rate limiter, but it’s more likely to result in resource-intensive, long-lived requests.

Treat these limits as maximums and don’t generate unnecessary load.

API Introduction

API Introduction#

Authentication#

Error#

Error Types and Code#

Error Object#

Errors Example#

Expanding Responses#

Idempotent Requests#

Pagination#

Request IDs#

Access Rate Limit#

API Introduction

Authentication

Error

Error Types and Code

Error Object

Errors Example

Expanding Responses

Idempotent Requests

Pagination

Request IDs

Access Rate Limit