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");
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
- Cancel a charge (refund)
- Authorize a payment
- Authentication reference
- Test data