Sync status updates

Fraugster expects a sync status update on each transaction as soon as you receive an API response on the transaction authorization. The update should include the new status of the transaction with a timestamp. It may be necessary that you include additional information in the status update – read more in this article.

How to send sync status updates

You send sync status update to Fraugster via the Fraugster API. We expect a sync status update for each transaction to indicate whether the issuer approved it. Updating transactions is a batch operation, so please group multiple transaction updates in one API request.

The API call with a sync status update can contain a determined set of values only. Read more about possible values in Possible status values.

A sync 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.

The update object accepts the following fields:

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".
acq_ref_id	Yes	Indicates the Acquirer Reference ID, which tags a credit card transaction when it goes from the merchant's bank (the acquiring bank) through the card scheme to the cardholder's bank (the issuer). Sending this ID facilitates reconciliation and chargeback mapping. Required if You are a Chargeback Protection customer, and You operate with the credit card payment method, and The sync status is approved.
issuer_reason_code	No*	Indicates the reason why the acquirer declined or approved a credit card transaction. You may send this field if You are a Chargeback Protection customer, and You operate with the credit card payment method, and The sync status is declined or approved. This field accepts only specific values. Refer to the complete list of accepted values if you intend to send this field in the sync status update.
issuer_decline_reason	No*	Indicates the reason why the acquirer declined a credit card transaction. You may send this field if You are a Chargeback Protection customer, and You operate with the credit card payment method, and The sync status is declined. This is a string field where you can send any reason you want to share. If you want to send an industry-specific reason code coming from the acquirer, send the field issuer_reason_code instead with the specific value it accepts.

* Please note: For a declined transaction, you're required to send at least one of the following fields: issuer_reason_code or issuer_decline_reason, not both of them.

HTTP endpoint

PATCH/api/v2/transaction

Body example

{
  "d72xfdil915889fu": {
    "status": "approved",
    "ts": "2018-08-28T15:04:05Z",
    "acq_ref_id": "120100-479105-61D2C749-57E9"
  },
  "124sa987gjk0at61": {
    "status": "frg_declined",
    "ts": "2018-08-28T15:22:11Z"
  },
  "424sa987gok0at90ty": {
    "status": "declined",
    "ts": "2018-08-28T15:04:07Z",
    "issuer_decline_reason": "Expired card"
  }
}

Curl command

curl -i \
-X PATCH https://api.fraugsterapi.com/api/v2/transaction \
-H "Authorization:SessionToken KWqrUW4wUu7cJ5e5A7i2iNd" \
-d '{"424sa987gok0at90ty": {"status": "declined","ts": "2018-08-28T15:04:07Z","issuer_decline_reason": "Expired card"}}'

Possible status values

Update the status of each transaction as soon as you receive a response from the issuer. The update should include the status of the transaction with a timestamp. The status field can have a limited set of values. We accept only the statuses defined in the documentation.

Status	Description
approved	The transaction was approved by the issuer. Requires acq_ref_id to be processed.
approved_recurring	The recurring transaction was approved by the issuer or merchant.
declined	The transaction was declined by the issuer. Requires issuer_decline_reason or issuer_reason_code to be processed.
declined_fraudscreening	The transaction was declined by a different fraud detection solution.
error	The transaction wasn't authorized due to an error, for example, a connection issue between you and the acquirer.
frg_declined	The transaction was declined following Fraugster's suggestion and was not sent for further authorization to the bank.
payment_pending	A future-dated payment was approved and awaits to be processed/completed by the user.

Additional data to support sync status updates

It may be necessary that you include additional information for some sync status updates. The update JSON object accepts the following fields only:

Field	Description
authentication_status	Indicates the authentication status following SCA (3DS). Relevant in cases where Fraugster processed the transaction prior to authentication and/or authorization. Include if the status is approved or declined. Possible values are: fully_authenticated: The user was fully authenticated with 2FA. partially_authenticated: The user was authenticated without completing 2FA. not_authenticated: The user was not authenticated by the issuing bank. failed_authentication: The user failed or cancelled the authentication. unable: authentication was not carried out due to a technical error.
exemption_type_raised	Indicates the SCA exemption type that was raised following Fraugster's advice. Please note: Fraugster can advise on multiple exemption types per transaction. Include it if the status is approved or declined. Possible values are: out_of_scope: The transaction is out of scope for PSD2 (eg. issuer outside of EEA). low_value: The transaction is of low value (eg. the value of the transaction is under €30). low_risk: The transaction is assessed by our Engine as low risk. recurring_transaction: The transaction is a recurring transaction with the exact same amount.
http_status_code	The HTTP status code received after sending a scoring request to the Fraugster API.
latency	The latency in milliseconds between the request and the response as detected in your systems.

Please note

We removed the field extra with the 3.4 Fraugster release. The new architecture of sync 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.