Payment transaction

User group

The user group 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 keypair. In other words: A keypair contains all necessary information and configuration for a specific merchant and is tied to said merchant.

Identification group

The identification group consisted of all IDs used for identification of a transaction. Beside the unique and short ID, the others (namely the 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 all of that functionality and makes it easy for you to use it. Although unique 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 putting 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 chargen (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 keypair will either support live or test transactions. By either putting p- (for production) or s- (for sandbox) in front of both the public and the private key, you determine the transaction mode to be used.

Here’s a quick example of a sandbox keypair:

Sandbox public key: s-pub-xxxxxxxxxx
Sandbox private key: s-priv-xxxxxxxxxx

Additionally the p- or s- keywords are visible in every created resource, such as a payment, a payment typeor 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. Within the new API we use types resources instead of the two letter code. The payment type not only identifies the payment option but also contains the data for the type. So in case of a sepa-direct-debit it will contain also the IBAN and BIC of the customer. We recommend to use our Javascript UI components to create types resources.

In the past you also had to specify a brand to differentiate between different payment methods. Sometimes you also had to use different channels. This is all obsolete in the new API. You just need to create a types resource.

Here’s a mapping from payment code to types:

Payment type Payment code / Brand Types
Credit Card CC https://api.unzer.com/v1/types/card
Debit Card DC https://api.unzer.com/v1/types/card
Direct Debit DD https://api.unzer.com/v1/types/sepa-direct-debit

https://api.unzer.com/v1/types/sepa-direct-debit-secured
Invoice IV https://api.unzer.com/v1/types/invoice

https://api.unzer.com/v1/types/invoice-secured
Unzer Prepayment PP https://api.unzer.com/v1/types/prepayment
Online Transfer OT / SOFORT
OT / EPS
OT / GIROPAY
OT / IDEAL
OT / PRZELEWY24
https://api.unzer.com/v1/types/sofort
https://api.unzer.com/v1/types/eps
https://api.unzer.com/v1/types/giropay
https://api.unzer.com/v1/types/ideal
https://api.unzer.com/v1/types/przelewy24
Paypal VA https://api.unzer.com/v1/types/paypal

Transaction Types

The type code used to identify the specific payment activity performed on the payment method. For instance 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 is capable of all of that as well, but in a much easier and more readable way. 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 unqiue within a payment. The following table explains the mapping from transaction type to payment resource URL’s:

Transaction type Old API Code Payment resource URL
Reservation PA https://api.unzer.com/v1/payments/authorize
Debit DB https://api.unzer.com/v1/payments/charges
Capture CP https://api.unzer.com/v1/payments/{id}/charges
Reversal RV https://api.unzer.com/v1/payments/{id}/charges
Refund RF https://api.unzer.com/v1/payments/{id}/charges/{chargeId}/cancels
Registration RG https://api.unzer.com/v1/types/{type}