Performing Transactions

Authorize and (direct) Charge

An authorization transaction leads to the creation of an authorization resource and a payment resource. Similarly a charge transaction leads to the creation of a charge resource and a payment resource.

The Authorize and the Charges page tell you which payment methods supports which transaction type, as not all of them support them both.

Examples

In general the transaction calls on a payment type require at least the amount, the currency and the returnUrl. See the following examples on both transaction types.

// basic authorization example

Card card = new Card("4444333322221111", "03/20");
card.setCvc("123");
Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
card = heidelpay.createPaymentType(card);

Authorization authorization = card.authorize(BigDecimal.ONE, Currency.getInstance("EUR"), new URL("https://www.meinShop.de"));
// full authorization example

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

//Create card payment method
Card card = new Card("4444333322221111", "03/20");
card.setCvc("123");
card = heidelpay.createPaymentType(card);

Customer customer = new Customer("Max", "Mustermann");
customer = heidelpay.createCustomer(customer);

String orderId = '12345678';

Metadata metadata = new Metadata();
metadata.addMetadata("MyCustomData", "my custom value");
metadata = heidelpay.createMetadata(metadata);

BasketItem basketItem = new BasketItem();
basketItem.setBasketItemReferenceId("Artikelnummer4711");
basketItem.setQuantity(5);
basketItem.setAmountPerUnit(new BigDecimal("100.1"));
basketItem.setAmountNet(new BigDecimal("420.1"));
basketItem.setTitle("Apple iPhone");

Basket basket  = new Basket();
basket.setAmountTotalGross(new BigDecimal("500.5"));
basket.setCurrencyCode("EUR");
basket.setOrderId("uniqueOrderId_1");
basket.addBasketItem(basketItem);
baket = heidelpay.createBasket(basket);

Boolean card3ds = true;
card.set3ds(card3ds);

Authorization card = card.authorize(new BigDecimal("500.5"), "EUR", "https://your.return.url", customer);
/* Will be uncommented when sdk is updated.
Authorization authorize = card.authorize(new BigDecimal("500.5"), "EUR", "https://your.return.url", customer, orderId, metadata, basket, card3ds, "invoiceId", "payment reference text");
*/
// basic charge example

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Card card = heidelpay.fetchPaymentType("s-crd-9wmri5mdlqps");

Charge charge = card.charge(new BigDecimal("100.0"), "EUR", "https://www.heidelpay.com");
// basic payout example

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Card card = createPaymentTypeCard();
Payout payout = heidelpay
  .payout(BigDecimal.ONE
          , Currency.getInstance("EUR")
          , card.getId(), new URL("https://www.heidelpay.com"));

