Post-purchase Updates - Overviews

Post-purchase Updates

Ensure that Forter’s system has the most up-to-date information about the status of individual orders, including payment authorization (for pre-auth flows), fulfillment status, and returns or compensation.

This helps Forter protect your company by ensuring that changes in an order status don’t expose your company to fraud. For example, if a customer calls up your customer support and asks to change the address to which they’re sending their delivery then that might be a suspicious sign, depending on the address used. By sending Forter order status updates, your company can make sure Forter has the ongoing information we need to protect you. Our goal is to understand if the order was authorized by the bank, completed/delivered, or rejected/canceled at a later phase.

Order Status Updates

When Forter receives updates after the checkout decision is made, we use the orderID provided in the Order API as the identifier to connect to the original order and ensure orders are tracked seamlessly.

You can send order status updates for up to 18 months after checkout.

Payment authorization update

For pre-authorization flows, you can streamline the process of sending payment authorization updates by creating a webhook notification from your payment processors that they will send directly to Forter.

Forter can accept payment webhook notifications from Adyen, Primer, and Worldpay.

For all other payment processors, send an update via the Order status API with mapped values from the payment authentication information you received.

Data Point	Parameter in payment.[paymentMethod] object	Notes
Authorization code	verificationResults.authorizationCode or processorResponseCode or processorResponseText
AVS result	verificationResults.avsFullResult or avsStreetResult and avsZipResult	In countries where address is verified
CVV result	verificationResults.cvvResult
3DS status	verificationResults.threeDsStatus or eciValue or cavvValue
Payment processor	paymentProcessorData.processorName
Processor transaction ID	paymentProcessorData.processorTransactionId	For proper mapping, include this value as chargeId when reporting disputes

Also include an updated status for the order with this request. When the authorization succeeds, updatedStatus: “PROCESSING”. When the authorization fails, updatedStatus: “CANCELED_BY_MERCHANT”.

Order Status API request example for payment authorization

{
  "orderId": "1415287568000",
  "eventTime": 1661893713000,
  "updatedStatus": "PROCESSING",
  "updatedMerchantStatus": "card auth tokenised",
  "verificationResults": {
    "cvvResult": "M",
    "avsStreetResult": "M",
    "processorResponseCode": "1000",
    "processorResponseText": "Approved",
    "cavvResult": "VYboNwcsB3F9gTIsbaUjvEuLW0o=",
    "eciValue": "05",
    "threeDsStatus": "Cardholder authenticated",
    "liabilityShift": true,
    "threeDsVersion": "2.1.0",
    "authorizationProcessedWith3DS": true
  }
}

Order fulfillment update

When there is an update to the order status - whether sent, completed, returned, canceled, etc. - call the Order Status API using Forter's enumerated status types. This will not return a decision, but provides valuable information to inform our decision models.

Data Point	Parameter	Notes
New order status	updatedStatus	See enum definitions below
Status change datetime	eventTime

The definitions of an order's status are:

PROCESSING: When the order is placed successfully, but you have not yet sent any items to the customer.
SENT: When you have sent part of the order to the recipient.
COMPLETED: When you have sent the entire order to the recipient.
CANCELED_BY_MERCHANT or CANCELED_BY_CUSTOMER: When an order is canceled in entirety.
If only some items in the order are canceled prior to fulfillment, send the updatedTotalAmount and adjusted cartItems, but retain the PROCESSING or SENT status for the order.

Order Status API request example for fulfillment update

{
  "additionalInformation": {},
  "deliveryStatusInfo": {
    "additionalShippingInfo": "PO Box 3297",
    "customerOpenedEmail": false,
    "proofOfShippingURL": true,
    "signedProofOfShipping": true
  },
  "eventId": "r48987fgdse0r",
  "eventTime": 1415287568000,
  "orderId": "2356fdse0rr489",
  "statusChangeReason": "Fraud_Team_Manual_Decline",
  "updatedMerchantStatus": "Shipped",
  "updatedStatus": "SENT",
  "updatedTotalAmount": {
    "amountLocalCurrency": 105.55,
    "amountUSD": 99.95,
    "currency": "CAD"
  }
}

Compensation update

When a customer is granted compensation or an appeasement (e.g. refund, replacement, return, store credit, etc), include the compensationStatus object in the Order Status API along with the eventTime and updatedStatus of the order. This will not return a decision, but provides valuable information to inform our decision models.

If the compensation request applies to only some items in the order, include the statusData object at the item-level within the itemStatus array.

Data Point	Parameter in compensationStatus object	Notes
Items	itemStatus.basicItemData	Include name, price, quantity and type
Type	statusData.compensationTypeGranted
Reason provided	statusData.reasonCategory
Return method	statusData.returnMethodGranted
Request status	statusData.updatedStatus
Amount	totalGrantedAmount

Order API Response

The response details whether or not the Order API update was completed successfully. It will NOT return a new decision.

Example:

{
  "message": "Transaction #:id status received",
  "status": "success"
}

Mapping payment processor fields (Important for Chargeback Recovery integration)

When a chargeback arrives from your payment processor, Forter needs to link it back to the original order. Two fields make this possible:

paymentProcessorData.processorTransactionId — The payment processor's unique identifier for the authorized payment. This is the primary field Forter uses to match a dispute to the original order.
additionalIdentifiers.additionalOrderId — Your internal order reference as it appears in the processor's system (e.g., the merchant reference you passed during checkout). This serves as a secondary identifier that Forter can use to match disputes when available.

Below is how to extract these values from each PSP's authorization response.