Async status updates

Fraugster expects to receive additional information on the transaction status to train the Engine on fraud trends and reimburse you for your fraud losses (if you are a Chargeback Protection customer). Send an async update for the transaction stored by Fraugster when more information becomes available to you. Common use cases for async updates include:

• A fraud chargeback took place.
• A transaction was concluded as fraudulent.
• The transaction was written off as a loss.
• The transaction amount was refunded.
• The transaction went into debt collection.

The Dashboard displays transaction statuses in the order they are received by the Fraugster API. Otherwise the order does not affect how we interpret the statuses. For example, if a transaction receives the status chargeback with a reason code, this marks the transaction as fraudulent, even if another status is received for it later.

An async transaction update is a JSON object where each key is a unique transaction ID represented by trans_id, and the corresponding value is an object that represents the update.

The value of trans_id must be identical to the one you sent for this transaction in your initial API request. If the values differ, we won't be able to connect the update with the actual transaction.

Read more about trans_id in Required datapoints.

Accepted fields

The update object accepts the following fields only. Some of them may be mandatory depending on the async status you're sending.

Field	Required	Description
status	yes	The new status of the transaction. Takes a limited set of values, see Possible status values for more information.
ts	yes	An RFC3339-encoded UTC timestamp without milliseconds. The timezone accepts either the character "Z" to indicate UTC or a time offset in the format "+02:00" or "-07:30".
chbk_reason_code	yes	The chargeback reason code. Required if the status is chargeback. This field accepts only specific values. Refer to the complete list of accepted values when you send this field with the status chargeback.
chbk_amt	yes	The original chargeback amount. Required if the status is chargeback.
chbk_currency	yes	The ISO 4217 currency code of the chargeback amount. Required if the status is chargeback.
dispute_reason	no	Specifies the reason for opening a dispute. Send this field if you're sending the status dispute_opened. The field accepts the following values only: not_received: The buyer didn't receive the item they had ordered. not_as_described: The buyer received a wrong item or an item described differently on the e-commerce website. fraud: The buyer has reported a fraud incident for this transaction. other: Any other reason not covered by the previous values.
loss_rsn	no	The reason for writing the transaction off as a loss. Can be sent with the status debt_collection_loss or pre_debt_collection_loss. The field normally contains any supplementary loss reason information in addition to the mandatory loss_rsn_category.
loss_rsn_category	yes	A way to categorize transactions written off as a loss. Required if the status is debt_collection_loss or pre_debt_collection_loss. This field can take one of the following values only: fraud: The transaction was written off as loss due to fraud. insolvent: The transaction was written off as loss due to credit issues, i.e. buyer's inability to pay. other: Any other reason that doesn't fit into fraud or insolvent category.
status_update_amt	yes	The amount of the status update. Required if the status is debt_collection_loss downtime dunning_fees item_not_as_described item_not_received refund returned timeout paid pre_debt_collection_loss
status_update_currency	yes	ISO 4217 currency code of the status update currency. Required if the status is debt_collection_loss downtime dunning_fees item_not_as_described item_not_received refund returned timeout paid pre_debt_collection_loss
bank_transfer_return_rsn	no	Specifies the reason a bank transfer got reversed. Reasons may include: high_risk_txn: The bank identified the transaction to be of high risk. item_not_received: The buyer didn't receive the item they had ordered. insufficient_funds: The bank didn't find sufficient funds on buyer's account. wrong_item: The buyer received a wrong item or an item described differently on the e-commerce website. damaged_item: The buyer received a damaged item. unknown_txn: The buyer didn't recognize the transaction and requested to reserve it. other: Any other reason not covered in the list. Send the reason with the status bank_transfer_return.
reversed_rsn	no	The reason for marking an approved transaction fraudulent after a manual review. Can be sent with the status reversed.
refund_rsn	no	The reason for refunding a transaction. Can be sent with the status refund.

Important

Updating transactions is a batch operation, so please group multiple transaction updates in one API request.

Sending multiple updates for the same transaction is not possible in one API call. If you want to update the same transaction with different statuses, you need to make multiple API calls.

HTTP endpoint

PATCH/api/v2/transaction

Body example

{
  "d72xfdil915889fu": {
    "status": "debt_collection_loss",
    "ts": "2018-08-28T15:04:05Z",
    "status_update_amt": 17.99,
    "status_update_currency": "EUR",
    "loss_rsn": "credit"
  },
  "124sa987gjk0at61": {
    "status": "chargeback",
    "ts": "2018-08-28T15:22:11Z",
    "chbk_reason_code": "10.4",
    "chbk_amt": 42.99,
    "chbk_currency": "EUR"
  },
  "424sa987gok0at90ty": {
    "status": "insufficient_funds",
    "ts": "2018-08-28T15:04:07Z"
  }
}

