Generate a Session

tip

For security reasons, session has to be generated on the backend and provided to the web app

Creating a session

• To integrate the CCG UI widget/API, the first step is to generate a session for the widget by making a call to the /POST sessions endpoint. This endpoint requires the following information:

  • customer: This information is necessary to identify the user and provide the relevant experience (wallet or guest).
    • Refer Guest vs Wallet Experience
  • payment: This includes all relevant information related to the payment, such as the amount, merchantTransactionId etc.
  • paymentMethod: This includes selected payment method id by merchant that will be used to get respective payment method selected when landing on payment method selector page.
  • config: This defines the configuration for the widget, eg: capabilties. This information is necessary to customize the widget to fit the merchant's needs and preferences.
    • Refer Widget Capabilities for full list.
    • The response returned by the session API may vary depending on how the widget is configured.

/POST session (request)

curl --location --request POST '<HCP_DOMAIN>/api/financial/commerce/nonprodcheckout/v1/sessions' \
--header 'X-Merchant-Id: <x-merchant-id>' \
--header 'X-Upstream-Env: <x-upstream-env>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authorization-token>' \
--data-raw '{
    "customer": {
        "firstName": "foo",
        "lastName": "bar",
        "email": "foo.bar@email.com",
        "ssnLastFour": "1234",
        "dateOfBirth": "1970-31-12",
        "phoneNumber": {
            "number": "9876543210",
            "countryCode": "1"
        },
        "zip5": "54321",
        "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
        "metadata": {}
    },
    "payment": {
        "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
        "amount": 1200,
        "authorizeCard": false,
    },
    "config": {
        "modes": [
            "PAYMENT_METHOD_ENTRY"
        ],
        "paymentMethodChannel": {
            "card": [
                "WEBFORM",
                "TEXT",
                "EMAIL",
                "GOOGLE_PAY",
                "APPLE_PAY"
            ],
            "bankAccount": [
                "WEBFORM"
            ]
        },
        "privacyPolicyUrl": "https://merchant.com/privacypolicy"
    }
}'

/POST session (response)

{
  "url": "/sessions/<CHECKOUT_SESSION_ID>",
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "hostedUrl": "<CCG_DOMAIN>/app?checkoutSessionId=<CHECKOUT_SESSION_ID>&appEnv=<CCG_APP_ENV>"
  }
}

Widget Configuration

• Widget configuration enables customizing the capabilities of the widget; Set config.modes property to the desired value when creating the session.
• The config.modes is array type but is designed to accommodate a single value: PAYMENT_WITH_WALLET, PAYMENT_METHOD_ENTRY, PAYMENT, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAY

sample /POST session (req/res)

{
  "customer": {},
  "payment": {},
  "config": {
    "modes": ["<mode>"],
    "paymentMethodChannel": ["<paymentMethodChannel>"]
  }
}

{
  "url": "/sessions/<CHECKOUT_SESSION_ID>",
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "hostedUrl": "<CCG_DOMAIN>/app?checkoutSessionId=<CHECKOUT_SESSION_ID>&appEnv=<CCG_APP_ENV>"
  }
}

Session Lifecycle

• A session is used to track the transaction status and is valid for 15 minutes once initiated.
• The lifecycle of a session typically begins with a call to the POST /session endpoint and ends when the transaction is successful, fails, or times out.

Status	Description
ACCEPTED	Accepted, but not ready for processing
CREATED	Ready for processing
COMPLETED	Transaction successful
error	Invalid request, Session creation error, Transaction failure or Time out

ACCEPTED

• This is the initial state of the session object that is returned immediately after a successful call to the POST /session endpoint. At this stage, the session has been initiated, but it is not yet ready for processing.

/POST session response(ACCEPTED)

// HTTP status code: 202
{
  "url": "/sessions/<CHECKOUT_SESSION_ID>",
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "hostedUrl": "<CCG_DOMAIN>/app?checkoutSessionId=<CHECKOUT_SESSION_ID>&appEnv=<CCG_APP_ENV>"
  }
}

Polling

• To retrieve subsequent status updates for the session, you can use the GET /session API and poll the endpoint periodically. By polling the GET /session API, you can retrieve the latest status updates for the transaction and monitor its progress in real-time.

CREATED

• In this state, the sessionId is active and can be used to perform the transaction.
• When using the API, this state signals that the API can be submitted for processing, such as making a payment.

/GET session response(CREATED)

