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
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