Preparing a PaymentTransactionServices Payment for the Chase Payment Module

To execute payment transactions, we must first create a Payment in PaymentTransactionServices. This process differs between different payment instrument types.

Note	See how to add a payment via the Commerce SDK.

Chase Hosted Payment Solution (HPS)

When using Chase Hosted Payment Solution, the overall steps look like so:

The frontend application makes a request to the POST /chase-payment/hps-order-abstraction/uid-init endpoint to obtain an HPS UID
The frontend application then uses that HPS UID to load a Chase Hosted Payment Form or Chase Hosted Payment Page (this configuration is further detailed in Chase’s Developer Center documentation).
After submission is complete and the HPF/HPP reports success, the frontend submits a request to create a Payment in PaymentTransactionServices:
Payment creation example for HPS-created profile
```
{
    "name": "My Payment",
    "type": "CREDIT_CARD",
    "gatewayType": "CHASE_ORBITAL",
    "amount": {
        "amount": 10,
        "currency": "USD"
    },
    "isSingleUsePaymentMethod": true,
    "shouldArchiveExistingPayments": true, (1)
    "paymentMethodProperties": {
        "paymentInstrumentType": "CREATED_HPS_PROFILE", (2)
        "hpsUid": "123ABCUIDXYZ" (3)
    },
    "ownerType": "BLC_CART", (4)
    "ownerId": "123OWNERID" (5)
}
```
1. There may be a scenario where the customer has already executed an HPS submission, and you’ve already created a BLC Payment for it, but then they decide to change to a different credit card. In such a case, they’ll need to go through the entire HPS flow again with a new UID, enter all the card information, submit, etc. Each HPS submission results in a net new Orbital profile being created, and thus, semantically, it is a new payment with new attributes. As a result, instead of editing the existing BLC Payment with the updated UID, simply create a new BLC Payment for the new submission, and archive the old one. This shouldArchiveExistingPayments flag makes it easy to archive the existing payment while creating the new one.
Note
This is different from the typical approach used with other gateways or payment methods, where the preferred pattern is to update the existing BLC Payment instead.
1. Required property that can be used by the system to drive further validation and internal processes
2. In this field, the frontend will supply the same UID that it used to load the HPF/HPP the customer submitted their cardholder information in. The system will internally leverage Chase’s UID Query endpoint to obtain the results of the customer submission and do further processing.
3. Describes the owner of the payment. This is expected to match the owner type provided in the /uid-init request.
4. The ID of the owner of the payment. This is expected to match the owner ID provided in the /uid-init request.

Payment Creation Validation and Processing

While processing the Payment creation request, the system will engage a few phases in ChaseOrbitalGatewayPaymentModificationService.

Validation

The provided UID is only considered valid if all the following are true:

Chase’s UID query endpoint is able to find and return details about the UID. It will return 404 if the customer has not submitted the form/page for the UID, or if the profile contained within it has already been used in an Orbital transaction request.
The UID query results show that the submitted cardholder information was valid (address verification AVS checks passed, CVV checks passed, profile was created successfully, etc)
The UID query results show that the requested payment owner type and owner ID are consistent with the values originally sent in the /uid-init request. This ensures, for example, that a profile created for cartX cannot be used to create a payment for cartY.
The UID query results show that the BLC application and tenant IDs the current Payment creation is being requested in are consistent with the values originally sent in the /uid-init request. This ensures an HPS profile created for a different application/tenant cannot be used to create a BLC payment in a different application/tenant.

Transformation

Chase’s Order Abstraction flow is intentionally designed to limit the amount of detail available to the frontend about the results of a HPF/HPP submission. As a result, only the backend (using authenticated requests with API keys) is able to retrieve key information such as the created profile reference number, card brand, masked card number, etc.

Thus, once the received UID query response has been validated, the backend will itself map over those additional details onto the Payment before it is created.

Payment.paymentMethodProperties
- In this field, the system will intentionally clear and replace whatever the API caller has provided in their request with only the entries expected by the system. This ensures the caller cannot themselves provide arbitrary properties that we only expect the system to calculate/set.
- In this map, the system will populate the payment instrument type, the UID, the created Orbital profile customer reference number, the card brand, and whether the card was detected to be a commercial card.
- If the card is a commercial card, the system will auto-generate and populate a PO number that can be supplied as the Level 2 order ID in later transactions.
Payment.displayAttributes
- The system will populate the credit card type (aka card brand), the masked credit card number, the card expiration month, and the card expiration year
Payment.billingAddress
- The system will populate the billing address to match the address submitted by the customer

Apple Pay

For details on what properties are required for Apple Pay during Payment creation, see Apple Pay Token creation.