Transaction Search API (EPP)

This section will show you how to use our Search API to search for transactions. To interact with the search API, we will use curl. Please note that our API only accepts secure communication over TLS 1.1 and TLS 1.2. Moreover, to access our services, you need to authenticate yourself to the site with a username and password using HTTP Basic Authentication.

The service path of the search API is:

/epayment/api/MERCHANTIDENTIFIER/transactions/search

The MERCHANTIDENTIFER is the identifier of the merchant, i.e., the organisation who receives payments made through our Payment API. You will get the API user and the merchant identifier during the onboarding process from RaiseNow.

In the following, we give some examples on how to sort and filter for specific transactions. So, let’s start!

Example 1

First, we try to fetch the latest transactions sorted by created date:

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/ \
api/MERCHANTIDENTIFIER/transactions/search? \
sort[0][field_name]=created&sort[0][order]=desc"

Note that the sorting conditions are provided as query parameters. The query parameter sort[0][field_name] with value created specifies the field name which will be used to sort the transactions. The second query parameter defines the sorting order. The values desc and asc are allowed here. You can have multiple dimensions to sort to: Add a new pair of sort[1][field_name] and sort[1][order] with your preferred secondary dimension (have you noticed that the index has to be incremented by one?).

The result for the request above may look like the example below:

{
"result" : {
    "transactions":[
            {
                    "epp_transaction_id": "c2x0f148mz2zw44",
                    "created": "1485844439",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success",
            },
            {
                    "epp_transaction_id": "c2rl148sfc0836",
                    "created": "1485840836",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success"
            },
            {
                    "epp_transaction_id": "c1y2w148yyfbw72",
                    "created": "1485837232",
                    "currency_identifier": "chf",
                    "amount": 500,
                    "payment_method_identifier": "EZS",
                    "last_status": "final_success"
                                                        
            }
    ],
    "sort": [
          ],
    "additional_info": {
                    "lang": "de",
                    "page": 1,
                    "total_pages": 13,
                    "search_time": "28.2662",
                    "records_per_page": "100",
                    "total_hits": 1321
               },
    "filters": [
            ],
    "facets": [
             ]
    }
}

The field created contains the creation date of the transaction as UNIX timestamp. Under additional_info you see meta information about your request. total_pages, records_per_page, and total_hits are important figures to fetch all remaining transactions.

There are 3 additional useful query parameters available to retrieve the relevant transactions.

• records_per_page defines how many transactions per page.

• If the result has more transactions than defined in records_per_page, you can jump to the next/previous page by incrementing/decrementing the current value of page.

• displayed_fields defines which fields/parameters of the transactions should be returned. It is a comma-separated list, e.g. epp_transaction_id,amount,currency,created

So, try it out and request your own merchant parameters (starting with stored_).

Example 2

Returning all transactions without filtering is of limited use. In this example, we demonstrate how to retrieve transactions with the following filter criteria:

• test_mode = production

• last_status = final_success

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/api/ \
MERCHANTIDENTIFIER/transactions/search?sort[0][field_name]=created& \
sort[0][order]=desc&filters[0][field_name]=test_mode& \
filters[0][type]&term&filters[0][value]=production& \
filters[1][field_name]=last_status& \
filters[1][type]=term&filters[1][value]=final_success"

Each filter is defined by 3 to 5 query parameters:

• filters[0][field_name] defines the field.

• filters[0][type] defines the type of the field. Possible values are: term, range, date_range, and fulltext. term values are not analyzed.

• filters[0][value] defines the value for term or fulltext filters. The character * and ~ are not allowed as first character of the value.

• filters[0][from] defines the lower bound for range and date_range filter.

• filters[0][to] defines the upper bound for range and date_range filter.

Example 3

The last example shows how to fetch transactions within a predefined date range.

curl -u USERNAME:PASSWORD -g "https://api.raisenow.com/epayment/api/ \
MERCHANTIDENTIFIER/transactions/search?sort[0][field_name]=created& \
sort[0][order]=desc&filters[0][field_name]=created& \
filters[0][type]=date_range& \
filters[0][from]=20160915000000&filters[0][to]=20160915235959"

The above request will fetch all transactions from 15th of September 2016 whereas filters[0][from] (e.g. 20160915000000) is defined as UTC timestamp in the format YYYYMMDDhhmmss (four-digit year, two-digit month, two-digit day, zero-padded hour between 00 and 24, zero-padded minute between 00 and 59, zero-padded second between 00 and 59).