Add payment details to customer billing profile

You must add payment details to customer billing profiles so that this information is passed downstream to fulfillment and provisioning systems.

In Telco transactions there is critical contact information that must be passed downstream to fulfillment and provisioning systems. Based on the Customer Account Model, this information is the following:

• Customer Account
• Service Account
• Billing Account
• Billing Profile

This topic covers the processes involved in the updating of payment details in a Billing Profile.

Understand how billing profiles are handled

A Contact (that is a user, shopper, or customer) may have the following information in Oracle Commerce transactions:

• A Customer Account (Account of type “Customer”).
• A link to other Customer Accounts. This would occur where the merchant supports account models such as “Family Account,” “Household,” or “Family and Friends.”
• A link to one or more Service Accounts (Accounts of type “Service”).
• A link to one or more Billing Accounts (Accounts of type “Billing”).
• A link to one or more Billing Profiles.

In this type of transaction model, Commerce has the important ability to create or update a billing profile with payment details. This is important because the payment information for the billing profile needs to be captured and passed on to the primary CRM (Customer Relationship Management) system in a PCI compliant manner. For the Oracle Telco CX Solution, the primary CRM system is Oracle Engagement Cloud (OEC).

Note: In an integration like this, transaction payment details that are stored in the CRM system are used for recurring payments. This info is pulled by the billing system from CRM. To compare this with Commerce, Commerce handles one time/upfront payments by interacting with payment gateways.

At this point in time, Commerce is PCI compliant whereas Oracle Integration Cloud and Oracle Engagement Cloud are not. Commerce supports the storing of credit cards against a shopper profile. The card details are captured, however, in the store as part of the checkout flow and subsequently a tokenized version of the card is obtained from an integrated payment system as part of the payment authorization process. This token, along with a masked version of card number and the expiration date are then stored against the shopper’s profile so that the shopper can easily use the same card for future purchases.

A feature is now supported that offers a generic horizontal benefit to Commerce and contributes to the Telco specific vertical requirement. This feature uses a store API endpoint that allows a shopper to store credit cards as part of their profile without actually purchasing an order. This endpoint can then be used to enable Commerce to pass credit card information to Oracle Engagement Cloud as part of the shopper billing profile when creating or for updating accounts in OEC.

Understand the Update Profile endpoint and Generic Payment webhook

As mentioned, Commerce provides an Admin and Agent Update Profile store API endpoint that lets you add and store customer credit cards as part of a shopper Billing Profile without actually purchasing an order.

The name of the endpoint is addCreditCard. The Admin URI for the endpoint is POST /ccstoreui/v1/current/creditCards/. The Agent URI for the endpoint is POST /ccagentui/v1/profiles/{id}/creditCards.

The endpoint can be used to invoke Add Card requests multiple times to let you add more than one card to a shopper Profile. Each new card is then stored against the profile. The inputs of this endpoint are:

• cardType
• nameOnCard
• cardNumber
• expiryMonth
• expiryYear

Both versions of this endpoint trigger the Generic Payment webhook for a Tokenize operation on the payment system. The payment system is expected to return a tokenized value of the card which is then saved against the billing profile. The endpoint then returns back a stored card ID.

The Admin Get Profile endpoint can then be used to get the token value of the card using the stored card ID. See Configure Payment Processing and Create a Generic Payment Gateway Integration for more complete information on this subject.

Add and update a Billing Profile to include a card token

There are two processes/flows that Commerce uses to capture the billing profile information that can be passed on to the primary CRM system. These are the following:

• Commerce creates an account(s) for a contact which includes creating one or more billing profiles.
• Commerce updates an existing billing profile.

To assist in these processes, Commerce provides a Customer Account Model Server Side Extension (SSE). The sections that follow provide the details on the various processes and flows that this SSE supports

Understand the OCC to OEC Account Create flow

The basic information on this flow is the following:

• SSE Name: Customer Account Model
• Endpoint Name: Create Accounts
• Flow Name: OCC to OEC Account Create flow

