Watchlist

The Watchlist API is an automated tool for transaction verification and fraud prevention. With this API, merchants can create and manage Watchlists of shoppers to automatically accept, verify, or block transactions. To add a Watchlist item, please use the ‘create’ endpoint. To make changes to an existing Watchlist item, please use the ‘update’ endpoint. To retrieve a specific item in the Watchlist, please provide the item_id with the ‘get’ endpoint.

Endpoints

GET /api/v1/risk/watchlist
GET /api/v1/risk/watchlist/{item_id}
POST /api/v1/risk/watchlist/{item_id}/update
POST /api/v1/risk/watchlist/create

Get list of items

GET /api/v1/risk/watchlist

Copy for LLMView as Markdown

Get list of items with optional filters, sorted by the item creation date in descending order.

Parameters

actionstring

Filter on action of Watchlist item.

from_created_atstring

The start date of created_at in ISO8601 format (yyyy-MM-dd'T'HH:mm:ssZ). The default is 30 days before to_create_at.

pagestring

A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.

page_sizeinteger

A limit on the number of records to be returned on a page, between 1 and 2000. The default is 100.

statusstring

Filter on status of Watchlist item.

to_created_atstring

The end date of created_at in ISO8601 format (yyyy-MM-dd'T'HH:mm:ssZ). The default is current time.

typestring

Filter on type of Watchlist item.

valuestring

Filter on value of Watchlist item.

Response body - 200 OK

itemsarray

Paged results.

items.actionstring

Risk action to be taken by the risk engine: Use BLOCK, VERIFY, ACCEPT to always perform the associated risk action. The risk engine will prioritize actions in the following order: BLOCK>VERIFY>ACCEPT. Please note that ACCEPT functionality will only be available to users with good fraud performance and will be subject to reasonable usage limits.

items.created_atstring

The latest timestamp the Watchlist item was created.

items.idstring

Unique identifier for the item.

items.reasonstring

The reason for adding this item to the Watchlist.

items.request_idstring

Unique request id for the item.

items.statusstring

The status of the list item will be one of: ACTIVE, INACTIVE, DEACTIVATED. Default is ACTIVE. Some list items may be forcefully DEACTIVATED based on fraud performance.

items.typestring

The type of the Watchlist item.

items.updated_atstring

The latest timestamp the Watchlist item was updated.

items.valuestring

The value of the item corresponding to the correct type.

page_afterstring

The page cursor used for searching after page.

page_beforestring

The page cursor used for search before page.

Errors

Error status	Description
400	Possible errors: `invalid_operation`
401	Unauthorized
403	Possible errors: `account_not_authorised_for_operation`
404	Possible errors: `resource_not_found`
500	Possible errors: `internal_server_error`

GET /api/v1/risk/watchlist

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/risk/watchlist' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "action": "BLOCK",
5      "created_at": "2023-01-01T00:00:00+0000",
6      "reason": "risk concern",
7      "status": "ACTIVE",
8      "type": "CUSTOMER_EMAIL",
9      "updated_at": "2023-01-01T00:00:00+0000",
10      "value": "[email protected]"
11    }
12  ],
13  "page_after": "YWZ0ZXI9MTk5MTI3NzEtNjRmZi00NjljLTlkZTItY2I1MzM1OWU5NWZj",
14  "page_before": "YWZ0ZXI9MTk5MTI3NzEtNjRmZi00NjljLTlkZTItY2I1MzM1OWU5NWZj"
15}

Was this section helpful?

Get a item by ID

GET /api/v1/risk/watchlist/{item_id}

Copy for LLMView as Markdown

Get a specific Watchlist item by specifying the Airwallex item_id.

Parameters

item_idrequiredstring

item_id of the item to retrieve.

Response body - 200 OK

actionstring

created_atstring

The latest timestamp the Watchlist item was created.

idstring

Unique identifier for the item.

reasonstring

The reason for adding this item to the Watchlist.

request_idstring

Unique request id for the item.

statusstring

The status of the list item will be one of: ACTIVE, INACTIVE, DEACTIVATED. Default is ACTIVE. Some list items may be forcefully DEACTIVATED based on fraud performance.

typestring

The type of the Watchlist item.

updated_atstring

The latest timestamp the Watchlist item was updated.

valuestring

The value of the item corresponding to the correct type.

Errors

Error status	Description
401	Unauthorized
403	Possible errors: `account_not_authorised_for_operation`
404	Possible errors: `resource_not_found`
500	Possible errors: `internal_server_error`

GET /api/v1/risk/watchlist/{item_id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/risk/watchlist/item_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "action": "BLOCK",
3  "created_at": "2023-01-01T00:00:00+0000",
4  "id": "<string>",
5  "reason": "risk concern",
6  "request_id": "<string>",
7  "status": "ACTIVE",
8  "type": "CUSTOMER_EMAIL",
9  "updated_at": "2023-01-01T00:00:00+0000",
10  "value": "[email protected]"
11}

