Integrate Adyen with IBM Sterling Order Management, Part 1

Introduction

This article is the first of the three-part series on integrating Adyen with IBM Sterling Order Management. The series provides information about:

1. The IBM Sterling Order Management payment adapter and its layers, as well as mapping Sterling Order Management with an adapter such as Adyen
2. Packaging and invoking the Sterling Order Management payment adapter from user exits, including one complete flow from checkout to charge
3. General errors while integrating with payment service providers (PSPs) and some standard practices

Here, the Apple Pay digital wallet is considered as a payment method. You can use the information here to understand how to integrate with Adyen by using the payment adapter framework. The payment adapter framework is designed as loosely coupled, interchangeable layers. So, the PSP-specific logic and service layer logic remains separate, which enables easy migration of one PSP to another without changing much code.

The adapter primarily consists of two layers:

• Service layer: This layer contains the logic that is related to items such as evaluating the eligibility and messaging the API output. The code within this layer is common across any PSP.
• Infrastructure layer: This layer contains the logic that is specific to a PSP. For example, request and response mapping, handling, and throwing exceptions. This layer is also responsible for throwing exceptions, but does not handle any exceptions.

Payment processing

Payment service providers manage the payment lifecycle for online businesses that need to accept online payments. These PSPs enable businesses to accept payments through e-commerce, mobile, and point-of-sale systems. Any Sterling Order Management deployment has various touchpoints from where it needs to call PSPs during authorization, charge, or refunds. Adyen is one of the most popular PSPs and this document helps you understand the payment processing by using Adyen for Sterling Order Management transactions.

Adyen with Apple Pay

Apple Pay is a mobile payment and digital wallet service from Apple Inc. It allows users to make payments in iOS apps and online using Safari. The user needs to confirm the payment securely through touch ID or face ID authentication. Adyen provides web, iOS, API, and point-of-sale integrations for Apple Pay.

Prerequisites

The following are the prerequisites for integrating IBM Sterling Order Management with Adyen:

• Test account with Adyen -- A test account is required for some tasks such as making test payments or managing API credentials. For more information about creating a test account, check out Get started with Adyen.

• IBM Sterling Order Management -- A running instance of Sterling Order Management from which charge, authorization, and refund transactions originate.

  1. Payment rule configuration -- Configure the payment rules by selecting both the checkboxes for authorization and settlement in the Sterling Business Center.

      System setup -> Payments -> Payment rules
     

     

  2. Authorization reversal strategy -- The authorized amount can sometimes exceed the order total after order modification. You can decide whether to reverse the authorization based on your business requirement. Here, the example considers the configuration to reverse the authorization when the authorization expires.

     System setup -> Payment Types -> Payment Type
     

     

  3. Apple test device -- To make Apple Pay payments, an iOS device is required, iPhone or iPad, for example. The device must be logged in with the test Apple ID credentials.

  4. Payment adapter -- This is required integrating IBM Sterling Order management with one or more PSPs. The source code can be found on GitHub.

Tokenization

Tokenization is a process of replacing sensitive payment data such as card number with non-sensitive data. Tokens are referred to as PAN and are a unique string of numbers. In addition to this, the tokens provide the following benefits:

• Increased security: Tokens cannot be used by any malicious actors to perform payment frauds.
• Enable one-click payments: Enables merchants to store card data securely, which enables fast checkouts for customers. These tokens are also well-suited for businesses with subscription-based business models.

The two widely used methods of tokenization are:

• Adyen tokenization -- Card details are stored by Adyen and they are swapped for recurringDetailReference. This enables the IBM Sterling Order Management application to use the token securely during functions such as subscriptions and reauthorization.
• Network tokenization -- Card networks such as Visa and Mastercard also provide tokenization services. Card details are swapped for a 16-digit alphanumeric code, which is referred to as PAN.

For more information about tokenization, see Tokenization on Adyen docs.

Integrations

You must use the following integrations to run complete payment flows.

Checkout integration

You must integrate the checkout process to create a shopping cart and make an online payment. Adyen provides multiple options line drop-ins, APIs, plug-ins, and pay-by links. The easiest way to check out is to create a payment link and pay by using Apple Pay.

Create order integration

After the checkout is successful, orders must be created in Sterling Order Management. While creating orders, payment information must be updated. You must map the following attributes from the create order XML. See create order integration in the above diagram.

After mapping, a sample create order XML contains the following attributes:

