/ /

Payments endpoint

Last updated: April 29, 2022

The payments endpoint allows you to search for all payments within parameters you specify.

Note

The payments endpoint is not available in the sandbox environment.

Tip

If you're not familiar with creating API requests, you might want to take a look at our Postman guide.

Information

No payments from before February 7th, 2019 at 00.00.00 UTC will appear when using the payments endpoint. To view payments from before this time, please contact our Support team..

Request JSON

The GET request

Use the details below to set up your request. To set the timeframe of your request, replace {start-date-time} and {end-date-time} with your desired start and end dates in ISO format (yyyy-mm-ddThh:mm:ss). Please note that the time zone for the request will be UTC.

Endpoint

get

https://api.checkout.com/reporting/payments

Request parameters and endpoints

You can filter the data in the payments endpoint by using the parameters below:

Filter Parameter

Filter	Parameter
Date-Time	`1https://api.checkout.com/reporting/payments?from={start-date-time}&to={end-date-time}`
Payment ID	`1https://api.checkout.com/reporting/payments/{paymentId}`
Reference	`1https://api.checkout.com/reporting/payments?reference={reference}`

Date-Time

1https://api.checkout.com/reporting/payments?from={start-date-time}&to={end-date-time}

Payment ID

1https://api.checkout.com/reporting/payments/{paymentId}

Reference

1https://api.checkout.com/reporting/payments?reference={reference}

You can also limit results.

The GET response

If the payments endpoint returns a response, then the request was successful. Below, you can find an example response from the payments endpoint, in addition to a list of the fields that will be shown.

Information

By default, the payments endpoint returns up to 200 payments per page of results. You can change this limit if you'd like.

Response example

