Checkout Integration

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 https //docs forter com/reference/order v3 reference documentation, with the most critical data for the decision model outlined on the docid\ ao5sxf8kqsfhdcpvedt5r 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 { "action" "approve", "message" "", "reasoncode" "", "status" "success", "transaction" "123456" } v3 response format {"forterdecision" "approve", "recommendation" "","verificationmethod" {}} in order to test your handling of an "approve" response, use the the email address 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 { "action" "decline", "message" "", "reasoncode" "", "status" "success", "transaction" "123456" } v3 response format { "forterdecision" "decline", "recommendation" "", "verificationmethod" {}} in order to test your handling of an "decline" response, use the the email address 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 { "action" "not reviewed", "message" "", "reasoncode" "", "status" "success", "transaction" "123456" } v3 response format { "forterdecision" "not reviewed", "recommendation" "", "verificationmethod" {}} in order to test your handling of an "not reviewed" response, use the the email address mailto\ notreviewed\@forter com in the accountowner object within the api request examples 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 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 order api request for mobile app order { "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" } } } 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 "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 example with same billing details "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 example of credit card and loyalty points { "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" }