x-api-key Header

The x-api-key header should be present in every API request. Create an API account and retrieve the key in the web UI. We do not recommend using the root API keys which were created by RevCent when you signed up. Instead, create new keys for specific implementations.

curl -G https://api.revcent.com/v2 \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \

Permissions

When creating an API key you can limit the key to perform only specific actions. We recommend you use the principle of least privilege, where you only enable specific API methods based on the use case per key.

Live/Test Keys

An API key can be set to Test mode or Live mode. This allows you to test the API and view results using the test/live mode toggle in the web app. Read more about Live vs Test mode at our Knowledge Base

Depending on the key used, RevCent will retrieve live or test items, as well as use the appropriate merchant gateway endpoint when processing payments. For example, if you use a test key for a payment request, RevCent will use the test endpoint for the merchant gateway and a live key will use the live merchant gateway endpoint.

HTTP Status Codes

There are seven potential HTTP status codes which can be returned by the RevCent V2 API. Use status codes as the starting point to determine the outcome of a request, then use the body of the response.

Do not confuse a HTTP status code with the code property contained within the response body. A HTTP status code is a standard for HTTP requests. The code property contained within an API call response body is specific to RevCent.

Non-Payment Error

For non-payment errors the HTTP status code will be 400 and the code property will equal 0. The message property will describe the reason for the request error.

Payment Error

For failed payment attempts the HTTP status code will be 402, and the code property within the response body will indicate the type of payment failure. The gateway_raw_response property is the response from the gateway indicating why the payment attempt failed.

There are potential values for the code property within the response body, either 2, 3, or 4, indicating the type of gateway failure.

Fraud Error

When either Sentinel or a third party service deems a request is fraud, the HTTP status code will be 402, and the code property will always equal 5. The fraud_detection_response property will provide detailed information about the fraud.

It is recommended that you do not display a fraud response directly to the visitor on checkout when fraud is detected. Instead, display a generic payment declined message to the fraudster, not letting them know you have detected fraud.

Additional payment attempts the fraudster makes will be immediately blocked by RevCent and never reach a gateway. RevCent wants fraudsters to continue to attempt payments, as RevCent will internally save information such as additional stolen cards and tracking visitor information.

Not Found Error

For not found errors the HTTP status code will be 404 and the code property will equal 0.

idempotency_key

Provide the idempotency_key property in the JSON body of a POST request. The idempotency key must be at least 10 characters in length and can be up to 255 characters in length. We recommended you use V4 UUIDs.

curl -X POST https://api.revcent.com/v2/sales \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{
    "idempotency_key": "2c74f520-2b7f-44ea"
}'

Required Parameters

Any GET requests which return more than one item, i.e. not ID specific, must include the date_start, date_end, limit and page URL parameters. Omitting any required parameters will result in an error.

curl -G https://api.revcent.com/v2/customers \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \
-d date_start=1627876799 \
-d date_end=1628049599 \
-d limit=25 \
-d page=1

Multi-Value Filter

You can submit multiple values for the same filter by including the URL parameter more than once in a GET request. RevCent will group same URL parameters when filtering items.

In the example CURL request we wish to filter a list of customers by campaign using the campaign_filter parameter. However, we want to filter using multiple campaign IDs. We provide the campaign_filter URL parameter twice, each time being a specific campaign ID.

curl -G https://api.revcent.com/v2/customers \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \
-d date_start=1627876799 \
-d date_end=1628049599 \
-d limit=25 \
-d page=1 \
-d campaign_filter="mJ1zZoOobEuP8pnWKXd1" \
-d campaign_filter="LYE26MW8Rlh5VbJmlp2l"

Metadata Filter

When making a get request for a list of items you have an optional metadata_filter parameter, which can be multi-value. Each metadata_filter parameter submitted is an object having a name and value property.

There are two methods when providing one or more metadata_filter parameters, however, you should only use one method in production. You can use a stringified JSON object, or use an array index i.e. metadata_filter[i][name] and metadata_filter[i][value].

In the two example CURL requests we show the different methods, where both methods would produce the same filtered result.

In the first example CURL request we wish to filter a list of sales by metadata using a stringified JSON object for each metadata_filter. Notice how we can include the metadata_filter multiple times with separate stringified JSON objects.

In the second example CURL request we use the array index method to match the name/value pair for each metadata_filter. Notice how we can include the metadata_filter multiple times, separating each filter name/value pair using an array index.

Customer ID Filter

Utilize the customer_id URL parameter when you wish to return a list of items specific to a customer.

Note: The customer_id filter is not a multi-value filter. It is limited to one customer ID and additional customer_id parameters will be ignored.

In the example CURL request, we wish to receive a list of transactions specific to the customer with an ID of 4r158EzJmmcVM69dNLkg. This will limit transactions only to this specific customer. If we omitted the customer_id parameter, all transactions will be returned regardless of customer.

curl -G https://api.revcent.com/v2/transactions \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \
-d date_start=1627876799 \
-d date_end=1628049599 \
-d limit=25 \
-d page=1 \
-d customer_id="4r158EzJmmcVM69dNLkg"

URL Params

When requesting a list of items, the date_start, date_end, page and limit parameters are required. Utilize all four parameters, specifically the limit and page parameters, to paginate across multiple pages of results.

curl -G https://api.revcent.com/v2/customers \
-H "x-api-key: YOUR_REVCENT_API_KEY" \
-H "Accept: application/json" \
-d date_start=1627876799 \
-d date_end=1628049599 \
-d limit=25 \
-d page=1

Page Info

The response from a list request will contain the results array, as well as page info. The page info tells you the current page, the total number of pages and the number of items per page.

In the example response, we are using a limit of 25, currently at page 1, with a total of 4 pages. If you wanted the next page (page 2), you would use the same date_start and date_end URL params, along with limit=25 page=2.