--- title: Checkout Integration slug: checkout-integration docTags: createdAt: 2026-06-01T13:20:13.766Z --- ## Send Order API Request The Order API is used to provide Forter with all relevant data points collected at checkout that will help Forter determine whether the entity conducting the transaction/engagement is legitimate or fraudulent. For pre-authorization, the Order API should be called *prior* to the call made to your payment gateway to authorize customer funds. For post-authorization, the Order API should be called *after* an authorization response is received from your payment gateway, and must include the authorization response. The full request and response data can be found in our [Order API](https://docs.forter.com/reference/order-v3) reference documentation, with the most critical data for the decision model outlined on the [Important Data](docId:3Bakj1niJwdI2IftDXpqb) page. ## Handle Order API Response The API response will contain Forter's decision and, if you are leveraging other Forter services, applicable recommendations such as abuse policy enforcements or 3DS recommendations. For Fraud Management, the Forter decision is the important object and will be one of the following: Approve, Decline or Not Reviewed. ### "Approve" Decision Forter may return an "Approve" decision which means that Forter's evaluation is that the transaction can be approved and it is not fraudulent, so you can capture the transaction funds, send the customer confirmation and produce an invoice. Depending on which version of the Order API you are using, you will receive the decision either in the `action` or `forterDecision` parameter. **v2 Response format** ```json { "action": "approve", "message": "", "reasonCode": "", "status": "success", "transaction": "123456" } ``` **v3 Response format** ```json {"forterDecision": "APPROVE", "recommendation": "","verificationMethod": {}} ``` In order to test your handling of an "Approve" response, use the the email address [approve@forter.com](mailto\:approve@forter.com) in the `accountOwner` object within the API request. For pre-auth integrations, once you've moved forward with the payment request, you must also follow up with Forter to provide the payment authorization response from your payment gateway, either via a webhook or the Order Status API as described in the next step. This is important so that new information such as the AVS/CVV check and 3DS data are available for future decisions. ### "Decline" Decision As part of the Order API response, Forter may return an "Decline" decision which means that Forter's evaluation is that the transaction should be declined as there are indications it is fraudulent. Please cancel the transaction and communicate with the customer. Depending on which version of the Order API you are using, you will receive the decision either in the `action` or `forterDecision` parameter. **v2 Response format** ```json { "action": "decline", "message": "", "reasonCode": "", "status": "success", "transaction": "123456" } ``` **v3 Response format** ```json { "forterDecision": "DECLINE", "recommendation": "", "verificationMethod": {}} ``` In order to test your handling of an "Decline" response, use the the email address [decline@forter.com](mailto\:decline@forter.com) in the `accountOwner` object within the API request. ### "Not Reviewed" Decision Forter may return a "Not Reviewed" decision, for one of the following reasons: - Listen Mode – during the ramp up period, while Forter is ensuring data accuracy. - Integration add-ons - when new payment method that was not included in the initial integration is added.For example: if we start receiving PayPal orders after the integration of credit card orders has been completed but Paypal order data accuracy requires validation. - Missing data – no BIN code / email / phone details. - Merchant IP – cases when we receive *your* IP address instead of the customer IP address (e.g. phone orders / orders submitted through the merchant admin console). - Cases when a decision is not needed for the payment method or no payment data is available for the payment method If the decision was "Not Reviewed", Forter does not review the transaction, according to policy. Please act according to the policies in place prior to the integration with Forter. Depending on which version of the Order API you are using, you will receive the decision either in the `action` or `forterDecision` parameter. **v2 Response format** ```json { "action": "not reviewed", "message": "", "reasonCode": "", "status": "success", "transaction": "123456" } ``` **v3 Response format** ```json { "forterDecision": "NOT REVIEWED", "recommendation": "", "verificationMethod": {}} ``` In order to test your handling of an "Not Reviewed" response, use the the email address [notreviewed@forter.com](mailto\:notreviewed@forter.com) in the `accountOwner` object within the API request. *** ## Examples ::::ExpandableHeading ### Mobile App Order The request payload below outlines how an order made from a mobile application should be structured. Note that orders that originate from a native mobile app have `orderType` field should be populated with an enum of "MOBILE", "iOS", or "ANDROID" and include a `forterMobileUID` generated by the SDK, *in place of* the `forterTokenCookie`. Relevant mobile fields are also populated in the `connectionInformation` objet. :::hint{type="info"} Note that mobile web orders or mobile app orders that use a webview at checkout should be treated as web orders, rather than mobile. Populate the `orderType` as "WEB" and populate the `forterTokenCookie` field. ::: :::CodeblockTabs Order API Request for mobile app order ```json { "orderId": "B12261933767", "orderType": "IOS", "authorizationStep": "PRE_AUTHORIZATION", "timeSentToForter": 1672177899353, "checkoutTime": 1672177899151, "connectionInformation": { "customerIP": "38.23.217.48", "userAgent": "demoApparelApp/22.37.7 (prod; 2211222839; iOS 16.1.2; iPhone14,2)", "forterTokenCookie": null, "forterMobileUID": "10EG-891C-4725-BC45-45B3EDF95315", "mobileAppVersion": "22.37.7", "mobileOSType": "iOS", "mobileDeviceBrand": "Apple", "mobileDeviceModel": "iPhone14,2" }, "totalAmount": { "amountLocalCurrency": "120.73", "currency": "USD" }, "cartItems": [ { "basicItemData": { "name": "generic shoe", "quantity": 1, "type": "TANGIBLE", "price": { "amountLocalCurrency": "110.00", "currency": "USD" } } } ], "payment": [ { "billingDetails": { "personalDetails": { "firstName": "John", "lastName": "Smith", "email": "jsmith2021@icloud.com" }, "address": { "address1": "92 Montgomery ln", "city": "Nashville", "country": "US", "zip": "37081", "region": "TN" }, "phone": [ { "phone": "2126129007" } ] }, "tokenizedCard": { "lastFourDigits": "1111", "bin": "4111111", "cardBrand": "VISA", "cardType": "CREDIT", "countryOfIssuance": "US", "nameOnCard": "John Smith", "expirationMonth": "09", "expirationYear": "2025" }, "amount": { "amountLocalCurrency": "120.73", "currency": "USD" }, } ], "primaryDeliveryDetails": { "deliveryType": "PHYSICAL", "deliveryMethod": "Standard", "deliveryPrice": { "amountLocalCurrency": "0.00", "currency": "USD" }, "expectedDeliveryDate": "2023-01-12", }, "primaryRecipient": { "personalDetails": { "firstName": "John", "lastName": "Smith", "email": "jsmith2021@icloud.com" }, "address": { "address1": "92 Montgomery ln", "city": "Nashville", "country": "US", "zip": "37081", "region": "TN" }, "phone": [ { "phone": "2126129007" } ] }, "accountOwner": { "firstName": "John", "lastName": "Smith", "email": "jsmith2021@icloud.com", "accountId": "abc-86a7-83ebdd57ad5c", "created": 1652926635460 }, "customerAccountData": { "personalDetails": { "firstName": "John", "lastName": "Smith", "email": "jsmith2021@icloud.com" } } } ``` ::: :::: ::::ExpandableHeading ### Split Payment Forter defines a split payment order as an order that includes more than one payment method. For instance, if a customer pays for an order partially with gift card and partially with credit card or partially with credit card and partially with PayPal. In Forter's API schema, `payment` is formatted as an array that can accept multiple payment objects. In cases of multiple payments, you should put each payment method as an object into the array. The nesting within the `payment` array should look like this: ```json "payment": [ {}, // first payment method {} // second payment method ] ``` The `amount` object within each payment method object should reflect the amount of funds used for each payment method while the `totalAmount` object in the request body should reflect the total amount of the order. **Split payment with same billing details** If the billing details for both payment methods is constant, it only needs to be passed into *one* of the payment method objects. Below is an example of a split with two credit cards that share a billing address. :::CodeblockTabs Example with same billing details ```json "orderId":"123-abc-de45" "totalAmount": { // total amount of order "amountUSD": "135.27" }, "payment": [ // payment array { // first payment cc object "creditCard": { "nameOnCard": "Or Paul", "bin": "424242", "lastFourDigits": "1111", "countryOfIssuance": "US", "cardType": "credit", "expirationMonth": "10", "expirationYear": "2025", "verificationResults": { "authorizationCode": "A", "avsFullResult": "Y", "cvvResult": "M", "processorResponseCode": "1683V2", "processorResponseText": "Authorized" } }, "billingDetails": { "personalDetails": { "fullName": "Or Paul", "email": "or.paul@gmail.com" }, "phone": [], "address": { "zip": "90043", "address1": "123 17th St", "city": "Santa Monica", "region": "CA", "country": "US" } }, "amount": { // amount on first card "currency": "EUR", "amountLocalCurrency": "90.00", "amountUSD": "100.00" } }, { // second cc payment object "creditCard": { "nameOnCard": "Or Paul", "bin": "481234", "lastFourDigits": "7777", "countryOfIssuance": "US", "cardType": "credit", "expirationMonth": "07", "expirationYear": "2030", "verificationResults": { "authorizationCode": "authorized", "avsFullResult": "Y", "cvvResult": "20", "processorResponseCode": "6712300", "processorResponseText": "Approved" } }, "amount": { //amount on second card "amountUSD": "25.00" } } ] } ``` ::: **Split payment with credit card and loyalty points** Many merchants allow customers to pay for orders partially with credit card and partially with a gift card or loyalty points. In these cases, loyalty points data does not usually include billing details or any card holder information, but the loyalty points should still be nested as its own object within the payments array. :::CodeblockTabs Example of credit card and loyalty points ```json { "orderId": "123456", "orderType": "WEB", "timeSentToForter": 1625652707572, "checkoutTime": 1625652415000, "connectionInformation": {}, "totalAmount": { // total amount of order "amountUSD": "26.98" }, "cartItems": [], "primaryDeliveryDetails": {}, "accountOwner": {}, "payment": [ // payments array { // first payment object credit card "billingDetails": { "personalDetails": { "firstName": "David", "lastName": "Ond" }, "address": { "address1": "2168 Forter Drive", "city": "New York", "country": "US", "address2": "Unit 29", "zip": "100017", "region": "NY" }, "phone": [ { "phone": "212-999-7773" } ] }, "amount": { "amountUSD": "16.98" }, "creditCard": { "nameOnCard": "David Ond", "lastFourDigits": "0007", "bin": "444522", "cardType": "CREDIT", "expirationMonth": "06", "expirationYear": "2033", "verificationResults": { "cvvResult": "M", "avsFullResult": "Y", "authorizationCode": "Authorized", "processorResponseCode": "A681T6", "processorResponseText": "APPROVED" }, "cardBrand": "VISA", "paymentGatewayData": { "gatewayName": "CyberSource" } } }, { // second payment object (loyalty points) "loyaltyPoints": { "loyaltyPointsCount": 1698 }, "amount": { "amountUSD": "10.00" // equivalent dollar amount of points value } } ], "totalDiscount": { "couponCodeUsed": "716315970", "discountType": "Loyalty_Discount" } ``` ::: ::::