<commit_before>When an end-user is charged against a payment method, this is encapsulated as a *payment* in Kill Bill. These details need to be recorded in Kill Bill.


=== Payment flows overview

*Payment flows* describe the flows that occur when a merchant site invokes the Kill Bill payment APIs for charging a customer. Thus,
these flows are not applicable for recurring payments initiated by Kill Bill.

Kill Bill supports two main payment flows, referred to as *Hosted Payment Pages* (or *HPP*) and as *Gateway integration*:

* A *HPP* flow is when the payment is completely outsourced, either by redirecting the user to a third-party website or by hosting a form or an iframe, that submits the information to a third-party website
* A *Gateway integration* flow is when the customer doesn't leave your website and Kill Bill processes the payment directly by calling a gateway API

For a concrete example on how the two flows can be implemented, take a look at our https://github.com/killbill/killbill-adyen-demo[Adyen demo].

In the flow diagrams below, we consider the following actors:

* *Browser*: user sitting behind a browser and initiating the payment flow
* *Merchants Site*: customer facing web site which receives the order and shields the payment system (i.e. Kill Bill)
* *Payments*: the payment system (i.e. Kill Bill and its specific payment plugins which interact with the payment providers) offering APIs for the various flows
* *Payment Provider*: also called Payment Service Provider (PSP), Payment Gateway or simply Gateway, this is the entity that will process the payment
* *Access Control Server* (optional): in the case of 3D-Secure checkout, the user is redirected to some third party entity to enter custom information that will validate whether he can pursue with the payment flow

=== Hosted Payment Page flow

During an HPP flow, the customer enters his payment method information (either on the main Merchants Site or a third-party site) and then submits a form containing that information to make the payment. The information required to present the user with a payment form (specific form fields or URL where the form is hosted) is obtained by calling the https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentGatewayApi.java[*buildFormDescriptor*] API.

The result of the API call will depend on the type of HPP integration:

* If the payment form is hosted on your own website (but the form data will be sent to a third-party website), the response will list the exact fields to set, such as required visible fields (the names will vary depending on the gateway, for instance some expect a `Sum` field instead of `amount`) and required hidden fields (e.g. `merchantId` value). For https://developer.paypal.com/docs/classic/paypal-payments-standard/ht_test-pps-buttons/[PayPal Payments Standard Buttons] for example, the API would return the values of the fields *cmd*, *hosted_button_id* and *submit*. The browser submits the payment information to the payment provider, which then redirects the customer to a landing page upon success or failure.
* If the payment form is completely hosted on a third-party website, the response will contain a URL to redirect the user to. This URL can be generic or unique (generated by the payment plugin either by submitting the order information to the gateway or by constructing the special URL via query parameters). For https://docs.adyen.com/classic-integration/hosted-payment-pages/hosted-payment-pages-api[Adyen HPPs] for example, the API would return a url like https://live.adyen.com/hpp/select.shtml. The browser is redirected to the payment provider website for the customer to complete the payment before being redirected back to a landing page upon success or failure.

Note that after calling *buildFormDescriptor*, the payment may or may not exist in Kill Bill: this will depend on the plugin. If it does however, it will be most likely in a **PENDING** state.

Here are a few common scenarii:

* the HPP provider doesn't provide an API to retrieve the state of the payment, nor sends notifications: the only way to record the payment is when the user is redirected to the Merchants Site. In that case, *buildFormDescriptor* can simply return the data to create the form and/or redirect the user without creating any payment. When the user completes the payment and is redirected back to the site, the Merchants Site will need to record the payment explicitely by calling the *createPurchase* API. Alternatively, if you want to keep track of abandoned purchases, the plugin could create a payment in a *PENDING* state during the *buildFormDescriptor* call. After the redirect, the Merchants Site will still call the *createPurchase* API to complete the payment, but will pass the paymentId returned by the previous *buildFormDescriptor* call.

.Payment created during the redirect

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/hpp_purchase_on_redirect.png[width=960,align="center"]

.Pending payment created during the *buildFormDescriptor* call, completed during the redirect

image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/hpp_purchase_on_redirect_with_pending_payment.png[width=960,align="center"]

