Docs

Log in to read the version of docs relevant to your site, or use the dropdown versions

Payment Initiator Parameter

The Payment Initiator API parameter, denoted as payment_initiator, serves a critical role in distinguishing the originator of a transaction in Chargebee. This parameter allows you to differentiate between transactions initiated by merchants and those initiated by customers. The payment_initiator parameter can have one of two values: "merchant" or "customer".

In cases where customer participation is required, such as in 3D Secure flows, Chargebee can easily differentiate between Customer-Initiated Transactions (CIT) and Merchant-Initiated Transactions (MIT). However, it is more complex for Chargebee in custom checkout flows, especially in non-3DS scenarios, to classify transactions as either CIT or MIT. This complexity stems from the diverse front-end experiences controlled by individual merchants, along with limited insight into the unique operational flows adopted by various businesses. In such scenarios, the payment initiator parameter becomes highly valuable in informing Chargebee how to handle the transaction.

Use cases

  • Businesses can build a custom checkout process, allowing customers to input payment methods and purchase subscriptions through their own checkout process. In this situation, businesses must explicitly inform Chargebee that it is a customer-present operation. This way, Chargebee can transmit the necessary parameters to the gateway to classify these transactions as customer-initiated and guide them through the appropriate flow.
  • Businesses may have developed an interface for their internal customer-facing teams, empowering them to fulfill customer requests by creating, upgrading, or downgrading a subscription. As the merchant initiates this action on behalf of the customer, businesses can inform Chargebee about the initiator during the subscription creation or update process. By doing so, Chargebee can transmit the relevant parameter to the gateway, indicating that it should be categorized as a merchant-initiated flow and apply the appropriate exemptions.
  • Businesses can levy ad hoc fees apart from recurring payments, such as consulting fees, setup fees, and additional add-ons, which they may need to raise separately according to their internal processes. In such cases, businesses can use the payment initiator parameter in the Chargebee API to designate it as a merchant-initiated transaction.

Note:

merchant is considered the default value if a specific value is not passed to the payment_initiator parameter, except for payment_intent flows.

Using the Payment Initiator Parameter

When initiating an operation via Chargebee APIs, such as creating a subscription or creating an invoice, merchants can specify the payment initiator parameter value in their API call. Chargebee will store the parameter's value in the database and return it along with the transaction response, allowing merchants to distinguish between customer-initiated and merchant-initiated transactions.

  • Ecentric via payFURL
  • Windcave via payFURL
  • Metrics Global via payFURL

If you want this to be prioritized for a payment gateway that is not part of the above list, submit your request through your Customer Success Manager / Chargebee Support.

Note:

The Payment Initiator parameter will be used to set the initiator type only for the immediate payment transaction resulting from an operation (say creating a subscription). All subsequent renewal payments will be automatically classified as Merchant-Initiated Transactions by Chargebee.

Special Workflow for BlueSnap

BlueSnap provides the flexibility to leverage Kount for fraud verification. By default, BlueSnap conducts fraud checks for both CIT and MIT payments. However, some businesses may seek to optimize costs related to fraud verification with Kount by excluding MIT payments from the fraud check process.

To achieve this, BlueSnap offers the option to configure a specific parameter known as recurringTransaction with the value "Recurring" in the MIT flow for card payments. Setting this parameter allows businesses to selectively skip sending MIT payments for fraud checks.

In scenarios involving MIT Non-3DS, the payment initiator parameter plays a crucial role in determining and configuring this additional parameter within BlueSnap. This customization is an additional configuration step that must be independently enabled in your Chargebee account and your BlueSnap account.

If you wish to implement this configuration for your BlueSnap account within Chargebee, please contact Chargebee support for assistance in enabling this feature. Check with your Bluesnap Account Manager if it's already enabled on your Bluesnap account before enabling this in Chargebee.

API Endpoints that Support Payment Initiator Parameter

Following are the API Endpoints from the Product Catalogue 1.0 and 2.0 that support the Payment Initiator parameter. You can navigate to the relevant API document using the hyperlink for each endpoint:

Product Catalogue 1.0

Product Catalogue 2.0

Was this article helpful?