Payolution

Payolution

Payolution (part of Unzer) offers invoice payments for the Austrian, German, and Swiss online markets. The currency used has to be EUR.

The consumer must be older than 18 years of age, the billing address and the delivery address must be the same and the order amount must not be below or exceed the limits as contractually agreed with payolution. The delivery country must be accepted by payolution. Gift vouchers must be excluded and may not be purchased via invoice or installment.

The title of this payment method to be displayed in the shop may be freely chosen during shop plugin configuration. Since payolution is a white-label product it’s recommended to choose a neutral title such as "invoice".

Payolution will communicate the required live data to merchants only after the final tests of the integration were successfully completed and the entire installation was found adequate.

Commands

Pre Transaction Commands

The first step is to generate a unique order number with the command CREATEORDER.

Transaction Commands

INITIATEPAYMENT

Request Parameters
Table 1. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

INITTYPE

ORDERREFERENCE

PAYMENTTYPE

CUSTOMERSTATEMENT

AMOUNT

CONSUMER_BIRTH_DATE

CURRENCY

CONSUMER_BILLING_PHONE

ORDERNUMBER

COMPANY_NAME

ORDERDESCRIPTION

COMPANY_VAT_ID

CONSUMER_EMAIL

COMPANY_TRADE_REGISTRY_NUMBER

CONSUMER_BILLING_FIRST_NAME

COMPANY_REGISTER_KEY

CONSUMER_BILLING_LAST_NAME

CONSUMER_MERCHANT_CRM_ID

CONSUMER_BILLING_ADDRESS_1

APPLICATIONTYPE

CONSUMER_BILLING_CITY

ORIGINATOR

CONSUMER_BILLING_ZIP_CODE

Payolution recommends sending consumer shipping data in addition.

CONSUMER_BILLING_COUNTRY

If the parameter COMPANY_NAME is used, the parameter CONSUMER_BIRTH_DATE is not required anymore.

CONSUMER_IP_ADDRESS

Table 2. Request Parameters
Required Parameters

MERCHANTKEY

COMMAND

INITTYPE

PAYMENTTYPE

AMOUNT

CURRENCY

ORDERNUMBER

ORDERDESCRIPTION

CONSUMER_EMAIL

CONSUMER_BILLING_FIRST_NAME

CONSUMER_BILLING_LAST_NAME

CONSUMER_BILLING_ADDRESS_1

CONSUMER_BILLING_CITY

CONSUMER_BILLING_ZIP_CODE

CONSUMER_BILLING_COUNTRY

CONSUMER_IP_ADDRESS

Optional Parameters

LOGPATH

LANGUAGE

ORDERREFERENCE

CUSTOMERSTATEMENT

CONSUMER_BIRTH_DATE

CONSUMER_BILLING_PHONE

COMPANY_NAME

COMPANY_VAT_ID

COMPANY_TRADE_REGISTRY_NUMBER

COMPANY_REGISTER_KEY

CONSUMER_MERCHANT_CRM_ID

APPLICATIONTYPE

ORIGINATOR

Payolution recommends sending consumer shipping data in addition.
If the parameter COMPANY_NAME is used, the parameter CONSUMER_BIRTH_DATE is not required anymore.

Optional request parameters CUSTOMERSTATEMENT and ORDERREFERENCE, are more restricted about their length and allowed characters than usual.

Response Parameters
Table 3. Response Parameters
Required Parameters Optional Parameters

status

header

version

body

errorCode

message

paySysMessage

originator

Additional Response Parameters

Table 4. Additional Response Parameters
Parameter State Data type Descritpion

gatewayReferenceNumber

Success

Alphanumeric with special characters, up to 255.

Technical reference number of the payment processing at QENTA.

providerReferenceNumber

Success

Alphanumeric with special characters, up to 255.

Reference number of the invoice.

Table 5. Additional Response Parameters
gatewayReferenceNumber

Data

Value

State

Success

Data type

Alphanumeric with special characters, up to 255.

Description

Technical reference number of the payment processing at QENTA.

providerReferenceNumber

Data

Value

State

Success

Data type

Alphanumeric with special characters, up to 255.

Description

Reference number of the invoice.

