Reports API

Use the the Reports API to request bulk reports for merchants.

API Calls

Structures

Report States

new Indicates that the /report/create call was successfully executed.
processing The report is being prepared.
complete The report has been successfully prepared and is ready to be retrieved.
deleted The report has been deleted and no data from the report can be recovered. Reports are automatically deleted after four days. However, you can still retrieve the metadata for the report using the /report call and passing the report_id.
failed The report did not process and no data can be recovered. You can still retrieve the metadata for the report using the /report call and passing the report_id.

Report States Diagram

How it works

Reports are requested and received following these steps:

  1. Your platform requests a report via /report/create.
  2. WePay sends an IPN when the report is available - typically within 5 to 10 minutes.
  3. Your platform uses /report to obtain the link to download the report.
  4. Your platform can deliver the report (or just the report link) to the merchant in a variety of ways (see the “Receiving Reports” section below).

Requesting reports

Use /report/create to request a report. The request includes:

  • The type of report, e.g. merchant_transactions or reconciliation.
  • The callback URI at which your platform will get an IPN when the report is ready.
  • Advanced options: the same options in the wepay.com merchant reports user interface, as appropriate to each type of report (date ranges, for example).

Report processing

Reports are processed asynchronously, which typically takes 5 to 10 minutes. Your application will receive a callback when the report is ready. /report will initially show state new, which means the request has been received but has not started being processed. Once processing begins, /report will show state processing. Your application should monitor IPNs and wait for the report to be in state complete.

Receiving reports

When your application receives the IPN, it should call /report. Verify that the state is now complete, and then use the report URI to access the data. The URI will point to a comma-separated values (CSV) file. Rows are terminated with newlines. If report_uri parameter value is null, then the report is still processing. This should also be reflected in the state parameter.

Availability

Reports are available for four days from the time they are generated. WePay sends an IPN when the report is deleted.

Data Latency

There is delay between the time the data is created or modified and the time it is available for download in a report. For reconciliation reports, the delay is 6 hours. For transaction reports, the delay is 36 hours. Note that this is independent of the 5 to 10 minutes it takes to process a request. Report generation will automatically fail if the report is requested inside the data latency period.

Version: v2 2017-02-01

POST Endpoint

https://wepayapi.com/v2/reports

/report

Use this call to obtain information about a requested report and to obtain the URL from which your report can be downloaded.

Arguments

Parameter Required Type Description
report_id Yes Integer (64 bits) The unique ID of the report for which you want information.

Example

{
   "report_id": 12345
}

Response

Response Type Description
report_id Integer (64 bits) The unique ID of the report.
user_id Integer (64 bits) The ID of the WePay user for whom the report was requested.
type String (255 chars) The type of merchant report.

Possible values: merchant_transactions and reconciliation.
resource Report Resource Structure Describes the object on which this report is based.
advanced_options Advanced Options Structure Advanced options for this report.
state String (255 chars) The state of the report.

Possible values: new, processing, complete, deleted, and failed.
request_time Integer (64 bits) The Unix timestamp (UTC) when the report was requested
expires_time Integer (64 bits) The Unix time when the report will expire (UTC).
callback_uri String (255 chars) Where to send IPNs for this report.
report_uri String (255 chars) The URL from which the report may be downloaded. The value is null until the report generation is complete.

Example

{
   "report_id": 228925493,
   "user_id": 242359999,
   "resource": {
      "object_id": 216083312,
      "object_type": "account"
   },
   "type": "merchant_transactions",
   "advanced_options": {
      "start_time": 1455201963,
      "end_time":  1457707563
   },
   "state": "processing",
   "request_time": 1453839020,
   "expires_time": null,
   "callback_uri": null,
   "report_uri": null
}

/report/create

Use this call to request a report. The response contains the same data as the response to /report.

Arguments

Parameter Required Type Description
type Yes String (255 chars) The type of report.

Possible values: merchant_transactions and reconciliation.
resource Yes Report Resource Structure Identifies the object on which the report is based.
advanced_options No Advanced Options Structure Advanced options for this report.
callback_uri Yes String (255 chars) Where to send IPNs for this report.

Example

{
   "type":"merchant_transactions",
   "resource": {
      "object_type": "account",
      "object_id": 216083312
   },
   "advanced_options": {
      "start_time": 1455201963,
      "end_time":  1457707563
   },
   "callback_uri":"https://example.com/report/ipn"  
}

Response

Response Type Description
report_id Integer (64 bits) The unique ID of the report.
user_id Integer (64 bits) The ID of the WePay user for whom the report was requested.
type String (255 chars) The type of merchant report.

Possible values: merchant_transactions and reconciliation.
resource Report Resource Structure Describes the object on which this report is based.
advanced_options Advanced Options Structure Advanced options for this report.
state String (255 chars) The state of the report.

Possible values: new, processing, complete, deleted, and failed.
request_time Integer (64 bits) The Unix timestamp (UTC) when the report was requested
expires_time Integer (64 bits) The Unix time when the report will expire (UTC).
callback_uri String (255 chars) Where to send IPNs for this report.
report_uri String (255 chars) The URL from which the report may be downloaded. The value is null until the report generation is complete.

Example

{
   "report_id": 228925493,
   "user_id": 242359999,
   "resource": {
      "object_id": 216083312,
      "object_type": "account"
   },
   "type": "merchant_transactions",
   "advanced_options": {
      "start_time": 1455201963,
      "end_time":  1457707563
   },
   "state": "processing",
   "request_time": 1453839020,
   "expires_time": null,
   "callback_uri": null,
   "report_uri": null
}

Advanced Options Structure

Contains the Unix timestamps (UTC) for the date range of the report.

Fields

Field Required Type Description
start_time No Integer (64 bits) The start of the time range (UTC Unix timestamp) selected for the report data.
end_time No Integer (64 bits) The end of the time range (UTC Unix timestamp) selected for the report data.
disable_email No Boolean Flag to control whether or not an email is sent out when the generation of the report is complete

Default: true

Note: This field is only returned in the response. It is not a parameter that you can currently set in /report/create.

Example

{
   "advanced_options":{
      "start_time": 1468603385,
      "end_time": 1469208185,
      "disable_email": true  
   }
}

Report Resource Structure

Contains information about the resources about which the report is based.

Fields

Field Required Type Description
object_type Yes String (255 chars) The type of resource upon which the report is based.

Possible values: account and withdrawals.

Note: use account for merchant_transactions reports and withdrawal for reconciliation reports.
object_id Yes Integer (64 bits) The unique ID of the resource upon which this report is based. The resources referred to by this ID are the account_id or the withdrawal_id for the object specified in object_type, above.

Example

{
   "resource": {
      "object_type": "account",
      "object_id": 12345  
   }
}