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
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$authorize = $card->authorize(100.0, 'EUR', 'https://www.heidelpay.com');
// full authorization example
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$customer = (new \heidelpayPHP\Resources\Customer())
  ->setFirstname('Max')
  ->setLastname('Mustermann');

$orderId = '12345678';

$metadata = new \heidelpayPHP\Resources\Metadata();
$metadata->addMetadata('MyCustomData', 'my custom value');

$basketItem = (new \heidelpayPHP\Resources\EmbeddedResources\BasketItem())
  ->setBasketItemReferenceId('Artikelnummer4711')
  ->setQuantity(5)
  ->setAmountPerUnit(100.1)
  ->setAmountNet(420.1)
  ->setTitle('Apple iPhone');
$basket  = (new \heidelpayPHP\Resources\Basket())
  ->setAmountTotalGross(500.5)
  ->setCurrencyCode('EUR')
  ->setOrderId('uniqueOrderId_1')
  ->addBasketItem($basketItem);

$card3ds = true;

$authorize = $card->authorize(500.5, 'EUR', 'https://your.return.url', $customer, $orderId, $metadata, $basket, $card3ds, 'invoiceId', 'payment reference text');
// basic charge example
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$charge = $card->charge(100.0, 'EUR', '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 heidelpayPHP\Resources\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 heidelpayPHP\Resources\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 heidelpayPHP\Resources\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 = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$charge = $heidelpay->chargeAuthorization('s-pay-1');
// charge authorized amount by authorization object
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$authorization = $heidelpay->fetchAuthorization('s-pay-1');

$charge = $authorization->charge();
// part charge authorization by payment id
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$charge1 = $heidelpay->chargeAuthorization('s-pay-1', 50.0);
$charge2 = $heidelpay->chargeAuthorization('s-pay-1', 50.0);
// part charge authorization by authorization object
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$authorization = $heidelpay->fetchAuthorization('s-pay-1');

$charge1 = $authorization->charge(50.0);
$charge2 = $authorization->charge(50.0);

Arguments to heidelpay::chargeAuthorization

Parameter Type Description
payment string or heidelpayPHP\\Resources\\Payment 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 = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$authorization = $heidelpay->fetchAuthorization('s-pay-1');

$cancellation = $authorization->cancel();
// part cancel on Authorization

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$authorization = $heidelpay->fetchAuthorization('s-pay-1');

$cancellation = $authorization->cancel(50.0);

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 = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$charge = $heidelpay->fetchChargeById('s-pay-1', 's-chg-1');

$cancel = $charge->cancel();
// part cancel on Charge

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$charge = $heidelpay->fetchChargeById('s-pay-1', 's-chg-1');

$cancel = $charge->cancel(50.0);
// cancel Unzer Instalment

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$payment = $heidelpay->fetchPayment('s-pay-1');

$cancel = $payment->cancelAmount(59.5, null, 'Payment reference text', 50.0, 9.5);

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.
This is transmitted as amountGross in case of Unzer Instalment.
Required: false
Default: null
reasonCode string (heidelpayPHP\Constants\CancelReasonCodes) 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
amountNet float The net amount to cancel.
Required: only in case of Unzer Instalment.*
Default: null
amountVat float The VATamount to cancel.
Required: only in case of Unzer Instalment.*
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 = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$payout = $heidelpay->payout(100.00, 'EUR', $card, 'https://docs.heidelpay.com');
// payout transaction via payment type object

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$card = $heidelpay->fetchPaymentType('s-crd-9wmri5mdlqps');

$payout = $card->payout(100.0, '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 \heidelpayPHP\Resources\Customer
orderId string The id of the order in your store.
Required: false
Default: null
metadata \heidelpayPHP\Resources\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 \heidelpayPHP\Resources\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.

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$shipment = $heidelpay->ship('s-pay-1);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$payment = $heidelpay->fetchPayment('s-pay-1');

$shipment = $heidelpay->ship($payment);
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$payment = $heidelpay->fetchPayment('s-pay-1');

$shipment = $payment->ship();

Arguments to heidelpay::ship

Parameter Type Description
payment string or heidelpayPHP\\Resources\\Payment 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.

// check result of a transaction

$heidelpay = new Heidelpay('s-priv-xxxxxxxxxx');
$authorize = $heidelpay->authorize(12.99, 'EUR', $paymentTypeId, 'https://www.heidelpay.de');

if (!$authorize->isError()) {
    $this->redirectToSuccess();
}
$this->log($authorize->getMessage()->getCustomer());
$this->redirectToFailure();