// HTTP status code: 200
{
  "id": "<CHECKOUT_SESSION_ID>",
  "status": "CREATED" // ready for processing
}

COMPLETED

• This is the final state of the session object that is triggered when the transaction is successfully completed. The nature of the transaction completed may vary depending on the widget configuration that was supplied to create the session.
• For example, in the case of PAYMENT_METHOD_ENTRY, this state may be triggered when the user successfully adds a payment method. In the case of PAYMENT_WITH_WALLET, this state is only triggered if the user successfully completes a payment.
• In this final state, the session response may include information such as the paymentId, paymentMethodId information, which can be used to track the transaction and provide proof of payment to the customer.

/GET session response(COMPLETED)

// HTTP status code: 200
{
  "id": "<CHECKOUT_SESSION_ID>",
  "status": "COMPLETED",
  "paymentMethod": {}
}

error

• This state indicates that there were errors during the transaction, which could be due to transaction failure or timeout.
• In this state, the response object may include error codes, error messages, and other details that can be used to identify and resolve the issues that caused the transaction to fail.

/GET session response (error)

// HTTP status code: 401, 403
{
  "message": ""
}

```json
// HTTP status code: 500
{
  "title": "",
  "detail": "",
  "status": ""
}

Request/Resonse based on config.modes

PAYMENT_WITH_WALLET

/POST session (request)

{
  "customer": {},
  "payment": {},
  "config": {
    "modes": ["PAYMENT_WITH_WALLET"]
  }
}

/GET session/:id (response)

{
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "status": "COMPLETED",
    "payment": {
      "id": "",
      "amount": 100,
      "description": "",
      "merchantTransactionId": "",
      "merchantId": "",
      "paymentType": "",
      "currencyCode": "",
      "status": "COMPLETED",
      "paymentMethodId": "",
      "metadata": {},
      "error": null,
      "statementDescriptorSuffix": null,
      "paymentDetails": null
    }
  }
}

PAYMENT_METHOD_ENTRY

/POST session (request)

{
  "customer": {},
  "config": {
    "modes": ["PAYMENT_METHOD_ENTRY"],
    "paymentMethodChannel": {
      "card": ["WEBFORM", "TEXT", "EMAIL"] // "TEXT", "EMAIL" applies only for agent and not user flow
    }
  }
}

/GET session/:id (response)

{
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "paymentMethodResponse": {
      "id": "",
      "paymentMethodType": "CARD",
      "status": "COMPLETED",
      "card": {
        "nameOnCard": "",
        "cardBrand": "",
        "expiryMonth": 1,
        "expiryYear": 2020,
        "last4": "",
        "zipCode": ""
      },
      "paymentMethodDetails": {
        "type": "CARD",
        "nameOnCard": "",
        "cardBrand": "",
        "expiryMonth": 1,
        "expiryYear": 2020,
        "last4": "",
        "zipCode": ""
      },
      "nickname": "",
      "default": true
    },
    "status": "COMPLETED"
  }
}

PAYMENT

/POST session (request)

{
  "customer": {}, // NA for `guest` user
  "payment": {},
  "config": {
    "modes": ["PAYMENT"]
  }
}

/GET session/:id (response)

{
  "data": {
    "sessionId": "<CHECKOUT_SESSION_ID>",
    "status": "COMPLETED",
    "payment": {
      "id": "",
      "amount": 100,
      "description": "",
      "merchantTransactionId": "",
      "merchantId": "",
      "paymentType": "",
      "currencyCode": "",
      "status": "COMPLETED",
      "paymentMethodId": null,
      "metadata": {},
      "error": null,
      "statementDescriptorSuffix": null
    }
  }
}

PAYMENT_METHOD_SELECT

/POST session (request)

{
  "customer": {},
  "paymentMethod": {
    "id": ""
  },
  "config": {
    "modes": ["PAYMENT_METHOD_SELECT"]
  }
}

/GET session/:id (response)

{
 {
    "data": {
        "id": "",
        "checkoutRequest": {
            "paymentType": null,
            "authorizeCard": null,
            "merchantTransactionId": null,
            "amount": null,
            "statementDescriptorSuffix": null,
            "paymentDescription": null,
            "phoneNumber": null,
            "email": "",
            "firstName": "",
            "config": {
                "paymentMethodChannel": {
                    "cardChannels": [
                        {
                            "type": "WEBFORM",
                            "order": 0,
                            "enabled": true
                        }
                    ],
                    "card": [
                        "WEBFORM"
                    ]
                },
                "modes": [
                    "PAYMENT_METHOD_SELECT"
                ],
                "paymentMethod": [
                    {
                        "type": "CARD",
                        "channels": [
                            {
                                "type": "WEBFORM",
                                "order": 0,
                                "enabled": true
                            }
                        ]
                    },
                    {
                        "type": "BANK_ACCOUNT",
                        "channels": [
                            {
                                "type": "WEBFORM",
                                "order": 0,
                                "enabled": true
                            }
                        ]
                    }
                ],
                "privacyPolicyUrl": "",
                "senderEmailAddress": "",
                "options": null
            },
            "agent": null,
            "assistedByAgent": null,
            "metadata": null,
            "paymentDetails": null,
            "paymentMethod": {
                "id": "",
                "default": false
            },
            "consent": null
        },
        "merchantId": "",
        "checkoutSessionStatus": "CREATED",
        "customerId": "",
        "vendorMerchantId": "",
        "paymentId": null,
        "paymentMethodId": null,
        "childSessionId": null,
        "childSession": null,
        "appearance": null,
        "error": null,
        "paymentMethod": null,
        "payment": null,
        "warning": null,
        "features": null,
        "expiresAtUtc": "",
        "createdAtUtc": ""
    },
    "hcpToken": ""
}
}

PAYMENT_METHOD_DISPLAY

/POST session (request)

{
  "customer": {}, // Customer identification details are required.
  "paymentMethod": {
    "id": "" // This is a required field.
  },
  "config": {
    "modes": ["PAYMENT_METHOD_DISPLAY"]
  }
}

/GET session/:id (response)

{
 {
    "data": {
        "id": "",
        "checkoutRequest": {
            "paymentType": null,
            "authorizeCard": null,
            "merchantTransactionId": null,
            "amount": null,
            "statementDescriptorSuffix": null,
            "paymentDescription": null,
            "phoneNumber": null,
            "email": "",
            "firstName": "",
            "config": {
                "paymentMethodChannel": {
                    "cardChannels": [
                        {
                            "type": "WEBFORM",
                            "order": 0,
                            "enabled": true
                        }
                    ],
                    "card": [
                        "WEBFORM"
                    ]
                },
                "modes": [
                    "PAYMENT_METHOD_DISPLAY"
                ],
                "paymentMethod": [
                    {
                        "type": "CARD",
                        "channels": [
                            {
                                "type": "WEBFORM",
                                "order": 0,
                                "enabled": true
                            }
                        ]
                    }
                ],
                "privacyPolicyUrl": "",
                "senderEmailAddress": "",
                "options": null
            },
            "agent": null,
            "assistedByAgent": null,
            "metadata": null,
            "paymentDetails": null,
            "paymentMethod": {
                "id": "",
                "default": false
            },
            "consent": null
        },
        "merchantId": "",
        "checkoutSessionStatus": "CREATED",
        "customerId": "",
        "vendorMerchantId": "",
        "paymentId": null,
        "paymentMethod": {
          "id": "<REQUESTED_PAYMENT_METHOD_ID>",
          "paymentMethodType": "CARD",
          "card": {
            "type": "CARD",
            "nameOnCard": "",
            "cardBrand": "",
            "expiryMonth": 3,
            "expiryYear": 2043,
            "last4": "",
            "zipCode": "",
            "status": "ACTIVE",
            "manufacturerCard": false
          },
          "nickname": "",
          "paymentMethodDetails": {
            "type": "CARD",
            "nameOnCard": "",
            "cardBrand": "",
            "expiryMonth": 3,
            "expiryYear": 2043,
            "last4": "",
            "zipCode": "",
            "status": "ACTIVE",
            "manufacturerCard": false
          },
          "default": true
        },
        "childSessionId": null,
        "childSession": null,
        "appearance": null,
        "error": null,
        "paymentMethod": null,
        "payment": null,
        "warning": null,
        "features": null,
        "expiresAtUtc": "",
        "createdAtUtc": ""
    },
    "hcpToken": ""
}
}

Environment values

• CHECKOUT_SESSION_ID - uuid to uniquely identify a session

Prod

• HCP_DOMAIN: https://api.uhg.com
• CCG_DOMAIN: https://wallet.healthsafepay.com
• CCG_APP_ENV: prod

Stage

• HCP_DOMAIN: https://api-stg.uhg.com
• CCG_DOMAIN: https://stg-wallet.healthsafepay.com
• CCG_APP_ENV: stage