However, some payment types require a `customer resource as well, which can be passed as additional parameter to the transaction. Please refer to the Additional Resources section to learn more about adding a customer reference.

Arguments to direct charge and authorize transaction methods

Parameter Type Description
amount float The amount to be charged/authorized.
Required: true
currency string The currency of the amount.
Required: true
returnUrl string The URL the API leads the customer to after he finished entering payment information outside of the shop (e.g. PayPal).
This needs to be set to a valid URL, no matter whether a redirect is necessary or not.
Required: true
customer com.heidelpay.payment.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 not set (i. e. the resource does not exist yet) the customer resource will automatically be created and referenced. Find additional information here.
Required: false
Default: null
orderId string The id of the order in your store.
Required: false
Default: null
metadata com.heidelpay.payment.Metadata A reference to the metadata corresponding to this payment.
A metadata resource will automatically be created if none is supplied. This is done to pass along information on the version and type of the SDK to the API. Find additional information here.
Required: false
Default: null
basket com.heidelpay.payment.Basket A reference to the basket corresponding to this payment. Find additional information here.
Required: false
Default: null
card3ds 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 invoiceId from your shop to the API.
Required: false
The invoiceId is necessary in case of Invoice payment, however it can also be transmitted later with the shipment call.
Default: null
paymentReference string This is a reference string to show the customer the purpose of the transaction.
Required: false
Default: null
returnUrl
The argument returnUrl needs to be set to a valid URL, no matter whether a redirect is necessary for the payment type or not.

Charge an Authorization

If an Authorization transaction has been performed the authorized amount can be charged. It is possible to perform several charges until the authorized amount is reached.

// charge authorized amount by payment id

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Charge charge = heidelpay.chargeAuthorization("s-pay-1");
// charge authorized amount by authorization object

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Authorization authorization = heidelpay.fetchAuthorization("s-pay-1");

charge = authorization.charge();
// part charge authorization by payment id

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Charge charge1 = heidelpay.chargeAuthorization("s-pay-1", new BigDecimal("50"));
Charge charge2 = heidelpay.chargeAuthorization("s-pay-1", new BigDecimal("50"));
// part charge authorization by authorization object

Heidelpay heidelpay = new heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Authorization authorization = heidelpay.fetchAuthorization("s-pay-1");

Charge charge1 = authorization.charge(new BigDecimal("50"));
Charge charge2 = authorization.charge(new BigDecimal("50"));

Arguments to heidelpay::chargeAuthorization

Parameter Type Description
payment string The id of the payment resource or the payment object itself can be entered here.
Required: true
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false

Arguments to Authorization::charge

Parameter Type Description
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false

Cancel on an Authorization (aka Reversal)

An cancellation transaction for an authorization transaction results in the creation of a cancellation resource linked to the original authorization resource.

The cancel method has the parameter amount, which can be left empty to perform a full reversal of the authorization. If the amount is set the reversal will reduce the authorization amount.

// full cancel on Authorization

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Authorization authorization = heidelpay.fetchAuthorization("s-pay-1");

Cancel cancellation = authorization.cancel();
// part cancel on authorization

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Authorization authorization = heidelpay.fetchAuthorization("s-pay-1");

Cancel cancellation = authorization.cancel(new BigDecimal("50"));

Arguments to Authorization::cancel

Parameter Type Description
amount float The amount to reduce the authorization by. The method will perform a full cancel of the authorization (and payment) if the amount is not set.
Required: false

Cancel on a Charge (aka Refund)

A cancel transaction on a Charge transaction will result in the creation of a Cancellation resource linked to the original Charge resource.

The cancel method has the amount parameter that can be left blank to perform a full refund of the charge. If the amount is set, the refund will reduce the charged amount.

// full cancel on Charge

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Charge charge = heidelpay.fetchChargeById("s-pay-1", "s-chg-1");

Cancel cancel = charge.cancel();
// part cancel on Charge

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Charge charge = heidelpay.fetchChargeById("s-pay-1", "s-chg-1");

Cancel cancel = charge.cancel(new BigDecimal("50"));

Arguments to Charge::cancel

Parameter Type Description
amount float The amount to cancel. The method will perform a full cancel of the charge (and payment) if the amount is not set.
Required: false
Default: null
Required: false
reasonCode string The reason why the charge amount is reduced/cancelled.
It can be one of the following:
‘CANCEL’, ‘RETURN’, ‘CREDIT’.
Default: null
paymentReference string This is a reference string to show the customer the purpose of the refund.
Required: false
Default: null

Payout

This transaction credits an amount of money to a payment type without any reference to a previous payment transaction.

// payout transaction via heidelpay object

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Card card = heidelpay.fetchPaymentType("s-crd-9wmri5mdlqps");

Payout payout = heidelpay.payout(new BigDecimal("100"), "EUR", card, "https://docs.heidelpay.com");
// payout transaction via payment type object

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Card card = heidelpay.fetchPaymentType("s-crd-9wmri5mdlqps");

/* We don't have it at the moment.
Payout payout = card.payout(new BigDecimal("100"), "EUR", "https://docs.heidelpay.com", null, null, null, null, "invoiceId", "payment reference text");
*/

The payout transaction is currently available for the following payment types:

  • Card
  • Unzer Direct Debit Secured

Arguments to BasePaymentType::payout()

Name Type Description
amount float The amount to credit the given payment type with.
Required: true
currency string The currency of the amount.
Required: true
returnUrl string A return URL (which is not used in this transaction).
customer string A reference to the customer resource corresponding to this transaction.
This can be either a customer object or the id of an existing customer resource. If a customer object is used whose id not set (i. e. the resource does not exist yet) the customer resource will automatically be created and referenced. Find additional information here.
Required: only in case of guaranteed payment types
Default: null
orderId string The id of the order in your store.
Required: false
Default: null
metadata com.heidelpay.payment.Metadata A reference to the metadata corresponding to this payment.
A metadata resource will automatically be created if none is supplied. This is done to pass along information on the version and type of the SDK to the API. Find additional information here.
Required: false
Default: null
basket com.heidelpay.payment.Basket A reference to the basket corresponding to this payment. Find additional information here.
Required: false
Default: null
invoiceId string This is used to transmit the invoiceId from your shop to the API.
Required: false
Default: null
paymentReference string This is a reference string to show the customer the purpose of the transaction.
Required: false
Default: null
In case of guaranteed payment methods (e. g. Unzer Direct Debit Secured) the 4th parameter for payout transaction $customer is mandatory.

Shipment

A Ship transaction on a payment results in the creation of a shipment resource linked to the payment.

The ship method on the heidelpay object requires the payment as parameter that is passed as an object or a as payments id string.

// shipment transaction on the heidelpay object by payment id

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Shipment shipment = heidelpay.shipment("s-pay-1");
// shipment transaction on the heidelpay object by payment object

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");

Payment payment = heidelpay.fetchPayment("s-pay-1");

Shipment shipment = heidelpay.shipment(payment);

Arguments to heidelpay::ship

Parameter Type Description
payment string The id of the payment resource or the payment object itself can be entered here.
Required: true
invoiceId string The id of the invoice in your shop. Only applicable in case of invoice payment types.
Required: only in case of invoice payment types.

Arguments to Payment::ship

Parameter Type Description
invoiceId string The id of the invoice in your shop. Only applicable in case of invoice payment types.
Required: only in case of invoice payment types.

Transaction Results

Transaction provide a message property holding the result of the last state change of the transaction. The message object stored here has a code and a message stored in the property customer.

The message can be used to give a specific reason for a state change e.g. as to why a transaction failed. The state of a transaction can change asynchronously e. g. from pending to successful or from pending to error. You can check the result of a transaction within a request in order to find out whether the payment was successful. Or fetch a transaction asynchronously to check the state and reason for the state the transaction is in.

Heidelpay heidelpay = new Heidelpay(new HttpClientBasedRestCommunication(), "s-priv-xxxxxxxxxx");
Authorization authorize = heidelpay.authorize(new BigDecimal("12.99"), "EUR", paymentTypeId, "https://www.heidelpay.de"); //paymentTypeId: s-crd-1, for instance