Initialization example
Payolution payment method can be initialized if the merchant sends INVOICE for parameter INITTYPE.
  1. Send a request.

    Example of Request for Initiation
    COMMAND=INITIATEPAYMENT&
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    INITTYPE=INVOICE&
    ORDERNUMBER=15588820&
    LANGUAGE=en&
    AMOUNT=1&
    CURRENCY=EUR&
    SERVICEURL=http://yourimprint.com/&
    ORDERDESCRIPTION=Test:0000&
    CONSUMER_BIRTH_DATE=2000-09-01&
    CONSUMER_EMAIL=test@qenta.com&
    CONSUMER_IP_ADDRESS=195.34.137.202&
    CONSUMER_BILLING_FIRST_NAME=Qenta&
    CONSUMER_BILLING_LAST_NAME=Tester&
    CONSUMER_BILLING_CITY=Graz&
    CONSUMER_BILLING_ZIP_CODE=8020&
    CONSUMER_BILLING_COUNTRY=AT&
    CONSUMER_BILLING_ADDRESS_1=Reininghausstraße 10&
    APPLICATIONTYPE=S&
  2. The response looks like this:

    Example of Response for Initiation
    version=qtillserver+3.23.0.47&
    status=0

VERIFYPAYMENT

Request Parameters
Table 6. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

PAYMENTNUMBER

QTILL_CLIENT_IP_ADDRESS

ORIGINATOR

Response Parameters
Table 7. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
Verifying payment example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    COMMAND=VERIFYPAYMENT&
    APPLICATIONTYPE=S&
    ORDERNUMBER=8704489&
    LANGUAGE=en&
  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
    payment.1.1.paymentNumber=8704489&
    payment.1.1.depositAmount=1.00&
    order.1.orderText=Test%3A0000&
    order.1.contractNumber=72ee7187-cf31-4aae-9773-20d6bec114af&
    payment.1.1.timeModified=31.10.2022+13%3A20%3A28&
    payment.1.1.paymentType=PAYOLUTION&
    order.1.merchantNumber=840&
    payment.1.1.state=payment_deposited&
    order.1.depositAmount=1.00&
    order.1.customerStatement=Test005&
    order.1.providerContractNumber=72ee7187-cf31-4aae-9773-20d6bec114af&
    order.1.timeModified=31.10.2022+13%3A20%3A28&
    payment.1.1.providerReferenceNumber=8704489&
    order.1.orderNumber=8704489&
    payment.1.1.gatewayReferenceNumber=8704489&
    payment.1.1.orderNumber=8704489&
    payment.1.1.approveAmount=1.00&
    order.1.approveAmount=0&
    order.1.credits=0&
    payment.1.1.merchantNumber=840&
    order.1.payments=1&
    order.1.currency=EUR&
    version=qtillserver+3.23.0.48&
    order.1.refundAmount=0&
    payment.1.1.currency=EUR&
    order.1.timeCreated=31.10.2022+13%3A20%3A27&
    order.1.state=ORDERED&
    order.1.orderDescription=Test%3A0000&
    orders=1&
    payment.1.1.timeCreated=31.10.2022+13%3A20%3A28&
    payment.1.1.batchNumber=300006200&
    order.1.acquirer=payolution&
    order.1.paymentType=PAYOLUTION&
    order.1.brand=Invoice&
    status=0

Post Transaction Commands

GETORDERDETAILS

Request Parameters
Table 8. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

ADMIN_PASSWORD

ORIGINATOR

