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();
}

See also