Reporting

All of your transactions, summed up.

When it comes to monitoring your transactions, organizing your archives, and following regulations, financial reporting is essential to your business. With the Switch Platform, you can do it all in one place by using our Reporting Application.

1
Create and Customize
Generate new reports and tap into the specifics of your transaction landscape. With the Reporting templates you are able to segment your transactional data, tap into new opportunities and push problematic areas to stand out.
2
Search and Filter
Find answers to all your stakeholders questions in a report. Looking for specifics? Trying to sum up a month’s worth of work? Reporting on your strongest currency? You can find it all with the Reporting application.
3
Share and Archive
Manage your archives, and share files with the people that matter. Set up billing schedules customized to fit your clients. Handle all the paperwork from one single source.

Reports

Learn how to generate comprehensive reports from your transactions.

Reporting Templates

Understand what conditions are relevant to your analysis and how to set up the ideal report.

Reporting Schedules

Decide on periodicity and frequency in the creation of your reports.

Billing

Generate billing reports to pass on to your sub-merchants and clients.

Reports

Generating reports of your transactions should be a straightforward process that aids the management and upkeep of your company and accounts. Through Reporting you can get a quick overview of the transactions processed with Switch.

Reports are .CVS files generated from your list of transactions. You can filter reports following multiple headers related to charge, instrument, payment, refund, dispute, reversal and settlement events. Before being able to proceed with the creation of a report, you need to set up a Reporting template which defines the structure and conditions of your report. You can find more information on how to create Reporting templates in the next chapter.

Existing reports can be revisited by searching for specific designations, namely by the description given to the report, by date and by details like currency.

POST `/v1/reporting/reports`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/reports` Production `https://merchant-api.switchpayments.com/v1/reporting/reports`	Generate a new report.

Request Body Parameters

descriptionStringRequired

Description of the new report being generated.

templateStringRequired

Reporting template ID applied to the report being generated.

REQUEST
    $ curl -vX POST https://merchant-api.switchpayments.com/v1/reporting/reports?merchant_id=accountId -u accountId:APIKey
    {
       "description": "Example",
       "template": "862d7a6939de9eda2ce47af9cc2c848211ab5f0a5e7cc539"
    }

Response Parameters

idString

Identifier for the generated report.

typeString

Type of report generated. It can either be default or billing.

currencyString

Currency present in the report.

descriptionString

Description attributed to the report.

metadataString

Metadata associated with the report.

merchant_idString

Identifier of the merchant to whom the report belongs to.

templateJSON Object

Details and conditions defined by the report template.

created_atDate

Date when the report was created.

created_atDate

Date when the report was last updated.

RESPONSE: HTTP 201 CREATED
    {
       "id": "0e22990c2a581f3257394771cb52b85821a7b6da5f3be6a9",
       "type": "default",
       "status": "pending",
       "currency": "EUR",
       "description": "Example",
       "transactions_query": null,
       "transactions_file_type": null,
       "transactions_file_headers": null,
       "failure_description": null,
       "metadata": null,
       "merchant_id": "Lq9aVoz7eI852ID7ffNgGD9rr9Grv3ZQeE9dtfF0KvE6QxGQLwmjCPFkqmpP6td",
       "template": {
           "items": [
               {
                   "label": "Example Item",
                   "quantity_type": "fixed",
                   "quantity_config": {
                       "value": 2.0
                   },
                   "value_type": "tiered",
                   "value_config": {
                       "tiers": [
                           {
                               "value": 200,
                               "minimum_quantity": 0
                           }
                       ]
                   },
                   "minimum_quantity": null,
                   "minimum_total": null,
                   "maximum_quantity": null,
                   "maximum_total": null
               }
           ],
           "id": "403d9c8fa29319515bbf454ebdc450146f156ad75f3bd75c"
       },
       "created_at": "2020-08-18T14:33:13.142267+00:00",
       "updated_at": "2020-08-18T14:33:13.142332+00:00"
    }

DELETE `/v1/reporting/reports{id}`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/reports{id}` Production `https://merchant-api.switchpayments.com/v1/reporting/reports{id}`	Delete a report.

REQUEST
  $ curl -vX DELETE https://merchant-api.switchpayments.com/v1/reporting/reports/{id}?merchant_id=accountId -u accountId:APIKey

RESPONSE: HTTP 204 NO CONTENT
    The server successfully processed the request and it is not returning any content.