Possible status values

Update the status of each transaction as soon as more information becomes available to you. The status field can have a limited set of values. We accept only statuses defined in the documentation. If you send status values that are not supported, we can't process them.

We've grouped accepted async statuses by payment methods for a better overview. Here's a reminder of the payment methods accepted at Fraugster:

• Bank transfer
• BNPL
• Cards
• Cash
• Digital wallet
• Direct debit
• Mobile
• Prepaids/vouchers/giftcards

All payment methods

Status	Description
approved_manual	You reviewed the transaction manually and determined that it isn't fraudulent.
cancellation_requested	The payment company asked the merchant not to ship the goods for reasons of possible fraud.
fraud_confirmed	The transaction is concluded as fraudulent by the merchant or by the payment service provider.
fraud_suspicious	You reviewed the transaction and have a reason to suspect fraud. Once the fraud has been confirmed, please send fraud_confirmed.
refund	The full or partial transaction amount was refunded. Requires status_update_amt and status_update_currency to be processed. You may send refund_rsn with this status with more details on the refund reason (for example, frauds).
returned	The buyer returned the goods to the merchant. If the buyer returned only some of the goods ordered, you can optionally send status_update_amt and status_update_currency to account for the partial return scenario.

BNPL

Status	Description
debt_collection_loss	The transaction was written off as a loss after the debt collection process. Requires status_update_amt, status_update_currency, and loss_rsn_category to be processed. Additionally, you can send loss_rsn with this status update.
debt_collection	The transaction went into debt collection.
dunning_fees	The merchant sent a message to the buyer about a payment being due with dunning fees accrued. Requires status_update_amt (the dunning fees amount) and status_update_currency to be processed.
pre_debt_collection_loss	The transaction was written off as a loss before the debt collection process. Requires status_update_amt, status_update_currency, and loss_rsn_category to be processed. Additionally, you can send loss_rsn with this status update.

Cards

Status	Description
cancelled_claim	The chargeback was cancelled.
chargeback	The transaction received a chargeback. Requires chbk_reason_code, chbk_amt, and chbk_currency to be processed.
captured	The card authorization was captured and the request was processed successfully by the payment processor.

Cash

Status	Description
closed	The cash payment was not finalized within 30 days.

Miscellaneous

Status	Description
bank_transfer_return	The bank transfer was reversed. Send bank_transfer_return_rsn with this status if you want to specify why the transfer was reversed. Applicable to the following payment methods: Bank transfer BNPL Direct debit
cancelled	The merchant declined the transaction prior to the shipment. The cancellation happened after the user authorization, but before the capture. If the capture did happen, please use the status refund. Applicable to all payment methods except for cash and mobile.
cancelled_recurring	The buyer disputes a recurring transaction that was processed after it was canceled or their account was closed. Suitable for non-card transactions. For card transactions, please use the status chargeback. Applicable for all payment methods except for cash.
dispute_accepted	A buyer's dispute was accepted by the payment method provider. Applicable to the following payment methods: Digital wallet Prepaids/vouchers/giftcards
dispute_cancelled	An open dispute was cancelled by the buyer. Applicable to the following payment methods: Digital wallet Prepaids/vouchers
dispute_denied	A buyer's dispute was denied by the payment method provider. Applicable to the following payment methods: Digital wallet Prepaids/vouchers/giftcards
dispute_opened	A dispute has been opened by the buyer for this transaction. If you send this status, specify the reason indicated by the buyer in the field dispute_reason (takes specific values only). Applicable to the following payment methods: Digital wallet Prepaids/vouchers/giftcards
paid	The invoice has been paid. Requires status_update_amt and status_update_currency to be processed. Applicable to the following payment methods: BNPL Cash
reversed	The transaction was reversed by the user. You may send reversed_rsn with this status outlining more details on the reason. Applicable to the following payment methods: Digital wallet Mobile Prepaids/vouchers/giftcards For card payments, use the status chargeback. For direct debit, BNPL, and online banking, use bank_transfer_return. If you are returning a payment, use the status refund.

Please note

We removed the field extra with the 3.4 Fraugster release. The new architecture of async status updates is cleaner and doesn't include the nested extra object. The new architecture is backward compatible, i.e. existing integrations continue to work as expected.

How to send async status updates

Fraugster API

We recommend you use the Fraugster API to send status updates to us. If your integration with Fraugster or a payment gateway allows to send status updates via the API, it's the preferred way to manage large data volumes in real time.

