Alternative Payments
Alternative (Non-Credit Card) Payment Methods
Non-Credit Card orders
Non-Credit Card orders include any alternative payment methods that can be used to pay partially or fully for an order including:
- Gift Card
- Store Credit
- Loyalty Points
- ApplePay
- AmazonPay
- AfterPay
- Affirm
- ShopRunner
Below is an outline of recommended mapping for each of payment method.
If you had these alternate payments - it should be added as logic on payment level to identify each payment method. After each payment method is identified, you can reference the relevant function to generate the data needed to map to the correct payment method object.
Gift Card Orders Mapping
In order for our servers to correctly identify gift card orders, please send gift card as a payment instrument detail in the request. There should be a dedicated giftCard object payment array in the Order API . The request should look something like:
function ForterGiftCard(auth, giftCard) { // optional object for gift card purchases
this.merchantPaymentId = giftCard.paymentTransaction.transactionID;
this.value = {};
this.value.currency = auth.currency_code;
this.value.amountUSD = auth.amount.toString();
this.value.amountLocalCurrency = auth.amount.toString();
}Store Credit Mapping
Store Credit orders use an object identical to the gift card object formatting, please send store credit as a payment instrument detail in the request. There should be a dedicated giftCard object payment array in the order API documentation. The request should look something like:
function ForterStoreCredit(auth, sc) { // optional object for purchases made with store credit
this.merchantPaymentId = sc.paymentTransaction.transactionID; // customized based on gateway
this.value = {};
this.value.currency = auth.currency_code; // customized based on gateway
this.value.amountUSD = auth.amount.toString(); // customized based on gateway
this.value.amountLocalCurrency = auth.amount.toString(); // customized based on gateway
}Loyalty Points Mapping
Store Credit orders use an object identical to the gift card object formatting, please send store credit as a payment instrument detail in the request. There should be a dedicated giftCard object payment array in the order API documentation. The request should look something like:
function ForterLoyalty(auth, loyalty) { // optional object for purchases made with loyalty points
this.loyaltyPointsCount = parseInt(loyalty.loyaltyValue); // customized based on gateway
this.loyaltyPointsSource = loyalty.pointsLocation; // optional
this.merchantPaymentId = auth.loyaltyCode; // optional
}ApplePay Mapping
ApplePay orders should map to a dedicated applePay object in the request that is built from the ForterOrder.ds file. The ApplePay object should be nested within the payment array and include the available authorization response data that you receive on the paymentInstrument. See the below example for reference:
"applePay": {
"nameOnCard": "Matthew Botbyl",
"cardBrand": "Visa",
"token": "46C5176ABX",
"lastFourDigits": "7125",
"expirationMonth": "12",
"expirationYear": "2025",
"cardType": "CREDIT",
"countryOfIssuance": "US",
"cardBank": "Chase Bank",
"fingerprint": "rvH8RyvbatRRTi1w",
"verificationResults": {
"cvvResultCode": "pass",
"avsStreetResult": "M",
"authorizationCode": "38671PN7x",
"processorResponseCode": "100",
"processorResponseText": "Payment complete."
},
"paymentGatewayData": {
"gatewayName": "Stripe",
"gatewayTransactionId": "ch_Gcue5iOK5JbMtG"
}
}Order.ds ApplePay Mapping
ApplePay orders leverage a tokenized card object. Please send ApplePay orders as a payment instrument detail in the request. There should be a dedicated applePay object within the payment array in the validation API documentation. Mapping the applePay information within the request may be structured similar to the following with customized logic based on the response data that you receive from your payment gateway.
Example:
function ForterApplePay(auth, apple) {
// where var ap is the raw applepay response data from your payment gateway
// format the expiration month. from 1 to 01, etc.
if (apple.expirationMonth.toString().length == 1) {
var appleExpMonth = "0" + apple.payment.expirationMonth.toString();
} else {
var appleExpMonth = apple.payment.expirationMonth.toString(); // TO DO: adjust to data available
}
this.nameOnCard = apple.creditCardHolder; //name on card if available in auth
this.cardBrand = apple.creditCardType; // TODO: adjust to your payment gateway
this.token = apple.token;
this.lastFourDigits = apple.creditCardNumberLastDigits; //optional
this.expirationMonth = appleExpMonth; // TODO: adjust to your payment gateway
this.expirationYear = apple.payment.ExpirationYear.toString(); // TODO: adjust to your payment gateway
this.verificationResults = {};
this.verificationResults.avsFullResult = auth.avs.toString(); // optional
this.verificationResults.cvvResult = auth.cvd_code.toString(); // optional
this.verificationResults.authorizationCode = auth.authorization_num.toString();
processorResponseCode = auth.exact_resp_code.toString(); // TODO: adjust to your payment gateway
processorResponseText = auth.exact_message.toString(); // TODO: adjust to your payment gateway
this.verificationResults.processorResponseCode = processorResponseCode; // TODO: adjust to your payment gateway
this.verificationResults.processorResponseText = processorResponseText; // TODO: adjust to your payment gateway
}Digital Wallets (e.g. AmazonPay, MetaPay)
Digital Wallets (AmazonPay, MetaPay)
The Digital Wallet object includes any of the following payment methods: - AmazonPay - AliPay - FacebookPay - MetaPay - Zelle - WeChat Pay - Mercado Pago - UnionPay - Payco - Ame Digital - KakaoPay - Line Pay - NaverPay - MB Way
These orders use a digitalWallet method object. Please send any of the above payment methods in the digitalWallet object and use one of the dedicated enums listed in our Orders API Documentation.
Sample Digital Wallet mapping
function ForterDigitalWallet(auth) {
this.digitalWalletName = "AMAZONPAY"; // select "AMAZONPAY" enum
this.underlyingPaymentMethod.underlyingPaymentMethodName = "CREDITCARD"; // select from relevant enum UNKNOWN, CREDITCARD, BANKTRANSFER, CASH, BITCOIN
this.paymentSuccessStatus = "Completed"; // gateway auth response
this.digitalWalletPayerEmail = "[email protected]"; // email associated with digital wallet
this.fullDigitalWalletResponsePayload = {}; // full response payload from digital wallet gateway
}AfterPay
Afterpay Mapping
AfterPay orders can use the `installmentService` payment method object that includes fields for the customer's name, the Affirm gateway transaction identifier, the raw response payload, and any authorization response data you may receive from your gateway.
"installmentService": {
"serviceName": "Afterpay Payment",
"firstName": "Nerri",
"lastName": "Shelan",
"serviceResponseCode": "200",
"paymentId": "AFTasasdVVG",
"fullResponsePayload": {}
},Sample function
function ForterAfterPay(auth) { // optional object for purchases made with Affirm
this.serviceName = "AfterPay Payment"; // can be hardcoded
this.firstName = ""; //optional
this.lastName = ""; // optional
this.paymentId = auth.transaction.data.code; // unique identifier from AfterPay
this.serviceResponseCode = auth.processorResponse.toString();
this.fullResponsePayload = auth; // any additional raw response data as an object
}Note that by default, Forter will not decision AfterPay, Affirm and any InstallmentService payments (i.e. return a not reviewed decision). If you would like decisions on this payment method or any installmentService payment types, please contact your onboarding team to enable decisioning for this payment method.
Affirm
Affirm Mapping
Affirm orders use the installmentService payment method object that includes fields for the customer's name, the Affirm gateway transaction identifier, the raw response payload, and any authorization response data you may receive from your gateway.
function ForterAffirm(auth, order) { // optional object for purchases made with Affirm
this.serviceName = "Affirm"; // can be hardcoded for all Affirm payments
this.firstName = order.customer.profile.firstName;
this.lastName = order.customer.profile.lastName;
this.serviceResponseCode = auth.ResponseMessage;
this.paymentId = auth.gatewayTransactionID;
this.payload = {}; // any additional raw response data
}Sample Affirm Object (installmentService)
Affirm payments should map to the `installmentService` object within the `payment` array. Depending on the data you have available for each order paid with Affirm, fields such as `firstName`, `lastName` and `serviceResponseCode` can be made optional.
"installmentService": {
"serviceName": "Affirm",
"firstName": "Guy",
"lastName": "Zucker",
"serviceResponseCode": "200",
"paymentId": "YTZ8JAMENAWRRVVG",
"fullResponsePayload": {}
},In the Forter Portal, Affirm payments will show as InstallmentService in the Detailed transaction view and by default Forter will not decision these transactions (i.e. return a not reviewed decision). If you would like decisions on this payment method, please contact your onboarding team to enable this payment method.
ShopRunner
ShopRunner orders can leverage either the existing creditCard object or tokenizedCard object. Depending on the authorization data you have available, these should be mapped to either the tokenizedCard or creditCard payment instrument detail in the request. The below example request uses the tokenizedCard mapping:
function ShopRunner(auth, cc) {
// where var ap is the raw applepay response data from your payment gateway
var processorResponseCode = "",
processorResponseText = "";
// format the expiration month. from 1 to 01, etc.
if (ap.creditCardExpirationMonth.toString().length == 1) {
var creditCardExpMonth = "0" + cc.creditCardExpirationMonth.toString();
} else {
var creditCardExpMonth = cc.creditCardExpirationMonth.toString();
}
this.nameOnCard = cc.creditCardHolder;
this.cardBrand = cc.creditCardType;
this.token = cc.token;
this.lastFourDigits = cc.creditCardNumberLastDigits;
this.expirationMonth = cc.creditCardExpMonth;
this.expirationYear = cc.creditCardExpirationYear.toString();
this.verificationResults = {};
this.verificationResults.avsFullResult = auth.avs.toString(); // optional
this.verificationResults.cvvResult = auth.cvd_code.toString(); // optional
this.verificationResults.authorizationCode = auth.authorization_num.toString();
processorResponseCode = auth.exact_resp_code.toString();
processorResponseText = auth.exact_message.toString();
this.verificationResults.processorResponseCode = processorResponseCode;
this.verificationResults.processorResponseText = processorResponseText;
this.paymentGatewayData = {};
this.paymentGatewayData.gatewayName = "FIRSTDATA_CREDIT"; // adjust based on your processor
this.paymentGatewayData.gatewayTransactionId = auth.retrieval_ref_no.toString();
}