Reports API

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

API Calls

/report
/report/create

Structures

Advanced Options Structure
Report Resource Structure

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:

Your platform requests a report via /report/create.
WePay sends an IPN when the report is available - typically within 5 to 10 minutes.
Your platform uses /report to obtain the link to download the report.
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.

Note

In the CSV report files, transaction related IDs (like payment_id, checkout_id, transaction_id, etc.) begin with one of the following prefixes:

RCBK - chargeback reversal
CBK - chargeback
RF - refund
C - payment
W - withdrawal

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 2019-04-03

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.

Caution

The report_uri returned by the /report call is publicly accessible and can lead to sensitive data that should be treated carefully (i.e. the report_uri should be stored securely and only shared with users that should have access to the data contained in the report).

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. Note: Your platform may test using ports in staging but ports are not allowed in production.

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. Default: If `start_time` is not provided, we will default to 30 days ago and round the timestamp to 00:00:00 UTC. If a date is provided, we round the timestamp to 00:00:00 UTC.
end_time	No	Integer (64 bits)	The end of the time range (UTC Unix timestamp) selected for the report data. Default: If `end_time` is not provided, we will default to 48 hours ago and round the timestamp to 23:59:59 UTC. If a date is provided, we round the timestamp to 23:59:59 UTC.
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)

Field	Required	Type	Description
object_type	Yes	String (255 chars)	The type of resource upon which the report is based. Possible values: `account` and `withdrawal`. 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.

The type of resource upon which the report is based.

Possible values: account and withdrawal.

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
    }
}