* the HPP provider provides an API to retrieve the state of the payment but does not send notifications. In this case, the URL constructed during the *buildFormDescriptor* call is most likely unique, and contains enough information for the plugin to poll the provider for the payment status. During the  *buildFormDescriptor* call, the plugin will need to create a *PENDING* payment. Kill Bill will automatically poll the plugin calling the *getPaymentInfo* API, which should query the provider for the latest payment status. Example: Boleto with PayU Latam.

.Pending payment created during the *buildFormDescriptor* call, completed by polling *getPaymentInfo*

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/hpp_poll.png[width=960,align="center"]

* the HPP provider doesn't provide an API to retrieve the state of the payment but does send notifications. In this case, *buildFormDescriptor* can simply return the redirect URL without creating a payment, which will be created when the notification is received. Similarly to the first case above, you could create a *PENDING* payment if you want to track abandoned purchases, just make sure that the plugin has enough metadata to reconcile the notification with the payment. When the notification is received, either use the *notifyPendingTransactionOfStateChanged* Kill Bill API to transition the payment, or wait for Kill Bill to poll the plugin via  the *getPaymentInfo* API. Example: any HPP provided by Adyen.

.Payment created when receiving a notification from the provider

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/hpp_notifications.png[width=960,align="center"]

.Pending payment created during the *buildFormDescriptor* call, completed when receiving a notification from the provider

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/hpp_notifications_with_pending_payment.png[width=960,align="center"]

The conceptual flow below shows a 3D-Secure variation of the previous flows. The main difference is that prior redirecting the browser to the landing page, it is first redirected to the access control server where the user can enter custom information.

.Hosted Payment Page 3D-Secure variation

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/payments_hostedpages_3ds.png[width=960,align="center"]

=== Gateway Integration flow

For gateway integrations, the entry point for any payment is either the https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createAuthorization*] (to authorize a credit card), https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createPurchase*] (to charge a payment method, for example authorizing and capturing a credit card, to initiate an ACH transfer, to withdraw money from a Bitcoin wallet, etc.) or https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createCredit*] (to deposit money on a payment method, without any reference to a previous payment) APIs. The payment state will be in `*_INIT` state before calling the plugin.

Usually, transactions end up in a terminal state right away as most gateways provide synchronous APIs. However, depending on the payment method, the plugin can choose to set the status to *PENDING*. For example, this is the case for 3D-Secure transactions (until the payment is verified by the issuer after redirecting the user), for direct debit transfers (e.g. ACH, which take usually a couple of days to be acknowledged), or for Bitcoin transfers (until the transaction is confirmed by the blockchain). Additionally, some gateways don't always provide synchronous responses (e.g. when capturing funds using Adyen), in which case the plugin has to rely on asynchronous notifications to transition the payment into a terminal state.

Before any payment operation can occur, the user must first enter his payment information. In Kill Bill, this translates into creating a PaymentMethod. When dealing with credit card information specifically, merchants have to keep the data into a PCI compliant environment (often handled by the gateway): this process requires tokenization of the PAN, so that the payment system only handles the token, which is stored at the plugin level and passed to Kill Bill as a plugin property. Take a look at our https://github.com/killbill/killbill-stripe-demo[Stripe demo] for a concrete example.

Note that the creation of the Kill Bill payment method is not represented in the flows below: it can happen either in a prior step or during the payment using one of our combo payment call. Usually, the user is prompted with a form to enter his payment method information, and then the payment is initiated using one of the *createAuthorization* or *createPurchase* APIs. Kill Bill will connect to its payment plugin which in turn will contact the gateway to perform the required operation. Upon success/failure, the user is redirected to a landing page.

.Gateway integration (direct payment API)

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/catalog/payments_gateway.png[width=960,align="center"]

If 3D-Secure is enabled, the payment (e.g. authorization) is split into two phases:

* The merchant site starts with an authorize call; if enough information is supplied to the gateway and if the payment method is 'registered' as being 3D-Secure, the gateway will return a (gateway) specific status so that the user can be redirected to the access control server to complete the flow
* The user may then enter its specific information on the access control server, and upon success it is then redirected to the merchant site that will complete the authorize phase<commit_msg>Fix image link problems<commit_after>When an end-user is charged against a payment method, this is encapsulated as a *payment* in Kill Bill. These details need to be recorded in Kill Bill.