GET `/v1/reporting/reports`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/reports` Production `https://merchant-api.switchpayments.com/v1/reporting/reports`	Get the list of existing reports.

Request Body Parameters

created_at__gte Date

When filtering the results by date, this is the start date.

created_at__lteDate

When filtering the results by date, this is the end date.

typeString

You can filter reports by type. Billing reports are set to billing, all other reports fit the default type.

currencyString

Currency applied in the report.

descriptionString

Designation attributed to the report.

REQUEST
    $ curl -vX GET https://merchant-api.switchpayments.com/v1/reporting/reports?merchant_id=accountId -u accountId:APIKey
    {
       "created_at__gte": "2020-07-31T23:00:00",
       "created_at__lte": "2020-08-04T22:59:59",
       “type”: “default”,
       “currency”:”EUR”,
       “description”: “example”
    }

Response Parameters

idString

Identifier for the generated report.

typeString

Type of report generated. It can either be default or billing.

currencyString

Currency present in the report.

descriptionString

Description attributed to the report.

metadataString

Metadata associated with the report.

merchant_idString

Identifier of the merchant to whom the report belongs to.

templateJSON Object

Details and conditions defined by the report template.

created_atDate

Date when the report was created.

created_atDate

Date when the report was last updated.

RESPONSE: HTTP 200 CREATED
    {
       {
       "collection": [
           {
               "id": "bce180137bfd5393633b18dd4748390b46fe6c565f299085",
               "type": "default",
               "status": "finished",
               "currency": "EUR",
               "description": "example",
               "transactions_query": {
                   "type": [
                       "charge",
                       "payment"
                   ],
                   "currency": [
                       "TRY",
                       "USD"
                   ],
                   "created_at__gte": "2020-08-03T23:00:00",
                   "created_at__lte": "2020-08-05T10:47:00"
               },
               "transactions_file_type": "csv",
               "transactions_file_headers": [
                   {
                       "name": "Merchant ID",
                       "field": "merchant_id"
                   }
               ],
               "failure_description": null,
               "metadata": {
                   "cenas": "cenas"
               },
               "merchant_id": "Lq9aVoz7eI852ID7ffNgGD9rr9Grv3ZQeE9dtfF0KvE6Q",
               "template": {
                   "items": [
                       {
                           "label": "asd",
                           "value_type": "tiered",
                           "value_config": {
                               "tiers": [
                                   {
                                       "value": 2,
                                       "minimum_quantity": 0
                                   }
                               ]
                           },
                           "maximum_total": null,
                           "minimum_total": null,
                           "quantity_type": "count",
                           "quantity_config": {
                               "filters": [
                                   {
                                       "charge_type__in": [
                                           "card_onetime"
                                       ],
                                       "transaction_type__in": [
                                           "charge"
                                       ]
                                   }
                               ]
                           },
                           "maximum_quantity": null,
                           "minimum_quantity": null
                       },
                       {
                           "label": "poknj",
                           "value_type": "tiered",
                           "value_config": {
                               "tiers": [
                                   {
                                       "value": 20,
                                       "minimum_quantity": 0
                                   },
                                   {
                                       "value": 10,
                                       "minimum_quantity": 100
                                   }
                               ]
                           },
                           "maximum_total": null,
                           "minimum_total": null,
                           "quantity_type": "count",
                           "quantity_config": {
                               "filters": [
                                   {
                                       "charge_type__in": [
                                           "card_onetime"
                                       ],
                                       "transaction_type__in": [
                                           "payment"
                                       ]
                                   }
                               ]
                           },
                           "maximum_quantity": null,
                           "minimum_quantity": null
                       }
                   ]
               },
               "created_at": "2020-08-04T16:44:53.466096+00:00",
               "updated_at": "2020-08-04T16:44:54.882597+00:00",
               "items": [
                   {
                       "label": "asd",
                       "quantity": 4.0,
                       "original_quantity": 4,
                       "value": 2.0,
                       "total": 8.0,
                       "original_total": 8.0,
                       "template_item_details": {
                           "quantity_type": "count",
                           "quantity_config": {
                               "filters": [
                                   {
                                       "charge_type__in": [
                                           "card_onetime"
                                       ],
                                       "transaction_type__in": [
                                           "charge"
                                       ]
                                   }
                               ]
                           },
                           "value_type": "tiered",
                           "value_config": {
                               "tiers": [
                                   {
                                       "value": 2,
                                       "minimum_quantity": 0
                                   }
                               ]
                           },
                           "minimum_quantity": null,
                           "minimum_total": null,
                           "maximum_quantity": null,
                           "maximum_total": null
                       }
                   },
                   {
                       "label": "poknj",
                       "quantity": 1.0,
                       "original_quantity": 1,
                       "value": 20.0,
                       "total": 20.0,
                       "original_total": 20.0,
                       "template_item_details": {
                           "quantity_type": "count",
                           "quantity_config": {
                               "filters": [
                                   {
                                       "charge_type__in": [
                                           "card_onetime"
                                       ],
                                       "transaction_type__in": [
                                           "payment"
                                       ]
                                   }
                               ]
                           },
                           "value_type": "tiered",
                           "value_config": {
                               "tiers": [
                                   {
                                       "value": 20,
                                       "minimum_quantity": 0
                                   },
                                   {
                                       "value": 10,
                                       "minimum_quantity": 100
                                   }
                               ]
                           },
                           "minimum_quantity": null,
                           "minimum_total": null,
                           "maximum_quantity": null,
                           "maximum_total": null
                       }
                   }
               ],
               "total": 28.0
           }
    ],
       "filters": {
           "created_at__gte": "2020-07-31T23:00:00",
           "created_at__lte": "2020-08-04T22:59:59",
           "type": "default"
       },
       "pagination": {
           "page": 1,
           "per_page": 30,
           "total_pages": 1,
           "total_items": 1
       }
    }
  }

