Provide fraud feedback

Report transaction authorization status to improve fraud detection accuracy

To improve fraud detection accuracy and protect your cardholders from unauthorized transactions, provide feedback on transaction classifications using the Fraud Feedback API. This feedback helps Airwallex's fraud detection engine learn from your specific transaction patterns, reducing false positives while maintaining security.

Before providing feedback, ensure you have verified the transaction authorization status directly with the cardholder. Incorrect feedback can result in card blocking or exposure to fraud.

Before you begin

Before you provide fraud feedback, ensure you have:

A valid Airwallex API key with permissions to access the Fraud Feedback API.
The authorization ID of the transaction you want to report. Note that only authorization IDs are accepted for fraud feedback.
Verified with the cardholder whether they authorized the transaction.
Set up webhook endpoints to receive fraud detection events. For guidance, refer to Fraud detection and feedback.

Report an authorized transaction

To report that a transaction was legitimate and authorized by the cardholder, complete these steps:

Verify with the cardholder that they authorized the transaction.
Make a POST request to the Fraud Feedback API API with the following parameters:
Bash
```
1curl -X POST https://api.airwallex.com/api/v1/risk/issuing/fraud_feedback \
2  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "authorization_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
6    "cardholder_decision": "AUTHORIZED_BY_CARDHOLDER"
7  }'
```
Handle the API response to confirm the feedback was recorded successfully.

After you report a transaction as authorized, the cardholder can successfully retry the transaction within a reasonable time period with updated fraud controls. The card status changes to Active if it was previously Inactive.

Correct a mistaken authorization

If you mistakenly marked a transaction as authorized when it was actually fraudulent, promptly submit follow-up feedback with NOT_AUTHORIZED_BY_CARDHOLDER to block the card and prevent further unauthorized use.

Report an unauthorized transaction

To report that a transaction was fraudulent and not authorized by the cardholder, complete these steps:

Verify with the cardholder that they did not authorize the transaction.

Make a POST request to the Fraud Feedback API API with the following parameters:

Bash

1curl -X POST https://api.airwallex.com/api/v1/risk/issuing/fraud_feedback \
2  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "authorization_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
6    "cardholder_decision": "NOT_AUTHORIZED_BY_CARDHOLDER"
7  }'

Handle the API response to confirm the feedback was recorded successfully.
Notify the cardholder that their card has been blocked and advise them on next steps.

After you report a transaction as not authorized, the card is immediately blocked, preventing any further transactions. Only Airwallex Customer Support can unblock a blocked card.

Correct a mistaken fraud report

If you mistakenly marked a transaction as not authorized when it was actually legitimate, contact Airwallex Customer Support to unblock the card. You cannot unblock the card through the API or by submitting additional feedback.

Handle fraud detection webhook events

To provide a complete fraud feedback workflow, set up webhook handlers that receive fraud detection events and trigger cardholder verification:

Configure webhook endpoints in the Airwallex web app to receive issuing events.
Implement handlers for the following webhook event patterns:
- Approved transaction with risk warning: issuing.transaction.succeeded with risk_details object.
- Declined transaction with active card: issuing.transaction.failed with failure_reason set to SUSPECTED_FRAUD.
- Declined transaction with frozen card: issuing.transaction.failed with failure_reason set to SUSPECTED_FRAUD and issuing.card.inactive events.
- Declined transaction with blocked card: issuing.transaction.failed with failure_reason set to SUSPECTED_FRAUD and issuing.card.blocked events.
When you receive a fraud detection event, extract the risk_details object to understand what triggered the fraud rule.
Notify the cardholder through your preferred communication channel (email, SMS, push notification, or in-app message) asking them to verify whether they authorized the transaction.
Provide a mechanism for the cardholder to respond with their verification.
Based on the cardholder's response, submit fraud feedback using the steps in the previous sections.

Example webhook payload

When a transaction is declined due to suspected fraud and the card is frozen, you receive the following events:

JSON