=== Payment flows overview

*Payment flows* describe the flows that occur when a merchant site invokes the Kill Bill payment APIs for charging a customer. Thus,
these flows are not applicable for recurring payments initiated by Kill Bill.

Kill Bill supports two main payment flows, referred to as *Hosted Payment Pages* (or *HPP*) and as *Gateway integration*:

* A *HPP* flow is when the payment is completely outsourced, either by redirecting the user to a third-party website or by hosting a form or an iframe, that submits the information to a third-party website
* A *Gateway integration* flow is when the customer doesn't leave your website and Kill Bill processes the payment directly by calling a gateway API

For a concrete example on how the two flows can be implemented, take a look at our https://github.com/killbill/killbill-adyen-demo[Adyen demo].

In the flow diagrams below, we consider the following actors:

* *Browser*: user sitting behind a browser and initiating the payment flow
* *Merchants Site*: customer facing web site which receives the order and shields the payment system (i.e. Kill Bill)
* *Payments*: the payment system (i.e. Kill Bill and its specific payment plugins which interact with the payment providers) offering APIs for the various flows
* *Payment Provider*: also called Payment Service Provider (PSP), Payment Gateway or simply Gateway, this is the entity that will process the payment
* *Access Control Server* (optional): in the case of 3D-Secure checkout, the user is redirected to some third party entity to enter custom information that will validate whether he can pursue with the payment flow

=== Hosted Payment Page flow

During an HPP flow, the customer enters his payment method information (either on the main Merchants Site or a third-party site) and then submits a form containing that information to make the payment. The information required to present the user with a payment form (specific form fields or URL where the form is hosted) is obtained by calling the https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentGatewayApi.java[*buildFormDescriptor*] API.

The result of the API call will depend on the type of HPP integration:

* If the payment form is hosted on your own website (but the form data will be sent to a third-party website), the response will list the exact fields to set, such as required visible fields (the names will vary depending on the gateway, for instance some expect a `Sum` field instead of `amount`) and required hidden fields (e.g. `merchantId` value). For https://developer.paypal.com/docs/classic/paypal-payments-standard/ht_test-pps-buttons/[PayPal Payments Standard Buttons] for example, the API would return the values of the fields *cmd*, *hosted_button_id* and *submit*. The browser submits the payment information to the payment provider, which then redirects the customer to a landing page upon success or failure.
* If the payment form is completely hosted on a third-party website, the response will contain a URL to redirect the user to. This URL can be generic or unique (generated by the payment plugin either by submitting the order information to the gateway or by constructing the special URL via query parameters). For https://docs.adyen.com/classic-integration/hosted-payment-pages/hosted-payment-pages-api[Adyen HPPs] for example, the API would return a url like https://live.adyen.com/hpp/select.shtml. The browser is redirected to the payment provider website for the customer to complete the payment before being redirected back to a landing page upon success or failure.

Note that after calling *buildFormDescriptor*, the payment may or may not exist in Kill Bill: this will depend on the plugin. If it does however, it will be most likely in a **PENDING** state.

Here are a few common scenarii:

* the HPP provider doesn't provide an API to retrieve the state of the payment, nor sends notifications: the only way to record the payment is when the user is redirected to the Merchants Site. In that case, *buildFormDescriptor* can simply return the data to create the form and/or redirect the user without creating any payment. When the user completes the payment and is redirected back to the site, the Merchants Site will need to record the payment explicitely by calling the *createPurchase* API. Alternatively, if you want to keep track of abandoned purchases, the plugin could create a payment in a *PENDING* state during the *buildFormDescriptor* call. After the redirect, the Merchants Site will still call the *createPurchase* API to complete the payment, but will pass the paymentId returned by the previous *buildFormDescriptor* call.

.Payment created during the redirect

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/hpp_purchase_on_redirect.png[width=960,align="center"]

.Pending payment created during the *buildFormDescriptor* call, completed during the redirect

image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/hpp_purchase_on_redirect_with_pending_payment.png[width=960,align="center"]

* the HPP provider provides an API to retrieve the state of the payment but does not send notifications. In this case, the URL constructed during the *buildFormDescriptor* call is most likely unique, and contains enough information for the plugin to poll the provider for the payment status. During the  *buildFormDescriptor* call, the plugin will need to create a *PENDING* payment. Kill Bill will automatically poll the plugin calling the *getPaymentInfo* API, which should query the provider for the latest payment status. Example: Boleto with PayU Latam.

