Overview

Introduction

This migration guide aims to give you a basic understanding of the new Unzer payment platform and to show you all differences between the old and the new API. With that, we want to ensure a smooth, quick and easy transition to the new system.

If you’re familiar with the old API, this guide will show you all the necessary changes and information you might need in order to successfully integrate the new API. Furthermore it will try to answer a few questions you might have, such as:

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

Overview

Here’s a quick overview of the chapters covered in the guide:

Key differences

Request vs Resource

People that have worked with Unzer’s old API know, that the whole implementation was based on a very simple yet reliable request-response approach. An API call was formulated, all the necessary parameters put into it and it was then sent to the server. After that, the server either sends a success or an error message back.

The new API however takes a slightly different approach. Instead of sending one request after another and waiting for a response you create resources and send them via REST. This is much easier and comprehensible than formulating a whole API call every single time. You will then link the resources to each other and reference them within the next calls. Another big advantage of that 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. Below is a list of resources and mappings to existing functionality and terminology:

Existing functionality Resource URL Description
Account https://api.unzer.com/v1/types/ Payment code and Account data
Payment https://api.unzer.com/v1/payments/charges
https://api.unzer.com/v1/payments/authorize
Payment data like amount, currency, order id
Customer https://api.unzer.com/v1/customers Customer and Address data
Analysis / Criterion https://api.unzer.com/v1/metadata Metadata

Unique and short IDs

In the previous implementation there were so 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 non 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, there is the payment resource.

Like every other resource in the new API, the payment resource has a unique resource-ID tied to it. Inside that resource you can find the payment state, the payment amount and all transactions related to that specific payment. You can find all the necessary information about payments in the documentation and in the API explorer.

Here’s a a quick example of a unique payment resource-ID:

Payment resource-ID example: p-pay-1234
Resource IDs
Note: All resource IDs across the new API are only unique in the scope of the keypair they were generated with!
They are not unique across multiple keypairs.

Security

In the old API, credentials were passed using the senderId, login and password. Additionally the channel was mandatory to identify the payment transaction. All of these parameters are 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 id’s within different payments. Only in conjunction with the url like https://api.unzer.com/v1/payments/p-pay-1/charges/p-chg-1 it gets clear 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.unzer.com/v1/payments/charges

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