CSV files

If your integration with Fraugster or with your payment gateway doesn't allow you to send status updates via the API, share them in a CSV file uploaded to the SFTP server.

Make sure you generate a CSV file that follows the requirements. All the requirements below are mandatory.

Technical requirements for CSV files

• The CSV file should follow the RFC-4180 standard.
• The CSV file should be encoded in UTF-8.
• The file should contain records with one or more fields per record.
• The first record (i.e. the first line) in each file should be the header. A header is a record with field names.
• Each record in the file should be separated by the newline character \n. The final record may be followed by the newline character.
• Fields in a record should be separated by a comma ,. Values in a field should be separated by a semicolon ;.
• All records should have the same number of fields.
• If a field contains a timestamp, it must be encoded using the RFC-3339 format with the correct timezone information (preferably UTC).

How we treat certain characters in CSV files

• White spaces are considered part of the field.
• Carriage returns before the new line character are removed (i.e. \r\n is interpreted as \n).
• Blank lines are ignored.
• Fields which start and end with the quotation marks "" are called quoted fields (as defined in RFC-4180).
• The quotation marks are not considered part of the quoted field.

Content of CSV files

To match status updates to the original transactions, the file must contain a unique identifier – either the Transaction ID trans_id that you sent to us with the first API call or the Acquirer reference ID acq_ref_id that you send along with your sync status update via the Fraugster API.

If you cannot provide a unique identifier in your CSV file, please contact the Customer Support team at [email protected]."

In addition to the unique identifier, make sure to send supporting information about the update: when it occurred, its amount, currency, and loss reason. Refer to the below use cases for specific information and sample files.

See the API documentation for a complete list of allowed async status updates. We accept only statuses defined in the documentation. If you send status values that are not supported, we can't process your files.

Use case 1: You process card payments and can provide the Transaction ID

Field name	Fraugster field name	Description
Transaction ID	trans_id	The ID of the original transaction sent to Fraugster. It allows us to accurately match the fraud case to the original transaction. If you cannot send the original transaction ID, make sure that you send the acquirer reference ID.
Status update	status	The status of the transaction. (eg. chargeback). Read more on possible status values in Async status updates.
Timestamp	ts	The timestamp of the status update in RFC 3339 format.
Chargeback reason code	chbk_reason_code	The chargeback reason code as sent by your acquiring bank.
Chargeback amount	chbk_amt	The amount of the filed chargeback.
Chargeback currency	chbk_currency	The currency in which the chargeback was filed.

⬇️ Download a sample CSV file for this use case:

sample_card_TransactionID_available.csv

Use case 2: You process card payments and can provide the Acquirer reference ID

Field name	Fraugster field name	Description
Acquirer reference ID	acq_ref_id	The Reference ID issued by your acquiring bank along with the sync status update (approved). Make sure to include the acquirer reference ID during the sync status update, and in the CSV file. This way we can match the chargeback to the transaction correctly.
Status update	status	The status of the transaction. (eg. chargeback, fraud_confirmed, debt_collection_loss). Read more on possible status values in Async status updates.
Timestamp	ts	The timestamp of the status update in RFC 3339 format.
Chargeback reason code	chbk_reason_code	The chargeback reason code as sent by your acquiring bank.
Chargeback amount	chbk_amt	The amount of the filed chargeback.
Chargeback currency	chbk_currency	The currency in which the chargeback was filed.

⬇️ Download a sample CSV file for this use case:

sample_card_AcquirerReferenceID_available.csv

Use case 3: You process no-card payments

Field name	Fraugster field name	Description
Transaction ID	trans_id	The ID of the original transaction sent to Fraugster. It allows us to accurately match the fraud case to the original transaction.
Status update	status	The status of the transaction. (eg. fraud_confirmed, debt_collection_loss). Read more on possible status values in Async status updates.
Timestamp	ts	The timestamp of the status update in RFC 3339 format.
Status update currency	status_update_currency	The currency of the status update.
Status update amount	status_update_amt	The amount of the status update.
Loss reason	loss_rsn	The reason for which the fraud case occurred.

⬇️ Download a sample CSV file for this use case:

sample_noncard_transactions.csv

Fraugster SFTP

If your integration with Fraugster doesn't allow you to send async status updates via the API yet, you can use an SFTP server. Automate the upload of your settlement reports from the acquirer or payment gateway to Fraugster.

SFTP credentials

Talk to our Customer Support team at [email protected] and confirm that this is your preferred way to provide async status updates. The team will provide you with access credentials.

Make sure to check the CSV file requirements before you submit the files.