.Pending payment created during the *buildFormDescriptor* call, completed by polling *getPaymentInfo*

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/hpp_poll.png[width=960,align="center"]

* the HPP provider doesn't provide an API to retrieve the state of the payment but does send notifications. In this case, *buildFormDescriptor* can simply return the redirect URL without creating a payment, which will be created when the notification is received. Similarly to the first case above, you could create a *PENDING* payment if you want to track abandoned purchases, just make sure that the plugin has enough metadata to reconcile the notification with the payment. When the notification is received, either use the *notifyPendingTransactionOfStateChanged* Kill Bill API to transition the payment, or wait for Kill Bill to poll the plugin via  the *getPaymentInfo* API. Example: any HPP provided by Adyen.

.Payment created when receiving a notification from the provider

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/hpp_notifications.png[width=960,align="center"]

.Pending payment created during the *buildFormDescriptor* call, completed when receiving a notification from the provider

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/hpp_notifications_with_pending_payment.png[width=960,align="center"]

The conceptual flow below shows a 3D-Secure variation of the previous flows. The main difference is that prior redirecting the browser to the landing page, it is first redirected to the access control server where the user can enter custom information.

.Hosted Payment Page 3D-Secure variation

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/payments_hostedpages_3ds.png[width=960,align="center"]

=== Gateway Integration flow

For gateway integrations, the entry point for any payment is either the https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createAuthorization*] (to authorize a credit card), https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createPurchase*] (to charge a payment method, for example authorizing and capturing a credit card, to initiate an ACH transfer, to withdraw money from a Bitcoin wallet, etc.) or https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/payment/api/PaymentApi.java[*createCredit*] (to deposit money on a payment method, without any reference to a previous payment) APIs. The payment state will be in `*_INIT` state before calling the plugin.

Usually, transactions end up in a terminal state right away as most gateways provide synchronous APIs. However, depending on the payment method, the plugin can choose to set the status to *PENDING*. For example, this is the case for 3D-Secure transactions (until the payment is verified by the issuer after redirecting the user), for direct debit transfers (e.g. ACH, which take usually a couple of days to be acknowledged), or for Bitcoin transfers (until the transaction is confirmed by the blockchain). Additionally, some gateways don't always provide synchronous responses (e.g. when capturing funds using Adyen), in which case the plugin has to rely on asynchronous notifications to transition the payment into a terminal state.

Before any payment operation can occur, the user must first enter his payment information. In Kill Bill, this translates into creating a PaymentMethod. When dealing with credit card information specifically, merchants have to keep the data into a PCI compliant environment (often handled by the gateway): this process requires tokenization of the PAN, so that the payment system only handles the token, which is stored at the plugin level and passed to Kill Bill as a plugin property. Take a look at our https://github.com/killbill/killbill-stripe-demo[Stripe demo] for a concrete example.

Note that the creation of the Kill Bill payment method is not represented in the flows below: it can happen either in a prior step or during the payment using one of our combo payment call. Usually, the user is prompted with a form to enter his payment method information, and then the payment is initiated using one of the *createAuthorization* or *createPurchase* APIs. Kill Bill will connect to its payment plugin which in turn will contact the gateway to perform the required operation. Upon success/failure, the user is redirected to a landing page.

.Gateway integration (direct payment API)

image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/payments-userguide/payments_gateway.png[width=960,align="center"]

If 3D-Secure is enabled, the payment (e.g. authorization) is split into two phases:

* The merchant site starts with an authorize call; if enough information is supplied to the gateway and if the payment method is 'registered' as being 3D-Secure, the gateway will return a (gateway) specific status so that the user can be redirected to the access control server to complete the flow
* The user may then enter its specific information on the access control server, and upon success it is then redirected to the merchant site that will complete the authorize phase
{'fraction_non_alphanumeric': 0.05783805345033905, 'fraction_numerical': 0.0031024243230066925, 'mean_word_length': 5.05744966442953, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 32, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3129303', 'n_tokens_mistral': 5663, 'n_tokens_neox': 5441, 'n_words': 3006}