Templates

Reports are automatically generated from your transaction data. You can schedule reports and also define different types of reports. This is where templates come in. When setting up your Reporting system, you should consider the information you want to collect from your reports, beyond getting the full list of transactions for a given time period, you can monitor specific information that is relevant to the course of your business.

1
See the big picture.
For instance, get the gross amount of payments made in the last month. Label: Gross Amount, Quantity: Sum, Sum Field: Amount, Charge type: Check all, Transaction type: Payment, Value: Fixed.
2
Zoom into the details.
For instance, get the sum of exchange rate expenditures in all my payments. Label: MSC Fixed, Quantity: Sum, Fixed: 0.19, Charge type: Check All, Transaction Type: Payment, Value: Fixed.

Report Feature	Conditions
Description	Descriptions are strings set by the user. You can label the Reporting template according to your needs.
Currency	You can select multiple currencies from the available list.
Label	Templates can have multiple items which represent conditions present in that template. The label is the name you attribute to these conditions.
Quantity Fixed Count Sum	You can analyze transactions in reports by counting the absolute number of transactions that fit your conditions and also by generating a sum of the values present in those transactions.
Value Fixed Tiered	You can segment the values present in your reports either by a fixed interval or multiple intervals or tiers.
Minimum/Caps Quantity Total	It is possible to cap the transactions present in your reports at a minimum or maximum quantity and value of transactions.

POST `/v1/reporting/templates`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/templates` Production `https://merchant-api.switchpayments.com/v1/reporting/templates`	Create a new Reporting template.

Request Body Parameters

currencyStringRequired

Currency applied to the reports following this template.

descriptionStringRequired

Designation for the template being created.

labelStringRequired

Designation for each item of the template being created.

quantityStringRequired

Operation to be performed on the transactions included in this report. It can be fixed, sum or count.

valueStringRequired

How the results should be presented in the reports following this template, either fixed or tiered.

REQUEST
    $ curl -vX POST https://merchant-api.switchpayments.com/v1/reporting/templates?merchant_id=accountId -u accountId:APIKey
    {
       "currency": "EUR" ,
       "description": "Example01"
    }

Response Parameters

idString

Identification of the report template.

descriptionString

Designation for this template.

currencyString

Currency applied to the reports generated through this template.

created_atString

Date and time in which the report template was created.

updated_atString

Date and time in which the report template was last updated.

RESPONSE: HTTP 200 CREATED
    {
       "id": "1da379eaa030cede73d8e425968ecdcff51418285f3bec60",
       "description": "Example01",
       "currency": "EUR",
       "items": [],
       "created_at": "2020-08-18T14:57:36.382929+00:00",
       "updated_at": "2020-08-18T14:57:36.383009+00:00"
    }

PATCH `/v1/reporting/templates/{id}`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/templates/{id}` Production `https://merchant-api.switchpayments.com/v1/reporting/templates/{id}`	Make changes to an existing Reporting template.

Request Body Parameters

currencyString

