Formatting an order where multiple payment methods are used
Overview
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.
Formatting Split Payments
In Forter's API schema, payment is formatted as an array that can accept multiple payment objects.
In cases of multiple payments, you should push each payment method into the payment array. The nesting within the payment array should look like the following for split payment orders:
"payment": [
{}, // first payment method
{} // second payment method
]
Where each object represents a different payment method.
The amount object within each payment method object (i.e. payment[0].creditCard.amount, payment[1].creditCard.amount) 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.
Note that the
totalAmountobject value will be how Forter's system determines the order Amount and bills accordingly.
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 of split payment 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": "[email protected]"
},
"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 Loyalty and Credit Card
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. The Loyalty points should still be nested as its own object within the payments array but only
Example of split payment with Credit Card and LoyaltyPoints
{
"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"
}
Display in Forter portal
When split payment methods are correctly formatted in the API request body, both payment types will show in the portal's Detailed Transaction view. Below is an example of how the split payments for a split credit Card/gift card order will appear in the detailed transaction grid.