1{
2  "count": 1,
3  "data": [
4    {
5      "id": "pay_nezg6bx2k22utmk4xm5s2ughxi",
6      "processing_currency": "USD",
7      "payout_currency": "GBP",
8      "requested_on": "2019-03-08T10:29:51.922",
9      "channel_name": "www.example.com",
10      "reference": "ORD-5023-4E89",
11      "payment_method": "VISA",
12      "card_type": "CREDIT",
13      "card_category": "Consumer",
14      "issuer_country": "US",
15      "merchant_country": "SI",
16      "mid": "123456",
17      "actions": [
18        {
19          "type": "Authorization",
20          "id": "act_nezg6bx2k22utmk4xm5s2ughxi",
21          "processed_on": "2019-03-08T10:29:51.922",
22          "response_code": "10000",
23          "response_description": "Approved",
24          "breakdown": [
25            {
26              "type": "Gateway Fee Tax ARE USD/GBP@0.7640412612",
27              "date": "2019-03-08T10:29:51.922",
28              "processing_currency_amount": -0.003,
29              "payout_currency_amount": -0.00229212
30            },
31            {
32              "type": "Authorization Fee Tax ARE USD/GBP@0.7640412612",
33              "date": "2019-03-08T10:29:51.922",
34              "processing_currency_amount": -0.0045,
35              "payout_currency_amount": -0.00343819
36            },
37            {
38              "type": "Scheme Fixed Fee Tax ARE USD/GBP@0.7640412612",
39              "date": "2019-03-08T10:29:51.922",
40              "processing_currency_amount": -0.00238223,
41              "payout_currency_amount": -0.00182012
42            },
43            {
44              "type": "Gateway Fee USD/GBP@0.7640412612",
45              "date": "2019-03-08T10:29:51.922",
46              "processing_currency_amount": -0.06,
47              "payout_currency_amount": -0.04584248
48            },
49            {
50              "type": "Authorization Fee USD/GBP@0.7640412612",
51              "date": "2019-03-08T10:29:51.922",
52              "processing_currency_amount": -0.09,
53              "payout_currency_amount": -0.06876371
54            },
55            {
56              "type": "Scheme Fixed Fee USD/GBP@0.7640412612",
57              "date": "2019-03-08T10:29:51.922",
58              "processing_currency_amount": -0.04764462,
59              "payout_currency_amount": -0.03640246
60            }
61          ]
62        },
63        {
64          "type": "Capture",
65          "id": "act_chgfpd2kn3iellv7hwo6cfekea",
66          "processed_on": "2019-03-08T10:29:52.562",
67          "response_code": "10000",
68          "response_description": "Approved",
69          "breakdown": [
70            {
71              "type": "Gateway Fee Tax ARE USD/GBP@0.7640412612",
72              "date": "2019-03-08T10:29:52.562",
73              "processing_currency_amount": -0.003,
74              "payout_currency_amount": -0.00229212
75            },
76            {
77              "type": "Capture Fee Tax ARE USD/GBP@0.7640412612",
78              "date": "2019-03-08T10:29:52.562",
79              "processing_currency_amount": -0.0045,
80              "payout_currency_amount": -0.00343819
81            },
82            {
83              "type": "Scheme Fixed Fee Tax ARE USD/GBP@0.7640412612",
84              "date": "2019-03-08T10:29:52.562",
85              "processing_currency_amount": -0.00364341,
86              "payout_currency_amount": -0.00278372
87            },
88            {
89              "type": "Scheme Variable Fee Tax ARE USD/GBP@0.7640412612",
90              "date": "2019-03-08T10:29:52.562",
91              "processing_currency_amount": -0.00714,
92              "payout_currency_amount": -0.00545525
93            },
94            {
95              "type": "Premium Fee Tax ARE USD/GBP@0.7640412612",
96              "date": "2019-03-08T10:29:52.562",
97              "processing_currency_amount": -0.06,
98              "payout_currency_amount": -0.04584248
99            },
100            {
101              "type": "Gateway Fee USD/GBP@0.7640412612",
102              "date": "2019-03-08T10:29:52.562",
103              "processing_currency_amount": -0.06,
104              "payout_currency_amount": -0.04584248
105            },
106            {
107              "type": "Capture Fee USD/GBP@0.7640412612",
108              "date": "2019-03-08T10:29:52.562",
109              "processing_currency_amount": -0.09,
110              "payout_currency_amount": -0.06876371
111            },
112            {
113              "type": "Scheme Fixed Fee USD/GBP@0.7640412612",
114              "date": "2019-03-08T10:29:52.562",
115              "processing_currency_amount": -0.07286825,
116              "payout_currency_amount": -0.05567435
117            },
118            {
119              "type": "Scheme Variable Fee USD/GBP@0.7640412612",
120              "date": "2019-03-08T10:29:52.562",
121              "processing_currency_amount": -0.1428,
122              "payout_currency_amount": -0.10910509
123            },
124            {
125              "type": "Premium Fee USD/GBP@0.7640412612",
126              "date": "2019-03-08T10:29:52.562",
127              "processing_currency_amount": -1.2,
128              "payout_currency_amount": -0.91684951
129            },
130            {
131              "type": "RR (0.06%, Release: 2019-03-08) USD/GBP@0.7640412612",
132              "date": "2019-03-08T10:29:52.562",
133              "processing_currency_amount": -0.012,
134              "payout_currency_amount": -0.01
135            },
136            {
137              "type": "Captured USD/GBP@0.7640412612",
138              "date": "2019-03-08T10:29:52.562",
139              "processing_currency_amount": 20,
140              "payout_currency_amount": 15.28082522
141            }
142          ]
143        },
144        {
145          "type": "Void Authorization",
146          "id": "act_4i7tyuj97qzendoopldc74rsg4",
147          "processed_on": "2019-03-08T10:29:53.157",
148          "response_code": "10000",
149          "response_description": "Approved",
150          "breakdown": [
151            {
152              "type": "Void Fee USD/GBP@0.7640412612",
153              "date": "2019-03-08T10:29:53.157",
154              "processing_currency_amount": -0.5509467,
155              "payout_currency_amount": -0.42094676
156            }
157          ]
158        },
159        {
160          "type": "Chargeback",
161          "id": "act_E198KE9B174L71WD6TF9",
162          "processed_on": "2019-03-08T10:29:53.399",
163          "response_code": "10.4",
164          "response_description": "Fraudulent Transaction – Card Absent Environment",
165          "breakdown": [
166            {
167              "type": "Chargeback Fee",
168              "date": "2019-03-08T10:29:53.399",
169              "processing_currency_amount": -10.0,
170              "payout_currency_amount": -10.0
171            },
172            {
173              "type": "Chargeback (ADJM)",
174              "date": "2019-03-08T10:29:53.399",
175              "processing_currency_amount": -20.67,
176              "payout_currency_amount": -20.67
177            }
178          ]
179        },
180        {
181          "type": "Refund",
182          "id": "act_hdwpzxgcoaceekwa8n54tmim5i",
183          "processed_on": "2019-03-08T10:29:53.864",
184          "response_code": "10000",
185          "response_description": "Approved",
186          "breakdown": [
187            {
188              "type": "Refund Fee USD/GBP@0.7640412612",
189              "date": "2019-03-08T10:29:53.864",
190              "processing_currency_amount": -0.56329695,
191              "payout_currency_amount": -0.43038211
192            },
193            {
194              "type": "Refunded USD/GBP@0.7640412612",
195              "date": "2019-03-08T10:29:53.864",
196              "processing_currency_amount": -1195.65,
197              "payout_currency_amount": -890.604696
198            }
199          ]
200        }
201      ],
202      "_links": {
203        "self": {
204          "href": "https://api.checkout.com/reporting/payments/pay_nezg6bx2k22utmk4xm5s2ughxi"
205        }
206      }
207    }
208  ],
209  "_links": {
210    "self": {
211      "href": "https://api.checkout.com/reporting/payments/pay_nezg6bx2k22utmk4xm5s2ughxi"
212    }
213  }
214}