1{
2  "event": "issuing.transaction.failed",
3  "data": {
4    "acquiring_institution_identifier": "123456",
5    "auth_code": "000001",
6    "billing_amount": 100,
7    "billing_currency": "USD",
8    "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
9    "card_nickname": "Airwallex Test Card",
10    "client_data": "Client data",
11    "digital_wallet_token_id": "2af871b8-466e-465e-a8de-eeaac9f82392",
12    "failure_reason": "SUSPECTED_FRAUD",
13    "fee_details": [
14      {
15        "amount": 10,
16        "currency": "USD",
17        "type": "ATM_ACCESS_FEE"
18      }
19    ],
20    "lifecycle_id": "95ede192-3a86-461e-96d9-f51b55aae79e",
21    "masked_card_number": "************4242",
22    "matched_authorizations": [
23      "6c2dc266-09ad-4235-b61a-767c7cd6d6ea"
24    ],
25    "merchant": {
26      "additional_merchant_info": {
27        "merchant_category": "Professional Services",
28        "merchant_full_name": "Meta",
29        "merchant_logo_url": "https://example.com/merchant-logo.png",
30        "merchant_sub_category": "Advertising and Marketing"
31      },
32      "category_code": "4829",
33      "city": "San Francisco",
34      "country": "USA",
35      "identifier": "012345678910123",
36      "name": "Merchant A",
37      "postcode": "94111",
38      "state": "CA"
39    },
40    "network_transaction_id": "3951729271768745",
41    "posted_date": "2025-03-22T16:08:02+00:00",
42    "retrieval_ref": "909916088001",
43    "risk_details": {
44      "risk_actions_performed": [
45        "TRANSACTION_BLOCKED"
46      ],
47      "risk_factors": [
48        "Suspicious transaction velocity"
49      ],
50      "three_dsecure_outcome": "AUTHENTICATED"
51    },
52    "status": "APPROVED",
53    "transaction_amount": 100,
54    "transaction_currency": "USD",
55    "transaction_date": "2025-03-21T16:08:02+00:00",
56    "transaction_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
57    "transaction_type": "CLEARING"
58  }
59}

JSON

1{
2  "event": "issuing.card.inactive",
3  "data": {
4    "additional_cardholder_ids": [
5      "4d694e2f-5294-41e5-b322-2e9b20238941"
6    ],
7    "authorization_controls": {
8      "allowed_currencies": [],
9      "allowed_merchant_categories": [],
10      "allowed_transaction_count": "MULTIPLE",
11      "transaction_limits": {
12        "currency": "USD",
13        "limits": [
14          {
15            "amount": 100.0,
16            "interval": "ALL_TIME"
17          },
18          {
19            "amount": 10000.0,
20            "interval": "PER_TRANSACTION"
21          }
22        ]
23      }
24    },
25    "brand": "VISA",
26    "card_id": "c5caf0ab-287c-4f74-8cde-84d52352bda3",
27    "card_status": "INACTIVE",
28    "cardholder_id": "52646a67-878f-46d6-b4b1-02601cd4c553",
29    "created_at": "2024-03-07T02:51:53.388+0000",
30    "created_by": "John Smith",
31    "form_factor": "VIRTUAL",
32    "is_personalized": false,
33    "name_on_card": "name on card",
34    "program": {
35      "purpose": "COMMERCIAL",
36      "sub_type": "GOOD_FUNDS_CREDIT",
37      "type": "CREDIT"
38    },
39    "purpose": "BUSINESS_EXPENSES",
40    "request_id": "d1064ar2-8ff0-4f9a-a5be-6d34dea8dc68",
41    "updated_at": "2024-03-07T02:51:53.388+0000"
42  }
43}

Use the combination of these events to trigger cardholder verification and determine the appropriate fraud feedback to submit.

Important considerations

When providing fraud feedback, keep the following considerations in mind:

Verify before submitting: Always verify the transaction status directly with the cardholder before submitting feedback. Incorrect feedback can disrupt legitimate transactions or expose your program to fraud.
Act promptly: Submit feedback as soon as possible after receiving the cardholder's verification to minimize the window for additional fraudulent transactions.
Card blocking is permanent: Once a card is blocked due to NOT_AUTHORIZED_BY_CARDHOLDER feedback, only Airwallex Customer Support can unblock it. Consider the impact before submitting this feedback type.
Monitor patterns: Review the risk_details in webhook events to understand common fraud patterns and adjust your fraud rules accordingly.
Handle errors gracefully: Implement error handling for API calls to ensure feedback is recorded even if the initial request fails.

Next steps

Now that you understand how to provide fraud feedback, explore related topics to enhance your card program:

Fraud detection and feedback to understand how fraud detection works.
Card statuses to learn about different card states and transitions.
Transaction failure reasons to understand why transactions are declined.

Was this page helpful?