Checkout Integration

send order api request this api is used to provide forter with all relevant data points that will help forter determine whether the entity conducting the transaction/engagement is legitimate or fraudulent the full request and response data can be found in our # order api reference documentation 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 orders where payment was rejected by the processor (no auth orders) should still be sent to forter in order to include these attempts in the decision model no auth orders will always receive a "not reviewed" decision from forter key data points to include orderid unique identifier for the order in your system accountowner details collected about the ordering customer such as name, email, account id, etc use this object even if the customer is checking out as a guest authorizationstep inform forter whether payment authorization has already been requested connectioninformation device and browsing data enables our system to distinguish between legitimate and suspicious signals as part of this object, you must include a fortertokencookie generated by the javascript snippet for orders initiated on the web, and a fortermobileuid generated in the fortersdk for orders initiated in a mobile application cartitems details about the goods being purchased note some item data will depend on the your vertical (e g travel items contain different data than apparel items) discounts any promotion or coupons applied to the order payment details on the payment method used as well as billing details for credit cards, include bin or token, last 4 digits, name on card, expiration month and year note that forter is pci dss level 1 certified and does not collect the full credit card, unless you are also utilizing forter's 3ds execution feature for paypal, include payer email, payer id, and payment method verificationresults for post auth integration, include payment authorization details within the payment method object for credit cards, include authorization code, processor response code, avs result code, cvv result code, and processor response text for paypal, include payment status, payer status, and paypal payment id primarydeliverydetails and primaryrecipient delivery method along with recipient name, address, email, etc depending on your precise industry and use case, we may ask for some extra data points that aren’t in this table, but they’ll all be the same kind of information you see listed here data points which have an obvious relevance and impact when it comes to making sure you can trust the right customers on your site if you're unable to provide any of these data points, especially any payment related data points, please reach out to your forter sc to consult on impact to your integration 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" }