anchor.diff:  
   The former set of APIs is used by the core billing engine to charge for subscriptions, and by Kaui (the Kill Bill Admin UI) to handle refunds, chargebacks, adjustments, etc. for invoices and payments associated with such subscriptions.
   
  -The latter set can be used to trigger payments (auth, capture, credit, refund, etc.) by your e-commerce application (e.g. shopping cart). It offers also helpers to create payment forms and redirect URLs in case of hosted payment pages.
  +The latter set can be used to trigger payments (auth, capture, credit, refund, etc.) by your e-commerce application (e.g. shopping cart). It offers also helpers to create payment forms and redirect URLs in case of hosted payment pages. It is independant of any subscriptions or invoices and is used solely to make payments.
   
  -Kill Bill, being a generic platform to build billing and payment infrastructures, is agnostic of payment gateways. Instead, it provides a framework to register payment plugins, which in turn implement gateway specific APIs. Those payment plugins must be OSGI compliant plugins. They can be written either in:
  +Kill Bill is a generic platform to build billing and payment infrastructures and as such, it is agnostic of payment gateways. However, it provides a framework to register payment plugins, which in turn implement gateway specific APIs. Those payment plugins must be OSGI compliant plugins. They can be written either in:
   
   * java; in which case they are just a standard OSGI java jar which must register a service implementing the https://github.com/killbill/killbill-plugin-api/blob/master/payment/src/main/java/org/killbill/billing/payment/plugin/api/PaymentPluginApi.java[PaymentPluginApi]
   * ruby; in which case they must use the https://github.com/killbill/killbill-plugin-framework-ruby[killbill gem] which provides a jruby bridge between java and ruby. Those plugins must inherit the https://github.com/killbill/killbill-plugin-framework-ruby/blob/master/lib/killbill/payment.rb[Payment class] to provide the specific plugin code functionality
  
positive.code: 
  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) 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. All calls create a payment id before calling the plugin.
  
  All of the payment APIs (*createAuthorization*, *createCapture*, *createPurchase*, *createVoid*, *createRefund*, *createCredit* and *createChargeback*) will attach transaction records to that original payment: for example, a payment can have an authorization and two capture transactions associated to it. Each transaction has its own state upon returning from the plugin:
  
  * if the plugin throws an error, the payment moves to the *PLUGIN_FAILURE* terminal state
  * if the plugin returns *UNDEFINED* the payment moves to the *UNKNOWN* terminal state
  * if the plugin returns *PROCESSED*, the payment moves to the *SUCCESS* terminal state
  * if the plugin returns *ERROR*, the payment moves to the *PAYMENT_FAILURE* terminal state
  * if the plugin returns *PENDING*, the payment moves to the *PENDING* state. This is used for multi-step calls (e.g. 3D Secure authorization)
  
  Note that contrary to the hosted page scenario, transactions always end up in a terminal state right away. There is no polling needed because the gateway will return the payment status synchronously (there is not asynchronous notification). The only exception to this is when the payment ends up in the *PENDING* state. Plugins set this status when additional steps are required to acknowledge the payment, for example in case of 3D Secure or Bitcoin (while waiting on miners to integrate the transaction deep enough in the blockchain).
negative.code: 
  Check the wiki page https://github.com/killbill/killbill/wiki/Payment-plugins[Payment Plugins] for a community-supported list of already written payment plugins.
  
  The Kill Bill payment code will detect all the payment plugins registered in the system and decide which plugin to use when a charge, refund, ... operation needs to happen. The dispatching is based on the payment methods associated with each account. By default, the model is to attach a default payment method to each account: that payment method will have a link that points to a specific plugin to use. For instance, one account could have a Paypal payment method that would point to the Paypal plugin. Additionally, you can also override the payment method to use on a per payment call.
  
  By default Kill Bill does not come configured with any payment plugins per se except for the built-in __EXTERNAL_PAYMENT__, which is used to track payments which occurred outside of Kill Bill. A typical example would be for when a customer pays by check and we want to make sure the invoice balance is set to 0 after receiving the check. A user, represented in Kill Bill as an account can add as many payment methods as required, and each of those will identify a specific plugin that Kill Bill will use when making payments.
  
  === Payment states and abstractions
  
  Initially a client of the api can make either an auth, a purchase, or a credit call. That initial operation will create a *payment* and along with the payment an initial *payment_transaction*. The user can then submit additional requests for the same payment (capture, refund, ...) and each of those calls will result in additional payment_transaction attached to the same payment. The payments have a state which will drive the set of possible subsequent operations available. For instance, it is possible to make a capture call against a payment in a state AUTH_SUCCESS but it is not possible to make such operation against a payment in an AUTH_ERRORED state. The set of payment state transitions are configured in an xml file and the Kill Bill payment subsystem is in charge to enforce the transitions:
  
  image::payment_states.svg[Kill Bill payment states, align="center"]
  
  In addition to the payment state transitions, each payment_transaction has a status to reflect the result of the operation. The payment_transaction status depends on the plugin result and it can be summarized below:
  
  |===
  |plugin result | payment_transaction status | payment_state | description
  
  |PROCESSED
  |SUCCESS
  |{AUTH,CAPTURE,..}_SUCCESS
  |Success opertaion
  
  |PENDING
  |PENDING
  |{AUTH,CAPTURE,..}_PENDING
  |Success asynchronous operation, or multi-step calls (e.g. 3D Secure authorization)
  
  |ERROR
  |PAYMENT_FAILURE
  |FAILED
  |The gateway, bank declined the operation
  
  |UNDEFINED, timeout
  |UNKNOWN
  |ERRORED
  |Plugin timed out or returned an UNDEFINED state
  
  |Any exception
  |PLUGIN_FAILURE
  |ERRORED
  |The plugin threw an exception
  
  |===
  
  Note that the first 3 cases are normal cases but tha last 2 are errors that are unrelated to the user being able to make the payment operation:
  
  * in the case of a plugin timeout (or UNDEFINED result code), the operation might actually have completed; Kill Bill will run a background task to detect those cases and will query the plugin to verify if the state is actually known and when it is, it will update both the transaction_status and move the payment to its appropriate state.
  * in the case of a plugin exception, this is probably a bug, and so there is no attempt to fix those. However it advisable to check that those are rare instances and fix code/data appropriately.
  
  
  === Payment flows
  
  There are two main payment flows, which we will describe separately. On one hand, customers can be redirected to an external website to complete the payment. We refer to this as *Hosted (payment) pages* (e.g. PayPal). Alternatively, if the customer doesn't leave your website and you process the payment directly by calling a gateway API, this is called a *Gateway integration*.
  
  ==== Hosted page
  
  