API migration

Learn how to migrate from the old heidelpay API to the new Unzer API.

Overview

This migration guide gives you a basic understanding of the new heidelpay payment platform and list all the differences between the old and the new API.

If you’re using the old API, you can learn about the changes and updates to integrate using the new API.

Also, it helps to answer a few questions you might have, such as:

• Where is my senderId, username, password and channel?
• Where are the processing codes or status codes?
• What happened to groups?

Ensure that all the new transactions for initial recurring card payment that are created using the API, are flagged correctly as recurring payment according to their recurring type.

To learn more, see the card use cases

Key differences

Request vs Resource

The API implementation of the old heidelpay API was based on a simple yet reliable request-response approach. An API call is formulated, all the necessary parameters added and it is then sent to the server. After that, the server either sends a success or an error message back.

In the new API, instead of sending one request after another and waiting for a response, you create resources and send them using the REST service. This is much easier and comprehensible than formulating an API call every single time. You then link the resources to each other and reference them within the next calls.

Another big advantage of is that you check (get) the status of a resource, such as a payment or charge.

So, instead of sending one single request, different reusable resources are created. The following is a list of resources and mappings to existing functionality and terminology:

Unique ID and short ID

In the previous implementation these were called Unique IDs and Short IDs.

Unique IDs always have 32 alphanumeric digits and were used to uniquely identify the physical sender, the channel, the user login, a single transaction and a specific account or customer. Short-IDs have the format 0000.0000.0000 and are not unique for transactions. These were often used when talking to support about a specific transaction.

Although the unique and short ID are still available and visible in the new API, they’re not necessary to uniquely identify a single transaction anymore. For identifying a specific transaction/payment in the new API, the payment resource is available.

Like every other resource in the new API, the payment resource has a unique resource ID tied to it. In that resource, you can find the payment state, the payment amount, and all the transactions related to that specific payment.

To learn more about payments, see online payments documentation and in the API reference.

Payment resource ID example: p-pay-1234

Resource IDs
All resource IDs across the new API are unique only for the key pair they were generated with. They are not unique across multiple key pairs.

Security

In the old API, credentials were passed using the sender ID, login, and password. Additionally, the channel was mandatory to identify the payment transaction. All of these parameters are now replaced by the public key and the private key.

Public keys are used within the web application or within mobile apps. The private key is more like your username and password put into one string. This should be protected and will be used to authenticate transactions coming from your server.

References

REST based resources use the URL to identify a payment. So, you can have several p-chg-1 IDs within different payments. Only in conjunction with the URL like https://api.heidelpay.com/v1/payments/p-pay-1/p-chg-1 it is evident that the charge belongs to p-pay-1. The following source code shows how references are used within the resources section of the JSON request:

POST <https://api.heidelpay.com/v1/payments/charges>
{
  "amount" : "50",
  "currency" : "EUR",
  "returnUrl" : "https://www.heidelpay.com",
  "orderId": "uniqueOrderId-1",
  "card3ds": "false",
  "resources" : {
    "typeId" : "s-crd-334mrpuadja2",
    "basketId": "s-bsk-16245",
    "customerId" : "s-cst-33da5484e227",
    "metadataId": "s-mtd-ufx8pg6tnxxi",
  }
}

Payment transaction updates

User group

The user group earlier contained information about the user sending the request. It consisted of USER.LOGIN and USER.PWD. In the new API, parameters like these become obsolete. The authentication process and the associated user are all included inside the key pair. In other words, a key pair contains all the necessary information and configuration for a specific merchant and is tied to this merchant.

Identification group

The identification group earlier consisted of all IDs used for identification of a transaction. Other than the unique and short ID, the others (such as transactionId, shopperId, and invoiceId) could be set by the merchant. The referenceId was required for payments which referenced a former transaction.

The new API supports this functionality and makes it easy for you to use it. Although unique ID and short ID are still in use, they aren’t necessary to uniquely identify a specific transaction anymore. Furthermore, the referenceId becomes obsolete due to the nature of resource oriented approach the new API takes - by adding different resources inside each other they automatically get tied together. For instance, if you perform an authorize (formerly reservation PA) on a credit card resource you can then easily perform a charge (formerly capture CP) by simply using the payments resource ID.

Transaction group