Understanding the response

The payments endpoint is designed to present your payments as clearly as possible. Depending on your parameters, you may receive a large response. If you’re looking for data even more quickly, try amending the parameters in the request. Regardless of the parameters in your request, the payments endpoint’s response can be split into four sections, each of which is outlined below.

1. Payments

This section displays all payment information in accordance with your chosen parameters. The table below shows the full list of parameters displayed, and how to decipher them.

Parameter	Description
`id`	The unique payment ID. Previously, this was called transaction_id.
`processing_currency`	The currency of the payment when processed by the cardholder.
`payout_currency`	The currency of the payment when paid out to you.
`requested_on`	The date on which the payment was initiated.
`channel_name`	The name of the channel where the payment was initiated.
`reference`	An optional ID used for tracking payments. Previously, this was called track_id.
`payment_method`	The payment method. For example, Visa or Mastercard.
`card_type`	The card type. For example, credit or debit card.
`card_category`	The card category. For example, consumer or commercial.
`issuer_country`	The country of the issuing bank.
`merchant_country`	The country of the merchant bank.
`mid`	An optional, user-defined ID that identifies the business.

2. Actions

This section outlines all the actions — authorization, void, capture, refund, retrieval, and chargeback — which have been administered to a payment. The table below outlines and explains the parameters of the report.

Parameter	Description
`type`	The type of action. For example, authorization, capture, refund, chargeback, chargeback reversal, or payment-related fee.
`id`	The unique ID associated with an action (referred to as a charge ID in the Hub).
`processed_on`	The date on which the action occurred.
`response_code`	The response code of the action (payment request).
`response_description`	Further information about the response code.

3. Breakdown

The amounts summary shows the amounts corresponding with a particular action. The table below shows the full list of these parameters and their explanations.

