Charges are an abstraction on top of invoices, providing a convenient way to charge customers with one-time payments and to pay existing unpaid invoices. Charges are basically a combination of an invoice and a payment transaction . Charges allow to pay either with a direct settle or with a two-step process consisting of an authorization reserving an amount, and a subsequent settle. The handle for a charge is also the invoice handle and can be seen as an order identification in own shopping system. If an invoice does not already exist an invoice will be created with state created and a payment transaction performed. After a payment attempt the resulting invoice will be in one of the following states: settled, authorized, failed, pending or pending. If the charge is failed it can be retried with the same handle. The pending state is only used for asynchronous payment methods (e.g. MobilePay Subscriptions) where the result of the charge operation is not known immediately. Webhooks must be used to listen for the state change. Card payments are always synchronous.
To create a charge a customer needs to be provided. This can either be a reference to an existing customer, or a create customer object. If a customer payment method (e.g. ca_..) is used a customer reference does not need to be provided as the payment method implicitly defines the customer. If an object is provided the customer will be created if the customer does not already exist in which case the existing customer will be used.
The amount for a charge is given either with the argument amount and optionally ordertext, or by providing a list of detailed order lines.
To create a charge a payment source must be provided with a reference to an existing payment method for the customer. E.g. ca_... for saved credit cards.
Notice that if Billwerk+Optimize Checkout is used as payment window, you do not need to create the charge directly. If will be created by Billwerk+Optimize Checkout.
The charge resource allows the use of an idempotency key to retry the same request multiple times. Multiple calls with the same key will yield the same result. This is convenient in cases of network outages where the result of a call is not received. In this case the same call can be retried. If the outcome a create charge is a failed charge a different idempotency key needs to be provided for a subsequent attempt to pay the same charge. Notice that even without using the idempotency key there is no risk of moving money twice when using the same handle. The operations around an invoice is locked, and an invoice can only be settled/authorized once.
The result of a charge can be monitored using webhooks by listening for the following events:
invoice_settled- Charge was a successful settle.invoice_authorized- Charge was a successful authorization.invoice_failed- Charge failed. To get error codes and additional information use the get charge operation.
An authorized invoice must normally be settled within seven days before the authorization expire. An authorization can also be cancelled resulting in an attempt to void the reservation of money. A cancel will result in an invoice with state cancelled.