Risk Reports

The Risk Reports API lets merchants self-serve their own risk datasets. The currently supported report type is PAYMENT_FRAUD_REPORT, which contains payment fraud data reported through acquirer TC40 / SAFE reports for a given date range.

Use Generate a risk report to submit a query and obtain a report id, followed by Retrieve a risk report to track the report status. When the report reaches COMPLETED status, obtain a short-lived signed download link. Reports are generated asynchronously. Subscribe to the risk.risk_reports.completed and risk.risk_reports.failed webhook events to be notified when a report is ready or generation has failed.

Endpoints

GET /api/v1/risk/risk_reports/{id}
POST /api/v1/risk/risk_reports/generate

Retrieve a risk report

GET /api/v1/risk/risk_reports/{id}

Copy for LLMView as Markdown

Fetches the status of a risk report and, once the report is COMPLETED, returns a short-lived signed download link. The link is regenerated on each poll, so an expired link is replaced with a new link on the next call.

Path parameters

idrequiredstring

Unique ID of the risk report.

Response body - 200 OK

end_datestring

End date of the report (UTC).

failure_reasonstring

Reason the report failed. Populated when status is FAILED.

fileobject

File result. Present when status is COMPLETED.

file.download_urlstring

File download URL.

file.expires_atstring

File download URL expiration date.

file.namestring

File name of the report.

idstring

Unique ID of the report.

start_datestring

Start date of the report (UTC).

statusstring

Status of the report.

PENDING

COMPLETED

FAILED

typestring

Type of report requested.

PAYMENT_FRAUD_REPORT

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	Possible errors: `permission_denied`
404	Possible errors: `resource_not_found`
500	Possible errors: `internal_server_error`

GET /api/v1/risk/risk_reports/{id}

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/risk/risk_reports/320ef695-691a-4827-93f0-227155efca8a' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "id": "320ef695-691a-4827-93f0-227155efca8a",
3  "status": "COMPLETED",
4  "start_date": "2026-04-01",
5  "end_date": "2026-06-30",
6  "type": "PAYMENT_FRAUD_REPORT",
7  "file": {
8    "name": "risk_report_123.csv",
9    "download_url": "https://files.airwallex.com/d/320ef695-691a-4827-93f0-227155efca8a?signature=abc123",
10    "expires_at": "2026-07-10T02:41:12Z"
11  }
12}

Was this section helpful?

Generate a risk report

POST /api/v1/risk/risk_reports/generate

Copy for LLMView as Markdown

Submits a risk report query for the authenticated merchant. Returns immediately with an id; the report is generated asynchronously. Poll the Retrieve a risk report endpoint (GET /api/v1/risk/risk_reports/{id}) using the returned id to track progress. When the report reaches COMPLETED status, obtain a short-lived signed download link.

Request body

end_daterequiredstring

End date (inclusive, in YYYY-MM-DD format, UTC) to specify the data records that the report should include. This parameter is a filter for:

Fraud reported date in the PAYMENT_FRAUD_REPORT

For example, request a risk report with start_date = 2026-04-01 and end_date = 2026-06-30 to obtain records from 2026-04-01 to 2026-06-30 inclusive, in UTC.

The max interval size between start_date and end_date is 90 days.

start_daterequiredstring

Start date (inclusive, in YYYY-MM-DD format, UTC) to specify the data records that the report should include. This parameter is a filter for:

Fraud reported date in the PAYMENT_FRAUD_REPORT

For example, request a risk report with start_date = 2026-04-01 and end_date = 2026-06-30 to obtain records from 2026-04-01 to 2026-06-30 inclusive, in UTC.

The max interval size between start_date and end_date is 90 days.

typerequiredstring

Type of report requested.

PAYMENT_FRAUD_REPORT

Payment fraud reported data, including the Visa TC40 and Mastercard SAFE reports.

Response body - 201 Created

end_datestring

End date of the report (UTC).

failure_reasonstring

Reason the report failed. Populated when status is FAILED.

fileobject

File result. Present when status is COMPLETED.

file.download_urlstring

File download URL.

file.expires_atstring

File download URL expiration date.

file.namestring

File name of the report.

idstring

Unique ID of the report.

start_datestring

Start date of the report (UTC).

statusstring

Status of the report.

PENDING

COMPLETED

FAILED

typestring

Type of report requested.

PAYMENT_FRAUD_REPORT

Errors

Error status	Description
400	Possible errors: `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	Possible errors: `permission_denied`
429	Too many requests
500	Possible errors: `internal_server_error`

POST /api/v1/risk/risk_reports/generate

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/risk/risk_reports/generate' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "start_date": "2026-04-01",
>  "end_date": "2026-06-30",
>  "type": "PAYMENT_FRAUD_REPORT"
>}'

Response (201 Created)

1{
2  "id": "320ef695-691a-4827-93f0-227155efca8a",
3  "status": "PENDING",
4  "start_date": "2026-04-01",
5  "end_date": "2026-06-30",
6  "type": "PAYMENT_FRAUD_REPORT"
7}

Was this section helpful?