Accept Unzer Prepayment with server-side-only integration

Build your own payment form to add Unzer Prepayment to your checkout page.

Overview

Prepayment payment method doesn’t require any input from the customer on the merchant website. The Unzer API will generate payment information (such as the bank account details) with which the customer must use to pay using a bank transfer.

Before you begin

• Check the basic integration requirements.
• Familiarize yourself with the general Server-side-only integration guide.

Step 1: Create a payment type resource

server side

When creating the payment type Prepayment, you need to send a request to the Unzer API. The response will contain an id , this is later referred to as typeId. You will need this typeId to perform the transaction.

POST https://api.unzer.com/v1/types/prepayment

Body: {}

$unzer = new Unzer('s-priv-xxxxxxxxxx', SupportedLocale::GERMAN_GERMAN);
$prepayment = $unzer->createPaymentType((new Prepayment()));

Unzer unzerInstance = new Unzer("s-priv-xxxxxxxxxx");
Prepayment prepayment = unzerInstance.createPaymentType(new Prepayment());

The response will look similar to the following example:

{
  "id": "s-ppy-vazzovscvxnu",
  "method": "prepayment",
  "recurring": false,
  "geoLocation": {
    "clientIp": "115.77.189.143",
    "countryCode": "VN"
  }
}

For a full description of Prepayment payment type creation, check API reference.

Step 2: Make a payment

server side

Make a charge transaction

Now, make a charge transaction with the Prepayment typeId that you created. With a successful charge transaction a payment resource is created. At this point no money has been transferred. The customer has to transfer the amount to the bank account which information are provided in the charge transaction response.

POST https://api.unzer.com/v1/payments/charges

{
  "amount" : "50",
  "currency" : "EUR",
  "returnUrl" : "https://www.my-shop-url.de/returnhandler",
  "resources" : {
    "typeId" : "s-ppy-ptz1cm2u4x7i"
  }
}

$unzer = new Unzer('s-priv-xxxxxxxxxx');
$prepayment = $unzer->fetchPaymentType('s-ppy-ptz1cm2u4x7i');
$charge = $prepayment->charge(20.0, 'EUR', 'https://www.my-shop-url.de/returnhandler');

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Prepayment charge = unzer.charge(BigDecimal.ONE, Currency.getInstance("CHF"), "s-ppy-ptz1cm2u4x7i", new URL("https://www.my-shop-url.de/returnhandler"));

The response looks similar to the following example:

{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "customer": "Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "amount": "50.6000",
    "currency": "EUR",
    "returnUrl": "https://www.my-shop-url.de/returnhandler",
    "date": "2018-09-26 14:15:13",
    "resources": {
        "paymentId": "s-pay-7786",
        "typeId": "s-ppy-ptz1cm2u4x7i"
    },
    "processing": {
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX",
        "uniqueId": "31HA07BC8137E7B23DE99031E56C4924",
        "shortId": "4018.9771.3370",
        "descriptor": "4018.9771.3370",
        "holder": "Merchant Thuan"
    }
}

For a full description of the charge transaction, refer to the relevant server-side integration documentation page: Charge a payment (direct API calls), Charge a payment (PHP SDK), Charge a payment (Java SDK).

Step 3: Check status of the payment

server side

Once the transaction is made, you can fetch the payment details from the API, by using the resources.paymentId from the charge response above to handle the payment according to its status. Check all possible payment states here.

Unlike most of the other payment types, the initial Charge will always be in status pending.

GET https://api.unzer.com/v1/payments/{payment_ID}

{
    "id": "s-pay-921",
    "state": {
        "id": 0,
        "name": "pending"
    },
    "amount": {
        "total": "50.6000",
        "charged": "0.0000",
        "canceled": "0.0000",
        "remaining": "50.6000"
    },
    "currency": "EUR",
    "orderId": "",
    "invoiceId": "",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-921",
        "basketId": "",
        "metadataId": "",
        "payPageId": "",
        "traceId": "b51b892a8896e73c8cfe740803e79531",
        "typeId": "s-ppy-vaq3p5vkfbmm"
    },
    "transactions": [
        {
            "date": "2021-05-17 11:51:32",
            "type": "charge",
            "status": "pending",
            "url": "https://api.heidelpay.com/v1/payments/s-pay-921/charges/s-chg-1",
            "amount": "50.6000"
        }
    ]
}

Step 4. Display payment result

client side

After the transaction is made you should display its result to the customer in the front end. Here you have to display the bank Information, the customer should transfer the money to.

This information should be displayed on the invoice (email/document).
They can also be shown on the success page or in the customer backend of your shop.

sprintf(
    "Please transfer the amount of %f %s to the following account:<br /><br />"
    . "Holder: %s<br/>"
    . "IBAN: %s<br/>"
    . "BIC: %s<br/><br/>"
    . "<i>Please use only this identification number as the descriptor: </i><br/>"
    . "%s",
    $charge->getAmount(),
    $charge->getCurrency(),
    $charge->getHolder(),
    $charge->getIban(),
    $charge->getBic(),
    $charge->getDescriptor()
);

Manage payment

server side

For more details on managing Unzer Prepayment payments, such as refunding them, see Manage Unzer Prepayment payments.

Notifications

We recommend subscribing to the payment event to receive notifications about any changes to the payment resource. As soon as the event is triggered you should fetch the payment and update the order status in your shop according to its status.

  {
    "event":"payment.pending",
    "publicKey":"s-pub-xxxxxxxxxx",
    "retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
    "paymentId":"s-pay-774"
  }

For more details on implementing webhooks to receive notifications, see Notifications page.

Error handling

All requests to the API can result in an error that should be handled. Refer to the Error handling guide to learn more about Unzer API (and other) errors and handling them.

Test & go live

You should always test your integration before going live. First perform test transactions using test data. Next, check against Integration checklist and Go-live checklist to make sure the integration is complete and you’re ready to go live.

See also

• Manage API resources:
  • Manage API resources (direct API calls)
  • Manage API resources (PHP SDK)
  • Manage API resources (Java SDK)
• Unzer API basics