<Order AuthorizationExpirationDate=“” CarrierAccountNo=“” CarrierServiceCode=“” ChainType=“” ChargeActualFreightFlag=“N” CustCustPONo=“” CustomerEMailID=“” CustomerPONo=“” DeliveryCode=“” Division=“” DocumentType=“0001” DraftOrderFlag=“N” EnterpriseCode=“MYLUMA” EntryType=“” FreightTerms=“” HasDeliveryLines=“N” HasProductLines=“Y” HasServiceLines=“N” HoldFlag=“N” >
   <OrderLines>
       <OrderLine DeliveryMethod=“PICK” DepartmentCode=“” FreightTerms=“” FulfillmentType=“PICK” ItemGroupCode=“PROD” OrderedQty=“1” ShipNode=“MY-LUMA-Store002">
           <Item CostCurrency=“” ItemID=“HEADPHONE_01" UPCCode=“” UnitCost=“5" UnitOfMeasure=“EACH”/>
           <LinePriceInfo ActualPricingQty=“1.00" IsPriceLocked=“Y” OrderedPricingQty=“1" PricingUOM=“EACH” RetailPrice=“5" TaxableFlag=“N” UnitPrice=“5"/>
       </OrderLine>
       <OrderLine DeliveryMethod=“PICK” DepartmentCode=“” FreightTerms=“” FulfillmentType=“PICK” ItemGroupCode=“PROD” OrderedQty=“1" ShipNode=“MY-LUMA-Store002”>
           <Item CostCurrency=“” ItemID=“SUNGLASS_01” UPCCode=“” UnitCost=“5” UnitOfMeasure=“EACH”/>
           <LinePriceInfo ActualPricingQty=“1.00” IsPriceLocked=“Y” OrderedPricingQty=“1” PricingUOM=“EACH” RetailPrice=“5” TaxableFlag=“N” UnitPrice=“5”/>
       </OrderLine>
   </OrderLines>
   <PersonInfoShipTo AddressLine1=“200 SW 8th St” City=“Miami” Country=“US” FirstName=“John” LastName=“Doe” State=“FL” ZipCode=“33130"/>
   <PersonInfoBillTo AddressLine1=“200 SW 8th St” City=“Miami” Country=“US” FirstName=“John” LastName=“Doe” State=“FL” ZipCode=“33130”/>
   <AdditionalAddresses NumberOfAdditionalAddresses=“0"/>
   <References/>
   <PaymentMethods>
       <PaymentMethod PaymentType=“CREDIT_CARD” AuthTime=“2022-07-29T16:16:28.000Z” CreditCardType=“VISA” CreditCardNo=“5454" DisplayCreditCardNo=“5454” CreditCardExpDate=“3/2030" FirstName=“John” LastName=“Doe” UnlimitedCharges=“Y” MaxChargeLimit=“10" PaymentReference5=“PVF8266LB6KXWD82” PaymentReference6=“customer12345" PaymentReference7=“TFZH94H2Q6TG5S82”>
           <PaymentDetails RequestAmount=“10.0" ChargeType=“AUTHORIZATION” ProcessedAmount=“10.00" AuthorizationID=“PVF8266LB6KXWD82” AuthorizationExpirationDate=“2022-07-29T16:16:28.000Z” HoldAgainstBook=“Y” />
           <PersonInfoBillTo AddressLine1=“200 SW 8th St” City=“Miami” Country=“US” FirstName=“John” LastName=“Doe” State=“FL” ZipCode=“33130"/>
       </PaymentMethod>
   </PaymentMethods>
</Order>

IBM Sterling Order Management to adapter integration

• From YFSExtnPaymentCollectionOutputStruct to PaymentCollectionInput The YFSCollectionCreditCardUE user exit provides an extension point where you can plug in the logic to start Adyen by using the adapter. You must write the mapping of the inputs and outputs of this UE to adapt to the generic payment model. For details, see the table below.

• From PaymentCollectionOutput to YFSExtnPaymentCollectionOutputStruct PaymentCollectionOutput is the output object of the adapter. You must write the mapping to synchronize synchronous responses from the adapter back to YFSCollectionCreditcardUE.

Adyen to IBM Sterling Order Management integration

Adyen pushes the payment processing updates for each transaction through the webhook notification. These updates must be applied to the order by the recordExternalCharges API. See the following mapping for Adyen webhook notifications to recordExternalCharges. Webhook notifications are crucial for a successful integration with Adyen because they provide important information about authorization, authorization adjustments, cancellations, refunds, and other events. For more information about configuring webhooks, see Notification webhooks.

Summary

This article helps you understand the architecture of the IBM Sterling Order Management payment adapter and the various integrations required for a successful integration with Adyen. Parts 2 and 3 will cover packaging and invoking the Sterling Order Management payment adapter from user exits, and general errors while integrating with payment service providers (PSPs).