Skip to main content
Version: v2

Payment Method Selector

Overview​

Payment Method Selector widget allows users to view a list of payment methods and receive notifications about the selected payment method. Notifications are delivered via callback in an embedded environment or through polling in a hosted environment. Additionally, users can pre-select a payment method during session creation and manage their wallet directly within the widget.

Pre requisites​

  1. Merchants are required to have an account on the CCG Platform and complete the technical integration process.
  2. After completing the onboarding process, merchants will receive a valid merchantId, which must be included in the header of all requests to CCG APIs, as outlined in the next section.
  3. Merchants must also obtain a valid JWT token for authentication purposes. This token should be included in the header of all request to CCG APIs, as outlined in the next section

Supported Experiences​

Usage​

Create a Session​

  • To create a session, send a request object specifying the customer details, configuration modes, and optionally, the payment method ID to be pre-selected.

Example Request​

Headers required:​

  • Authorization: Bearer xxxxx
  • Content-Type: application/json
  • X-Upstream-Env: stage (Specify the env value, Only required for Non-Prod)
  • X-Merchant-Id: (MerchantId obtained during onboarding)
{
  "customer": {
    "enterpriseId": "enterprise id",
    "hsid": "hsid",
    "firstName": "first name",
    "lastName": "last name",
    "email": "email",
    "ssnLastFour": "1234",
    "phoneNumber": {
      "number": "1234567890",
      "countryCode": "1"
    },
    "dateOfBirth": "dob",
    "zip5": "23124",
    "metadata": {
      "patientId": "rx-patient-id"
    }
  },
  "paymentMethod": {
    "id": "payment-method-id"
  },
  "config": {
    "modes": ["PAYMENT_METHOD_SELECT"],
    "paymentMethodChannel": {
      "card": [
        "TEXT",
        "EMAIL",
        "WEBFORM",
        "TELEPHONIC_ENTRY"
      ],
      "bankAccount": [
        "TEXT",
        "EMAIL",
        "WEBFORM"
      ]
    }
  },
  "agent": {
    "firstName": "First Name",
    "lastName": "Last Name",
    "userId": "msId",
    "isAccessVerified": true
  }
}

More info Note: Use hostedURL from the session request response to launch the hosted experience.

Explanation on above Request Payload​
  1. customer: Represents the customer object.
    • A valid customer identifier (e.g., hsid, enterpriseId, or rx-patientId) is required for the Payment Method Selector widget to enable the selection of a payment method in the wallet.
  2. paymentMethod.id: Represents the payment method id that need to be pre-select in widget.
  3. config.modes: Defines the mode of the CCG widget, which is set to PAYMENT_METHOD_SELECT.
  4. config.paymentMethodChannel: Specifies the types of payment methods displayed on the customer's wallet screen when the session is created.
    • config.paymentMethodChannel.card - Specifies the channels through which card payment method details can be captured. The available options are:
      • TEXT: Captures card details via SMS.
      • EMAIL: Captures card details via email.
      • WEBFORM: Captures card details via web form.
      • TELEPHONIC_ENTRY: Captures card details via telephonic entry.
    • config.paymentMethodChannel.bankAccount - Specifies the channels through which bank account payment method details can be captured. The available options are:
      • TEXT: Captures bank account details via SMS.
      • EMAIL: Captures bank account details via email.
      • WEBFORM: Captures bank account details via web form.
    • TEXT, EMAIL, and TELEPHONIC_ENTRY channels are available exclusively for agent-assisted sessions.
    • WEBFORM channel is available for both agent-assisted and self-service sessions.
    • WEBFORM channel is set to default to self-service sessions.
    • Note: The channels specified in the request must be enabled during the onboarding process. If a channel is not enabled, it will not be available for use.
  5. agent: Applied for agent assisted sessions.
    • Agents can select the payment method in wallet after they capture payment method details from customers through various channels, including TEXT, EMAIL, and TELEPHONIC_ENTRY.
    • The agent must be part of the WS2 group (i.e., the AZU_PCI_Workstation_2 secure group) to capture card details from customers if the merchant has opted for ws2Check during onboarding as part of PCI compliance.

Things to Keep in Mind​

Embedded Environment​

  • Merchants are notified via onEvent callback when a payment method is selected.
  • Users can manage their wallet through a CTA button below the list. When clicked, the merchant is notified that there is no selection. After wallet changes, the last added or updated card is selected, and the merchant is notified via callback.

Hosted Environment​

  • Merchants must poll session details to get the selected payment method ID, which is attached once the user confirms their selection.
  • The payment method selector page includes two additional buttons: Confirm payment method and Cancel.
  • If Confirm payment method button is clicked without a selection, an error message is displayed.
  • Once a selection is made and Confirm payment method is clicked, the selected payment method is added to the session, and the session is marked complete.
FAQs:​

  1. What is the PAYMENT_METHOD_SELECT mode? Payment Method Selector widget allows users to view a list of payment methods and can receive notifications about the selected payment method. Notifications are delivered via callback in an embedded environment or through polling in a hosted environment. Additionally, users can pre-select a payment method during session creation and manage their wallet directly within the widget.

  2. What happens if there are no saved payment methods in the customer's wallet? If the customer's wallet contains no saved payment methods, the screen prompts them to manage their wallet and add a payment method.

  3. What happens if an invalid CCG customer identifier is used? If an invalid CCG customer identifier is provided, the session creation will fail and return a response stating that the customer identifier is missing.

  4. What happens if an invalid payment-method-id provided in request? If an invalid payment-method-id (i.e., valid UUID but its not linked to given customer wallet) is provided, the session creation will success and won't pre-select the payment-method in widget.

  5. What are the different integration patterns available for launching the PAYMENT_METHOD_SELECT widget? Payment Method Selector widget can be launched in various forms of CCG’s integration patterns such as hosted, inline, inline with modal, inline with drawer experiences.

  6. What happens if I add a card that is already in my wallet? If a user adds a card that is already present in the wallet, the fields "Name on Card," "Expiration Date," "Nickname," and "Zip Code" are updated in the existing card.

  7. What happens if I add a bank account that is already in my wallet? If a user adds a bank account that already exists in the wallet, the fields "Account Type," "Name on Account," and "Bank Account Nickname" are updated in the existing bank account.