In this example, we are making changes to the currency applied to the reports under this template. You can make changes to any of the parameters available in the creation of a Reporting template.

REQUEST
    $ curl -vX POST https://merchant-api.switchpayments.com/v1/reporting/templates/{id}?merchant_id=accountId -u accountId:APIKey
    {
       "currency": "USD"
    }

Response Parameters

idString

Identification of the report template.

descriptionString

Designation for this template.

currencyString

Currency applied to the reports generated through this template.

created_atString

Date and time in which the report template was created.

updated_atString

Date and time in which the report template was last updated.

RESPONSE: HTTP 201 OK
    {
       "id": "1da379eaa030cede73d8e425968ecdcff51418285f3bec60",
       "description": "Example01",
       "currency": "USD",
       "items": [],
       "created_at": "2020-08-18T14:57:36.382929+00:00",
       "updated_at": "2020-08-18T14:57:36.383009+00:00"
    }

DELETE `/v1/reporting/reports{id}`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/templates{id}` Production `https://merchant-api.switchpayments.com/v1/reporting/templates{id}`	Delete a report template.

REQUEST
  $ curl -vX DELETE https://merchant-api.switchpayments.com/v1/reporting/templates/{id}?merchant_id=accountId -u accountId:APIKey

RESPONSE: HTTP 204 NO CONTENT
    The server successfully processed the request and it is not returning any content.

Reporting Schedules

You can schedule your reports to be generated automatically on a particular date and with specific frequency to better match your monitoring needs. This can be accomplished by setting up a reporting schedule, you can create as many reporting schedules as you would like and associate them to previously set Reporting templates.

When creating a new Reporting schedule, you should keep in mind what Reporting template you intend to associate to this schedule, the frequency to which it should be set and also the date of the first occurrence for the data included and the timezone it should guide itself by.

POST `/v1/reporting/schedules`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/schedules` Production `https://merchant-api.switchpayments.com/v1/reporting/schedules`	Create a new Reporting schedule.

Request Body Parameters

base_report_descriptionString

Title attributed to the Reporting schedule.

execution_timezoneString

Timezone applied to the Reporting schedule.

first_executionDate

Starting date for the report information.

frequencyString

Frequency in which the reports should be generated. It can be monthly, weekly, or daily.

report_typeString

Reports should have the report_type set to default. Billing specific reports are set to billing.

templateString

Template applied to the reports in this Reporting schedule.

REQUEST
    $ curl -vX GET https://merchant-api.switchpayments.com/v1/reporting/schedules?merchant_id=accountId -u accountId:APIKey
    {
       “base_report_description”: "Repo"
       “execution_timezone”: "Europe/Lisbon"
       “first_execution”: "2020-05-05T18:00:00.000000+00:00"
       “frequency”: "monthly"
       “report_type”: "default"
       “template”: "862d7a6939de9eda2ce47af9cc2c848211ab5f0a5e7cc539"
    }

Response Parameters

base_report_descriptionString

Title attributed to the Reporting schedule.

created_atDate

Date in which this schedule was created.

execution_timezoneString

Timezone applied to the Reporting schedule.

first_executionDate

Starting date for the report information.

frequencyString

Frequency in which the reports should be generated. It can be monthly, weekly, or daily.

idString

Identifier for the reporting schedule.

report_metadataArray

Additional information included when creating the Reporting schedule.

report_typeString

Reports should have the report_type set to default. Billing specific reports are set to billing.

templateString

Template applied to the reports in this Reporting schedule.

updated_atDate

Date in which this schedule was last updated.

RESPONSE: HTTP 201 CREATED
    {
        base_report_description: "Repo"
        created_at: "2020-05-05T13:35:23.192929+00:00"
        execution_timezone: "Europe/Lisbon"
        first_execution: "2020-05-05T18:00:00.000000+00:00"
        frequency: "monthly"
        id: "c5190ed3006fa0797a64074ef5f619319fb342fc5eb16b9b"
        report_metadata: null
        report_type: "default"
        template: "862d7a6939de9eda2ce47af9cc2c848211ab5f0a5e7cc539"
        updated_at: "2020-05-05T18:00:00.336279+00:00"
      }

Billing

Besides setting reports to manage your own transactions, you can use the Reporting feature to generate Billing reports for your customers or sub-merchants. Billing works very similarly to Reporting, since the Billing report is effectively a type of report. When creating a Billing schedule the parameters included are the same as when creating a Reporting schedule.