In this process, the SSE first identifies the payment type. If the payment type is Card, a check is done to see if the token for the card has been passed in (i.e., an existing card stored on the shopper’s Commerce profile). If the token has been passed in, then a check is done to see that the basic card information has also been passed in the form of maskedCardNumber and expiryMonth. If the token has not been passed in (i.e., a new card is being introduced), then a check is made to look for the following “full card” information being passed in:

• Card Type
• Name on Card
• Card Number
• CVN (card verification number)
• Expiry Month
• Expiry Year

There is also a step in the SSE execution whereby an API call can be made to the storefront Profiles/Update Profile endpoint to retrieve a tokenized version of the card. The billing profile information passed to the OCC to OEC Account Create flow includes:

• Payment Method=Card
• Masked Card Number
• Card Expiry Date
• Tokenized representation of the card

The next section provides details on an update process/flow that the SSE handles.

Understand the OCC to OEC Account Update flow

The basic information on this flow is the following:

• SSE: Customer Account Model
• Endpoint Name: Update Accounts
• Flow Name: OCC to OEC Account Update flow

In this process, the SSE first identifies the payment type. If the payment type is Card, a check is made to see if the token for the card has been passed in (i.e., there is an existing card stored on the shopper’s Commerce profile). If the token has been passed in, then a check is made that the basic card information has also been passed in the form of maskedCardNumber and expiryMonth.

If the token has not been passed in (i.e., a new card has been introduced), then a check is made to look for the following “full card” information:

• Card Type
• Name on Card
• Card Number
• CVN (card verification number)
• Expiry Month
• Expiry Year

The billing profile information passed to the OCC to OEC Account Update flow includes:

• Payment Method=Card
• Masked Card Number
• Card Expiry Date
• Tokenized representation of the card

Note: Keep in mind the following additional details regarding the OCC OEC Comms: Account Update flow:

• A check is made to verify that the payment type is credit card/debit card. If it is credit card/debit card, then a check is made to verify whether creditCardNumber is masked or non-masked.
• If creditCardNumber is masked, an additional check is made to verify that the masked creditCardNumber and creditCardId values provided are valid. If both are valid, then only creditCardNickname is allowed to update. All other fields/properties are not allowed to update.
• If creditCardNumber is unmasked, then the card is considered a new card. Tokenization occurs with the provided card details is similar to the Create Account flow. The process ends with the new card and token details stored in CDM.

Understand fields and properties supported by the billing profile

For the credit card or debit card payment type, the following fields/properties are supported:

• paymentMethod: “debitcard”/”creditcard”
• creditCardNumber (mandatory field)
• creditCardExpiryMonth (mandatory field)
• creditCardExpiryYear (mandatory field)
• creditCardContactName (mandatory field)
• creditCardType (mandatory field)
• creditCardSecurityCode
• creditCardNickname
• creditCardIin

For the bank transfer payment type, the following fields/properties are supported:

• paymentMethod: “bankTransfer”
• bankAccountNumber (This is the only mandatory field for bankTransfer payment type.)
• bankRoutingNumber
• bankAccountType
• bankAccountName
• bankSortCode
• bankName
• bankAddress
• bankIban
• bankSwiftCode

Understand the process changes as seen in the store interface

With a standard checkout flow where the shopper does not yet have a customer account model and is purchasing a service, the store interface captures the payment card details. This includes the following:

• The shopper is prompted to identify the payment type. If the payment type is “Credit/DebitCard,” the shopper is prompted to select either an existing card or enter new card details.
• If it is a new card the user interface captures the following required card information:
  • Card Type
  • Name on Card
  • Card Number
  • CVN (card verification number)
  • Expiry Month
  • Expiry Year

For a billing profile update checkout flow where the shopper, who does not have a customer account model and is purchasing a service, the store interface captures the payment card details. These details include the following:

• The shopper is prompted to identify payment type.
• If the payment type is “Credit/DebitCard,” the user interface captures the following the required card information:
  • Card Type
  • Name on Card
  • Card Number
  • CVN (card verification number)
  • Expiry Month
  • Expiry Year