--- title: Post-purchase Updates slug: post-purchase-updates docTags: createdAt: 2026-06-01T13:20:13.286Z --- 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. :::hint{type="success"} 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](https://docs.forter.com/adyen-dispute-webhook), [Primer](docId\:ateodxYQlQVxAL0lkoByD), and [Worldpay](docId\:gklBqq96s6RSW1LTtAf8k). 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** ```json { "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** ```json { "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:** ```text { "message": "Transaction #:id status recieved", "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. ### Adyen | Adyen Auth Response Field | Forter Field | | ------------------------- | --------------------------------------------- | | `pspReference` | `paymentProcessorData.processorTransactionId` | | `merchantReference` | `additionalIdentifiers.additionalOrderId` | ```json { "pspReference": "TG3G6Z4MCJ4NMXZ3", // -> processorTransactionId "merchantReference": "ORDER_101", // -> orderId "resultCode": "Authorised", "amount": { "currency": "USD", "value": 1000 } } ``` ### Stripe | Stripe Auth Response Field | Forter Field | | ------------------------------------ | --------------------------------------------- | | `id` (the `pi_...` PaymentIntent ID) | `paymentProcessorData.processorTransactionId` | | `metadata.order_id` | `additionalIdentifiers.additionalOrderId` | :::hint{type="info"} Prefer the PaymentIntent ID (`pi_...`) over the Charge ID (`ch_...`). The PaymentIntent ID is generated earlier in the flow and remains constant even if the specific charge attempt changes. ::: ```json { "id": "pi_3M7n...", // -> processorTransactionId (recommended) "object": "payment_intent", "charges": { "data": [{ "id": "ch_3M7n...", // alternative, but less stable "status": "succeeded" }] }, "metadata": { "order_id": "ORD_101" } // -> orderId } ``` ### Braintree | Braintree Auth Response Field | Forter Field | | ----------------------------- | --------------------------------------------- | | `transaction.id` | `paymentProcessorData.processorTransactionId` | | `transaction.orderId` | `additionalIdentifiers.additionalOrderId` | ```json { "transaction": { "id": "52ABC7", // -> processorTransactionId "status": "authorized", "orderId": "ORD_101", // -> orderId "amount": "10.00" } } ``` ### PayPal | PayPal Capture Response Field | Forter Field | | ------------------------------------------- | --------------------------------------------- | | `purchase_units[0].payments.captures[0].id` | `paymentProcessorData.processorTransactionId` | | `purchase_units[0].custom_id` | `additionalIdentifiers.additionalOrderId` | :::hint{type="info"} PayPal has a two-level structure (Order → Capture). The `processorTransactionId` should map to the **capture ID**, not the PayPal order ID, since the capture ID is what appears in dispute webhooks as `seller_transaction_id`. ::: ```json { “id”: “5O190127TN364715T”, // PayPal Order ID (not used for linking) “status”: “COMPLETED”, “purchase_units”: [{ “custom_id”: “ORD_101”, // -> additionalOrderId “payments”: { “captures”: [{ “id”: “3C679366HH908993F”, // -> processorTransactionId “status”: “COMPLETED”, “amount”: { “currency_code”: “USD”, “value”: “10.00” } }] } }] } ``` :::hint{type="info"} If neither `processorTransactionId` nor `additionalIdentifiers.additionalOrderId` is provided in your Order API request, Forter may not be able to match incoming chargebacks to the original order. This can result in missed disputes This can result in Forter missing dispute ingestion, which will impact your chargeback recovery and/or coverage policy.\::: :::