Want to know more about the Switch Dashboard?

By enabling the Switch Dashboard you get access to a user-friendly management tool to oversee your transactions. Head over to Dashboard and learn more about it.

To create a Billing schedule using the Switch Dashboard you should consider the following procedure:

Select Merchants on the main menu.
Under Billing, select Add Billing Schedule.
Set up a new Billing schedule by inputting a title and selecting: the template to be applied in the reports generated; the frequency of these reports (monthly, daily, or weekly); the first occurrence, which to the start date and time of the report; the time zone.

POST `/v1/reporting/schedules`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/reporting/schedules` Production `https://merchant-api.switchpayments.com/v1/reporting/schedules`	Create a new Reporting schedule set to `report_type` Billing.

Request Body Parameters

base_report_descriptionString

Title attributed to the Billing schedule.

execution_timezoneString

Timezone applied to the Billing schedule.

first_executionDate

Starting date for the Billing report information.

frequencyString

Frequency in which the Billing reports should be generated. It can be monthly, weekly, or daily.

report_typeString

Billing reports should have the report_type set to billing. Other general reports are set to default.

templateString

Template applied to this Billing schedule. Billing shares templates with Reporting, therefore this template can be created using the Reporting application.

REQUEST
    $ curl -vX GET https://merchant-api.switchpayments.com/v1/reporting/schedules?merchant_id=accountId -u accountId:APIKey
    {
       “base_report_description”: "Temp"
       “execution_timezone”: "Europe/Lisbon"
       “first_execution”: "2020-05-05T18:00:00.000000+00:00"
       “frequency”: "monthly"
       “report_type”: "billing"
       “template”: "862d7a6939de9eda2ce47af9cc2c848211ab5f0a5e7cc539"
    }

Response Parameters

base_report_descriptionString

Title attributed to the Billing schedule.

created_atDate

Date in which this schedule was created.

execution_timezoneString

Timezone applied to the Billing schedule.

first_executionDate

Starting date for the Billing report information.

frequencyString

Frequency in which the Billing reports should be generated. It can be monthly, weekly, or daily.

idString

Identifier for the Billing schedule.

report_metadataArray

Additional information included when creating the Billing schedule.

report_typeString

Billing reports should have the report_type set to billing. Other general reports are set to default.

templateString

Template applied to this Billing schedule. Billing shares templates with Reporting, therefore this template can be created using the Reporting application.

updated_atDate

Date in which the Billing schedule was last updated.

RESPONSE: HTTP 201 CREATED
    {
        base_report_description: "Temp"
        created_at: "2020-05-05T13:35:23.192929+00:00"
        execution_timezone: "Europe/Lisbon"
        first_execution: "2020-05-05T18:00:00.000000+00:00"
        frequency: "monthly"
        id: "c5190ed3006fa0797a64074ef5f619319fb342fc5eb16b9b"
        report_metadata: null
        report_type: "billing"
        template: "862d7a6939de9eda2ce47af9cc2c848211ab5f0a5e7cc539"
        updated_at: "2020-05-05T18:00:00.336279+00:00"
      }

Next Steps

Jump into Switch interfaces, learn more about the capabilities of the Switch Dashboard and how it can simplify your payments operations.

Reporting

All of your transactions, summed up.

Create and Customize

Search and Filter

Share and Archive

Reports

Reporting Templates

Reporting Schedules

Billing

Reports

POST /v1/reporting/reports

Request Body Parameters

Response Parameters

DELETE /v1/reporting/reports{id}

GET /v1/reporting/reports

Request Body Parameters

Response Parameters

Templates

See the big picture.

Zoom into the details.

POST /v1/reporting/templates

Request Body Parameters

Response Parameters

PATCH /v1/reporting/templates/{id}

Request Body Parameters

Response Parameters

DELETE /v1/reporting/reports{id}

Reporting Schedules

POST /v1/reporting/schedules

Request Body Parameters

Response Parameters

Billing

Want to know more about the Switch Dashboard?

POST /v1/reporting/schedules

Request Body Parameters

Response Parameters

Next Steps

POST `/v1/reporting/reports`

DELETE `/v1/reporting/reports{id}`

GET `/v1/reporting/reports`

POST `/v1/reporting/templates`

PATCH `/v1/reporting/templates/{id}`

DELETE `/v1/reporting/reports{id}`

POST `/v1/reporting/schedules`

POST `/v1/reporting/schedules`