Parameter	Description
`type`	Describes an amount/fee associated with an action. For example, a gateway fee, capture fee and capture amount would all be associated with the capture action.
`date`	Specifies an associated date with a specific amount (some external fees are returned after the associated action).
`processing_currency_amount`	The associated amount in the processing currency (if applicable). Numerical values up to 8 decimal places are provided in the response.
`payout_currency_amount`	The associated amount in the payout currency. Numerical values up to 8 decimal places are provided in the response.

Information

If you're looking for the outcome of a particular chargeback, please allow up to 60 days from the date the evidence was provided.

4. Links

You might have noticed several links at the bottom of the response from the payments endpoint. Let’s take a look at each one.

Payment ID – Self

This link allows you to focus on a particular payment that has been included in the response. As you can see, the final component of the link is pay_sv6ikhu36mgepkm3l22pztvywa, which corresponds to the payment ID for that particular payment in the response.

1{
2    "_links": {
3      "self": {
4        "href": "https://api.checkout.com/reporting/payments/pay_sv6ikhu36mgepkm3l22pztvywa"
5      }
6    }
7}

This link lets you move to the next page of results. Results are paginated at a payment level. By default, a page contains 200 results — though you can change this limit if you'd like.

1{
2    "_links": {
3        "next": {
4            "href": "https://api.checkout.com/reporting/payments?from=01%2F03%2F2019%2000%3A00%3A00&to=01%2F03%2F2019%2000%3A00%3A00&limit=1&after=11111111"
5        }
6    }
7}

Self

This link provides the URL associated with the current request.

1{
2    "_links": {
3        "self": {
4            "href": "https://api.checkout.com/reporting/payments?from=01%2F03%2F2019%2000%3A00%3A00&to=01%2F03%2F2019%2000%3A00%3A00&limit=1"
5        }
6    }
7}

Download a CSV

In addition to the JSON format described above, you can download a CSV report containing the data from the payments endpoint. To do this, follow the steps below.

How to download the CSV file

In the URL for the payments endpoint, add /download after /payments. An example of this can be found below:

1https://api.checkout.com/reporting/payments/download?from={start-date-time}&to={end-date-time}

If you are using Postman or an equivalent application, rather than sending the GET request, use the Send and Download functionality for the GET request to download the CSV report.

Information

Using /download will return a CSV containing all your payments unlike a standard request, which is paginated.

Tip

You can also get a CSV report by amending the Headers section of the request to accept a value of text/csv. Note that this will contain the same paginated results as the JSON.

How to read the CSV file

In your CSV file, a single payment is uniquely identified by an ID in the first column of the table and will be made of multiple rows, each of them reflecting a fee or an amount applied to a different action within the payment lifecycle.

Regardless of the parameters in your request, the payments endpoint’s CSV file will have the same overall structure and columns titles which can be split into three sections.

1. Payment and card attributes

This section displays all payment and card attributes in accordance with your chosen parameters.

2. Actions

This section outlines all the actions — authorization, void, capture, refund and chargeback — which have been administered to a payment.

3. Breakdown

This section provides details of the associated amounts to an action in both the processing and the payout currencies.

Limit results

Responses from the payments endpoint can be large, depending on the number of payments you process and the parameters you have chosen. By default, each page includes 200 results.

To limit your results, add limit= followed by a number of your choice (up to 500) at the end of the URL.

For example:

1https://api.checkout.com/reporting/payments?from=01%2F03%2F2019%2000%3A00%3A00&to=01%2F03%2F2019%2000%3A00%3A00&limit=100

Information

You can only limit results for JSON responses. A CSV will always contain all possible results.

Payments endpoint

Note

Tip

Information

Request JSON

The GET request

Endpoint

Request parameters and endpoints

The GET response

Information

Response example

Understanding the response

1. Payments

2. Actions

3. Breakdown

Information

4. Links

Payment ID – Self

Next

Self

Download a CSV

How to download the CSV file

Information

Tip

How to read the CSV file

1. Payment and card attributes

2. Actions

3. Breakdown

Limit results

Information

On this page

We've made some changes to our API