Charge a payment

Transfer money form the customer to the merchant.

Overview

The charge resource is used for activating the flow of transferring the money from the customer to you (merchant). When the customer initiates a payment, based on your configuration, a direct charge request or authorization request is created. You can either charge directly or authorize the payment and then charge it later.

Check Payment methods page to see what payment methods support direct charge and charge after authorization.

Charge directly

Direct charge will debit customer’s account without any prior authorization.

To trigger a direct charge, call the charge function of the Unzer object with an amount, currency, order ID, and a reference to a payment method. Alternatively, you can use the charge function of an existing payment type object

// basic charge example
Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.charge(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "s-crd-9wmri5mdlqps", "https://your.return.url");

// basic charge example
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Card card = (Card) unzer.fetchPaymentType("s-crd-9wmri5mdlqps");
Charge charge = card.charge(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "https://your.return.url");

Some payment types require a customer resource, which can be passed as additional parameter to the transaction.
Refer to the Manage Customer section to learn more about adding a customer reference.

Arguments to Unzer.charge

Parameter	Type	Description
amount	BigDecimal	The amount to be charged Required: true
currency	Currency	The currency of the amount. Required: true
paymentType	string \| `PaymentType`	The PaymentType object or the ID of the PaymentType to use. The `charge` function of payment types don’t have this parameter, the other parameters are the same, though. Required: true
returnUrl	string	The URL the customer will be redirected to after a transaction. This needs to be set to a valid URL, no matter whether a redirect is necessary or not. Required: true
customer	string \| `Customer`	A reference to the customer resource corresponding to this payment. This can be either a customer object or the ID of an existing customer resource. If a customer object is used whose ID is not set (i.e. the resource does not exist yet in the PAPI) the customer resource will automatically be created and referenced with the transaction call. For more details, see Manage customer. Required: false Default: null
orderId	string	The ID of the order in your store. Required: false Default: null
metadataId	string	A reference to the metadata corresponding to this payment. The metadata object can be used to pass along custom information which you wish to reference to the payment. For more details, see Manage metadata. Required: false Default: null
basket	`Basket`	A reference to the basket corresponding to this payment. For more details, see Manage baskets which is between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise, it is ignored. Required: false Default: null
invoiceId	string	Used to send the invoice ID from your shop to the API. Required: false The invoiceId is required for Unzer Invoice Secured payment, however it can also be sent later with the shipment call. Default: null
paymentReference	string	This is a reference string to display to the customer the purpose of the transaction. This is displayed on the bank statement of the customer. Required: false Default: null
recurrenceType	string	Recurrence type used for recurring payments. Required: false Default: null

Arguments to charge of payment type

Parameter	Type	Description
amount	BigDecimal	The amount to be charged Required: true
currency	`Currency`	The currency of the amount. Required: true
returnUrl	`URL`	The URL to which the customer will be redirected to after a transaction. This must be set to a valid URL, even if a redirect is not required. Required: true
customer	`Customer`	A reference to the customer resource corresponding to the payment. This can be either a customer object or the ID of an existing customer resource. If a customer object is used for which the ID is not set (that is, the resource is not yet available in PAPI) the customer resource is automatically created and referenced with the transaction call. For more details, see Manage customer. Required: false Default: null

Charge after Authorization

You can charge a payment after authorization. You can have several charges up to the authorized amount. The SDK provides multiple ways to perform this task.

Option 1: Charge full amount

// charge authorized amount by payment ID
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Charge charge = unzer.chargeAuthorization('s-pay-1');

// charge authorized amount by authorization object
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Authorization authorization = unzer.fetchAuthorization('s-pay-1');
Charge charge = authorization.charge();

// charge authorized amount by payment object
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Payment payment = unzer.fetchPayment('s-pay-1');
Charge charge = payment.charge();

Option 2: Charge partial amount

If you want, you can also partially charge a payment. This is useful if you shipped some goods to the customer and only want to invoice the shipped goods. If you are charging partially, and charge more than the total charge amount, an error is displayed.

// part charge authorization by payment ID
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Charge charge1 = unzer.chargeAuthorization('s-pay-1', BigDecimal.valueOf(50.0));
Charge charge2 = unzer.chargeAuthorization('s-pay-1', BigDecimal.valueOf(50.0));

// part charge authorization by authorization object
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Authorization authorization = unzer.fetchAuthorization('s-pay-1');
Charge charge1 = authorization.charge(BigDecimal.valueOf(50.0));
Charge charge2 = authorization.charge(BigDecimal.valueOf(50.0));

// part charge authorization by payment object
Unzer unzer = new Unzer('s-priv-xxxxxxxxxx');
Payment payment = unzer.fetchPayment('s-pay-1');
Charge charge1 = payment.charge(BigDecimal.valueOf(50.0));
Charge charge2 = payment.charge(BigDecimal.valueOf(50.0));

Arguments to Unzer.chargeAuthorization

Parameter	Type	Description
paymentId	string	The ID of the payment resource or the payment object itself. Required: true
amount	BigDecimal	The amount that must be charged. If the amount is not set, the full authorization amount is charged. Required: false Default: null

Arguments to Authorization.charge

Parameter	Type	Description
amount	BigDecimal	The amount of authorization that must be charged. If an amount is not specified, then the full amount is charged. Required: false Default: null

Arguments to Payment.charge

Parameter	Type	Description
amount	float	The amount of authorization that must be charged. If an amount is not specified, then the full amount is charged. Required: false Default: null
currency	`Currency`	The currency of the amount. Required: false Default: null

Transaction Results

The transaction response is stored in the transaction object. It contains a paymentId (for example, s-pay-1) the transactionId, and other properties of the response. The transaction object provides getter functions to access those properties, for example charge.getPaymentId()

The status-parameter indicate the result of the transaction. The Enum can only be SUCCESS, PENDING or ERRROR

If a transaction fails, the payment API returns an error resource instead of a transaction. In the SDK, this is handled as an UnzerPaymentException. Make sure to catch that case properly.

try {
    Unzer unzer  = new Unzer("s-priv-xxxxxxxxxx");
    Charge charge = unzer.charge(BigDecimal.valueOf(12.99), Currency.getInstance("EUR"), "s-crd-9wmri5mdlqps", "https://your.return.url");

    if (charge.Status.equals(Charge.Status.SUCCESS)) {
        this.redirectToSuccess();
    }
    // Transaction has to be pending at this point.
    this.redirectToPending();
} catch (HttpCommunicationException | PaymentException e) {
    // Transaction failed. API returned error resource.
    List<PaymentError> paymentErrorList = e.getPaymentErrorList();
    //Handle API Errors
    
    this.redirectToFailure(); // redirect to the failure page of your shop
} catch (Exception e) {
    merchantMessage = e.getMessage();
}