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

Expand/Collapse property list

Parameter	Type	Description
`amount`	`float`	The amount to be charged Required: true
`currency`	`string`	The currency of the amount. 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
`orderId`	`string`	The ID of the order in your store. This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId) Required: false Default: null
`card3ds` (Deprecated)	`boolean`	Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored. Required: false Default: null
`invoiceId`	`string`	This is used to transmit the invoice ID from your shop to the API.
`paymentReference`	`string`	This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer. Required: false Default: null
`additionalTransactionData`	`stdClass`	This can be used to add additional information to your transaction if requiered/supported by the payment method. (for example, it is used to set recurrence type for card payments.)

For a full list of the charges request parameter, please refer to API reference.

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`	`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
`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 indicates the result of the transaction. Possible values SUCCESS, PENDING or ERROR

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

Important information