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.
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 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 |
{
"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 |
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.
{
"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 |
{
"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 |
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.
{
“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” }
}]
}
}]
}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.:::