Response Parameters
Table 9. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Order as a basis type of properties in the response can be returned for this command.
Getting order details example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    COMMAND=GETORDERDETAILS&
    ORDERNUMBER=15588820&
    ADMIN_PASSWORD=9p3a0m5f&
    APPLICATIONTYPE=S&
  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
    payment.1.1.paymentNumber=15588820&
    payment.1.1.depositAmount=1.00&
    order.1.orderText=Test%3A0000&
    order.1.contractNumber=72ee7187-cf31-4aae-9773-20d6bec114af&
    payment.1.1.timeModified=31.10.2022+13%3A20%3A28&
    payment.1.1.paymentType=PAYOLUTION&
    order.1.merchantNumber=840&
    payment.1.1.state=payment_deposited&
    order.1.depositAmount=1.00&
    order.1.customerStatement=Test005&
    order.1.providerContractNumber=72ee7187-cf31-4aae-9773-20d6bec114af&
    order.1.orderNumber=15588820&
    order.1.timeModified=31.10.2022+13%3A20%3A28&
    payment.1.1.providerReferenceNumber=15588820&
    payment.1.1.gatewayReferenceNumber=15588820&
    payment.1.1.orderNumber=15588820&
    objectsTotal=1&
    payment.1.1.approveAmount=1.00&
    order.1.approveAmount=0&
    order.1.credits=0&
    payment.1.1.merchantNumber=840&
    order.1.payments=1&
    order.1.currency=EUR&
    version=qtillserver+3.23.0.48&
    order.1.state=ORDERED&
    order.1.timeCreated=31.10.2022+13%3A20%3A27&
    payment.1.1.currency=EUR&
    order.1.refundAmount=0&
    rder.1.orderDescription=Test%3A0000&
    orders=1&
    payment.1.1.timeCreated=31.10.2022+13%3A20%3A28&
    order.1.paymentType=PAYOLUTION&
    order.1.brand=Invoice&
    order.1.acquirer=payolution&
    payment.1.1.batchNumber=300006200&
    status=0

DEPOSIT

The transaction can be deposited:

  1. By using the command DEPOSIT (see an example!).

When the payment of a certain amount is authorized, some financial service providers offer a one-off deposit of less than the authorized amount. If e.g. the price of the item the consumer ordered is reduced.

Split capture is possible only for invoices and it must be enabled by payolution and by our integration specialists.
Request Parameters
Table 10. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

CURRENCY

PAYMENTNUMBER

CUSTOMERSTATEMENT

AMOUNT

MERCHANTREFERENCE

APPLICATIONTYPE

ORIGINATOR

Response Parameters
Table 11. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Deposit example
  1. Send a request.

    Request Parameters
    COMMAND=DEPOSIT&
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    ORDERNUMBER=15588820&
    PAYMENTNUMBER=15588820&
    LANGUAGE=en&
    AMOUNT=1&
    CURRENCY=EUR&
    APPLICATIONTYPE=S&
  2. The response looks like this:

    Response Parameters
    version=qtillserver+3.23.0.48&
    paymentNumber=15588820&
    status=0

APPROVEREVERSAL

For using the command APPROVEREVERSAL, payment needs to be in an approved state. Look at the order flow diagram of the payment method for closer information.
Request Parameters
Table 12. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

CURRENCY

PAYMENTNUMBER

AMOUNT

ADMIN_PASSWORD

APPLICATIONTYPE

ORIGINATOR

Response Parameters
Table 13. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

Approve Reversal example
  1. Send a request.

    Request Parameters
    COMMAND=APPROVEREVERSAL&
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    ORDERNUMBER=8704489&
    PAYMENTNUMBER=8704489&
    ADMIN_PASSWORD=9p3a0m5f&
    LANGUAGE=en&
    APPLICATIONTYPE=S
  2. The response looks like this:

    Response Parameters
    version=qtillserver+3.23.0.47&
    status=0

REFUND

Request Parameters
Table 14. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

AMOUNT

CREDITNUMBER

ADMIN_PASSWORD

CURRENCY

MERCHANTREFERENCE

CUSTOMERSTATEMENT

ISO_TRANSACTION_TYPE

ORIGINATOR

For refunds, basket item data are additional optional parameters.
Response Parameters
Table 15. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

creditNumber

Refunding example
  1. Send a request.

    Request Parameters
    MERCHANTKEY=[noTestMerchantKeyAvailable]&
    COMMAND=REFUND&
    ORDERNUMBER=15588820&
    CURRENCY=EUR&
    AMOUNT=1.00&
    ADMIN_PASSWORD=9p3a0m5f&
    APPLICATIONTYPE=S&
    LANGUAGE=en
  2. The response looks like this:

    Response Parameters
    creditNumber=14995999&
    version=qtillserver+3.23.0.48&
    status=0

Query Commands

For every payment method commands QUERYORDERS, QUERYCREDITS and QUERYBATCHES are used.

Order Flow Diagram

Image

To interpret this diagram, the successful completion of a NEW PAYMENT is assumed. Starting from this operation it’s possible to carry out different commands.

For an explanation of the different status descriptions included in this diagram have a look at GETORDERDETAILS.
All possible commands for specific acquirers are found here.