Was this section helpful?

Update item by ID

POST /api/v1/risk/watchlist/{item_id}/update

Copy for LLMView as Markdown

Edit an existing Watchlist item stored on the Airwallex platform.

Parameters

item_idrequiredstring

item_id of the list item to update.

Request body

reasonstring

The reason for adding this item to the Watchlist.

request_idrequiredstring

Unique id for the request.

statusstring

The status of the list item should be one of:ACTIVE,INACTIVE. Default is:ACTIVE.

valuestring

The value of the item corresponding to the correct type.

Response body - 200 OK

actionstring

created_atstring

The latest timestamp the Watchlist item was created.

idstring

Unique identifier for the item.

reasonstring

The reason for adding this item to the Watchlist.

request_idstring

Unique request id for the item.

statusstring

The status of the list item will be one of: ACTIVE, INACTIVE, DEACTIVATED. Default is ACTIVE. Some list items may be forcefully DEACTIVATED based on fraud performance.

typestring

The type of the Watchlist item.

updated_atstring

The latest timestamp the Watchlist item was updated.

valuestring

The value of the item corresponding to the correct type.

Errors

Error status	Description
400	Possible errors: `invalid_operation`
401	Unauthorized
403	Possible errors: `account_not_authorised_for_operation`
404	Possible errors: `resource_not_found`
409	Possible errors: `list_item_duplicate`
500	Possible errors: `internal_server_error`

POST /api/v1/risk/watchlist/{item_id}/update

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/risk/watchlist/item_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "reason": "risk concern",
>  "request_id": "<string>",
>  "status": "ACTIVE",
>  "value": "[email protected]"
>}'

Response (200 OK)

1{
2  "action": "BLOCK",
3  "created_at": "2023-01-01T00:00:00+0000",
4  "id": "<string>",
5  "reason": "risk concern",
6  "request_id": "<string>",
7  "status": "ACTIVE",
8  "type": "CUSTOMER_EMAIL",
9  "updated_at": "2023-01-01T00:00:00+0000",
10  "value": "[email protected]"
11}

Was this section helpful?

Add an item to the watchlist

POST /api/v1/risk/watchlist/create

Copy for LLMView as Markdown

Add an item to the Watchlist.

Request body

actionrequiredstring

reasonstring

The reason for adding this item to the Watchlist.

request_idrequiredstring

Unique id for the request

statusstring

The status of the list item should be one of:ACTIVE,INACTIVE. Default is:ACTIVE.

typerequiredstring

The type of the Watchlist item: CARD_BIN, CARD_FINGERPRINT, CARD_ISSUER_COUNTRY_CODE, CUSTOMER_EMAIL, CUSTOMER_ID. Please note that ACCEPT Watchlist only supports CARD_FINGERPRINT, CUSTOMER_EMAIL and CUSTOMER_ID. The following data fields are case sensitive: CARD_FINGERPRINT, CUSTOMER_ID.

valuerequiredstring

The value of the item corresponding to the correct type.

Response body - 201 Created

actionstring

created_atstring

The latest timestamp the Watchlist item was created.

idstring

Unique identifier for the item.

reasonstring

The reason for adding this item to the Watchlist.

request_idstring

Unique request id for the item.

statusstring

The status of the list item will be one of: ACTIVE, INACTIVE, DEACTIVATED. Default is ACTIVE. Some list items may be forcefully DEACTIVATED based on fraud performance.

typestring

The type of the Watchlist item.

updated_atstring

The latest timestamp the Watchlist item was updated.

valuestring

The value of the item corresponding to the correct type.

Errors

Error status	Description
400	Possible errors: `invalid_operation`
401	Unauthorized
403	Possible errors: `account_not_authorised_for_operation`
404	Possible errors: `resource_not_found`
409	Possible errors: `list_item_duplicate`
500	Possible errors: `internal_server_error`

POST /api/v1/risk/watchlist/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/risk/watchlist/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "action": "BLOCK",
>  "reason": "risk concern",
>  "request_id": "request_id",
>  "status": "ACTIVE",
>  "type": "CUSTOMER_EMAIL",
>  "value": "[email protected]"
>}'

Response (201 Created)

1{
2  "action": "BLOCK",
3  "created_at": "2023-01-01T00:00:00+0000",
4  "id": "<string>",
5  "reason": "risk concern",
6  "request_id": "<string>",
7  "status": "ACTIVE",
8  "type": "CUSTOMER_EMAIL",
9  "updated_at": "2023-01-01T00:00:00+0000",
10  "value": "[email protected]"
11}

Was this section helpful?