If you wanted to distinguish between a test and live system, you had to specify that by setting the appropriate parameter for the TRANSACTION.MODE, for instance you could set it to LIVE.

With the new API it’s even easier to set the transaction mode. Your key pair will either support live or test transactions. By either putting p- (for production) or s- (for sandbox) as a prefix for both the public and the private key, you can decide the transaction mode to be used.

Here’s a quick example of a sandbox key pair: Sandbox public key: s-pub-xxxxxxxxxx Sandbox private key: s-priv-xxxxxxxxxx

Additionally the p- or s- keywords are available for every resource that is created, such as a payment, a payment type or a charge/authorize: Sandbox charge example: s-chg-1234 Production charge example:p-chg-1234

Payment methods

In the old API the payment methods are identified by a two-letter code whereas in the new API, the types resources is used instead of the two-letter code. The payment type not only identifies the payment option but also contains the data for the type. So, for a sepa-direct-debit, it will also contain the IBAN and BIC of the customer. We recommend to use our UI components to create types resources.

Previously, you had to specify a brand to differentiate between different payment methods and sometimes use different channels. This is now obsolete in the new API. You just need to create a types resource.

Here’s a mapping from payment code to types:

Transaction Types

The type code used to identify the specific payment activity performed on the payment method. For example, a debit (DB) on a credit card. A few other previously supported transaction types include credit (CD), reversal (RV) and reservation (PA).

The new API can support these transactions types easily and in a more readable form. Instead of concatenating different codes to create a fully valid API call, you can simply call an authorize (previously reservation) or a charge (previously debit) on a specific payment type resource (previously method code). In addition to that, all authorize and charge calls have a unique resource ID as well.

Charge resource ID example: p-chg-1

The difference in the new API is that the charge ID is only unique within a payment. The following table explains the mapping from transaction type to payment resource URLs:

Response codes updates

Previously, the codes were used for all types of things like payment methods, types, processing and risk management methods. All codes were given within the code attribute and followed by a specific scheme of alphanumerical letters and numbers.

In the new API there is no need to use or memorize different, hard to read codes. Instead, there are resources put in place to represent all necessary information in a much more accessible and readable way.

Codes vs Resources

All resource IDs across the new API are only unique in the scope of the key pair they were generated with.

They are not unique across multiple key pairs.

Method code vs payment type

The old payment platform of heidelpay supported various payment methods and identified each one by a two letter code in the form of AA. The new API supports even more payment methods and distinguishes them by the payment type resources. These resources have a unique resource ID called the typeId, which can be use do to identify or reference a specific payment method. To learn more about the various payment methods types, see the API reference.

For example, a credit card type resource ID would be similar to p-crd-wln5j3zcmjzi.

Status and reason code

The old API provided status and reason code that is now replaces with more descriptive status, reason, and additional information. The codes consisted of 2 separate numbers and were in the form of 00. They were meant to give a more specific idea about a payments status. When paired together, the status and reason code categorized the error codes.

The new API provides more information about the status or the error of a certain operation or transaction. When performing a charge or authorize you receive 3 different status flags, amongst other things: isSuccess, isPending and isError. In case of a success, there is an additional message with a general code and a short description of the operation. In case of an error, an error code and two separate message are returned: a merchant message with a description of what went wrong and a customer message that is displayed to the customer. To learn more about error codes, see Error handling.

Payment code

The payment code is simply the method and type code concatenated, therefore becoming obsolete in light of all already existing calls in the new API. Processing code

Because the processing code is created through concatenation of the method, type, status, and reason code (that are implemented in a different way in the new API) it too becomes obsolete. In the new API, you will use the URL to specify what action should be executed.

Registration

Registrations in the old API were using Unique IDs that are not available in the new API. Therefore, a mechanism was put in place in the new API to transfer existing Unique IDs to the new API.

For example, a new typeId is generated by calling the types/recurring URL with the registered UUID:

POST https://api.unzer.com/v1/types/recurring/
{
  "uuid" : "31HA07BC816EFC407D27439F30EF4312"
}

{
    "id": "s-crd-dkryrhdajigk",
    "method": "card",
    "recurring": true,
    "number": "1234 **** **** 1111",
    "brand": "VISA",
    "3ds": false,
    "cvc": "***",
    "expiryDate": "04/2025"
}

To execute the charge or authorization, you should store the typeId that is returned in the order.