Introduction

PAYONE Frontend hosted-iFrame
You have a compliant solution even with using external references (e.g. images, self-hosted CSS) and customized JavaScript. The basic requirements to be eligible with SAQ A Please refer to PCI DSS Security Standards listed in SAQ A V3 on https://de.pcisecuritystandards.org are:
  • Your company accepts only card-not-present (e-commerce or mail/telephone-order) transactions;
  • All payment acceptance and processing are entirely outsourced to PCI DSS validated third-party service providers;
  • our company has no direct control of the manner in which cardholder data is captured, processed, transmitted, or stored;
  • Your company does not electronically store, process, or transmit any cardholder data on your systems or premises, but relies entirely on a third party(s) to handle all these functions;
  • Your company has confirmed that all third party(s) handling acceptance, storage, processing, and/or transmission of cardholder data are PCI DSS compliant; and
  • Your company retains only paper reports or receipts with cardholder data, and these documents are not received electronically.
  • The entirety of all payment pages delivered to the consumer's browser originates directly from a third-party PCI DSS validated service provider(s).

PAYONE provides now the PAYONE Frontend hosted iFrame for input of sensible credit card data which is fully PCI DSS 3.1 SAQ A compliant. Therefore a new URL has to be used: https://frontend.pay1.de/frontend/v2/. For security reasons the new PAYONE Frontend hosted-iFrame
  • does not populate credit card details with given data.
  • must not be used with option "autosubmit=yes" and credit card data.
  • has to be hosted on new domain and URL https://frontend.pay1.de/frontend/v2/

Migration to PAYONE Frontend hosted-iFrame

The PAYONE Frontend hosted-iFrame is configured in the same way as the existing Frontend solution. You can configure the Frontend design via PMI, payment portals, extended configuration. You will now find two tabs named "Classic Frontend (secure.pay1.de)" and "Frontend PCI DSS SAQ A (frontend.pay1.de)". For both frontend configuration the HTML header and footer can be specified and the design of the frontend can be customized. PAYONE already copied your existing frontend configuration into the configuration for PAYONE Frontend hosted-iFrame. However, the display of the PAYONE Frontend hosted-iFrame may differ from the existing Frontend as the size of an input field and an input iframe may differ. So please verify that the design of the PAYONE Frontend hosted-iFrame meets your expectations. After setup the new PAYONE Frontend hosted-iFrame you will simply have to replace the URL in your shop:

old URL to Frontend: https://secure.pay1.de/frontend/

-> HTML footer/header in PMI-Tab "Classic Frontend (secure.pay1.de)"

 new URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/

-> HTML footer/header in PMI-Tab "Frontend PCI DSS SAQ A (frontend.pay1.de)"

Important notes:
The HTML footer and header for "PAYONE Frontend" and "PAYONE Frontend hosted-iFrame" can be and have to be configured separately.
It is recommended to disable the usage of the Frontend classic once the PAYONE Frontend hosted-iFrame has been setup and tested. Otherwise it may be possible that an offender may change the new URL after calling the PAYONE Frontend hosted-iFrame to the old URL.
Feature "auto-submit" must not be used with PAYONE Frontend hosted-iFrame and credit card data.

---end

Customization of hosted-iFrames

You may customize the HTML-type and HTML-CSS for the PAYONE hosted-iFrames. Therefore you may put a script-block named "config" into your HTML Header Code within the PMI-Portal configuration in tab "Frontend PCI DSS SAQ A (frontend.pay1.de)".
This block may look like this (example):

Example
<script>
config = {
    fields:{
        cardpan: {
            type: "<span class="sp-highlight-term underline sp-cursor-pointer" style="background-color: rgb(255, 255, 255);">tel</span>",
            size: "21",
            maxlength: "21"
        },
        cardexpiremonth: {
            type: "select",
            size: "2",
            maxlength: "2"
        },
        cardexpireyear: {
            type: "select",
            size: "4",
            maxlength: "4"
        },
        cardcvc2: {
            type: "password",
            size: "4",
            maxlength: "4",
            style: "font-size: 10px; line-height: 12px; width: 60px;"
        }
    },
    defaultStyle: {
        input: " font-size: 10px; line-height: 12px; width: 220px",
        select: "font-size: 10px;",
        iframe: {
            height: "27px",
            width: "98%"
        }
    }
};
</script>

Please pay attention to separate the elements by "," – but not the last element of a list.
Please find a list of supported elements in the next chapter.

Table of Config Atributes:

These attributes and values are allowed in object "config.fields":

card-type card-pan card-cvc2 card-expire-month card-expire-year attribute value
x

 

 

 

 

cardtypes

define possible cardtypes for selection in PAYONE iFrame, e.g. ["V", "M", "A"]

 

x x x x size size of input field in characters, e.g. "20"

 

x x x x maxlength maximum length of accepted input, e.g. "20"

 

 

x

 

 

length Array of exact length of accepted input per CC-type
e.g.: length: { "A": 4, "V": 3, "M": 3, "J": 0 }

 

x x x x type define type of input field:
type Comments
"text"
tel input is visible, simple keyboard is displayed on mobile devices
"password" input is masked
"select" display selection/drop-down with possible values (only valid for month and year)
x x x x x style

CSS style properties, e.g. "font-size: 1em; border: 1px solid #000; background: white; color: red; width: 145px; height: 70px; font-family: 'Courier'; font-style: italic; font-weight: bold; text-align: center; letter-spacing: 2px;"


Remark: if "url" is used the style will be ignored as PCI DSS does not allow external ressources.

x x x x x iframe.height size
x x x x x iframe.width size, e.g.:
iframe: {
height: "25px",
width: "250px"
}

---end

These attributes and values are allowed in object "config.defaultStyle":

attribute value
input

CSS style properties for input fields, e.g. "font-size: 1em; border: 1px solid #000; width: 175px;"

select

CSS style properties for select fields, e.g. "font-size: 1em; border: 1px solid #000;"

iframe.height

size in pixel

iframe.width

size in pixel, e.g.:
iframe: {
height: "25px",
width: "250px"
}

---end

Frontend API Endpoints

Request URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/

The Endpoint  to Frontend Classic: https://secure.pay1.de/frontend/ should not be used for new implementations; existing implementations should be migrated

POST Request to PAYONE Frontend

You can create a Frontend-Page by sending a POST Request to our Frontend Endpoint with your desired parameters:

---end

Example
<form action="https://frontend.pay1.de/frontend/v2/" method=POST>
    <input type="hidden" name="portalid" value="2000000">
    <input type="hidden" name="aid" value="10000">
    <input type="hidden" name="mode" value="test">
    <input type="hidden" name="request" value="authorization">
    <input type="hidden" name="clearingtype" value="elv">
    <input type="hidden" name="reference" value="1234567">
    <input type="hidden" name="amount" value="1499">
    <input type="hidden" name="currency" value="EUR">
    <input type="hidden" name="id[1]" value="1">
    <input type="hidden" name="pr[1]" value="1499">
    <input type="hidden" name="no[1]" value="1">
    <input type="hidden" name="de[1]" value="Jurassic Park">
    <input type="hidden" name="va[1]" value="19">
    <input type="hidden" name="hash" value="70eaec2a33fa1b4674c0b112f6982966">
    <input type=submit value="Buy now!">
</form>

GET Request to PAYONE Frontend

Alternatively, you can also pass the values via URL (as GET request). The example above would look like this:

---end

Example
https://frontend.pay1.de/frontend/v2/?aid=10000&amount=1499&clearingtype=
elv&currency=EUR&de[1]=Jurassic%20Park&id[1]=
1&mode=test&no[1]=1&portalid=2000000&pr[1]=1499&reference=1234567&request=authorization&va[1]=
19&hash=70eaec2a33fa1b4674c0b112f6982966

The calculation of the hash value can be found here: FE - Calculation of the HASH value.

Billing several items using the „Shop" version: Any number of items to be billed can be transferred. If the Invoicing module has been ordered, these are listed on the invoice. "n" is the location of the item. Start with n=1. Accordingly id[2],pr[2],no[2],de[2],va[2] are the parameters of item 2 etc.
Creating a link for the payment portal „Access" version

In the „Access" version all offers (accesses or subscriptions) you want to bill have first to be created (see 2.1.2). The payment window is opened using this offer ID.

Account Here you select the account (sub-account) for which the bookings are to be listed in the statistics.
Offer Select the desired offer
 

---end

Example
<form action="https://frontend.pay1.de/frontend/v2/" method="POST">
        <input type="hidden" name="portalid" value="2000000">
        <input type="hidden" name="aid" value="10000">
        <input type="hidden" name="mode" value="test">
        <input type="hidden" name="request" value="createaccess">
        <input type="hidden" name="clearingtype" value="elv">
        <input type="hidden" name="reference" value="1234567">
        <input type="hidden" name="productid" value="1234">
        <input type="hidden" name="hash" value="70eaec2a33fa1b4674c0b112f6982966">
        <input type="submit" value="Buy now!">
</form>

Please use either:

Alternatively, you can also pass the values via URL (via GET request). The calculation of the hash value can be found here: Calculation of the HASH value.

To be SAQ A compliant PAYONE recommends implementation of the PAYONE hosted-iFrame-solution when processing the full original creditcard number (PAN).
Auto-Submit

PAYONE Platform Frontend supports the automatic triggering of a payment without the customer having to re-confirm the payment on the Frontend. This can be useful in payment methods where you already have obtained all relevant customer data (e.g. prepayment, invoice). This function also allows you to ask for the payment data already on your site and then simply transfer them to the Frontend. In this case the Frontend executes the payment automatically. If the payment was successful the customer is forwarded directly. In case of an error the customer is shown the Frontend and given the option to correct his data.

Note:

Payment data should not come into contact with your system. This is very important with credit card data. Certification according to the PCI standard is not necessary only if the card data does not come into contact with your systems. To prevent your systems from coming into contact with sensitive payment data, the payment data from your form should be sent directly to the Frontend and not be forwarded through your systems (see below). Any other data can be queried in preceding steps.

To be PCI DSS SAQ A compliant feature "autosubmit" must not be used with PAYONE Frontend and credit card payments.
To utilise this function you must use the hash method in this documentation (2.x). The hash method from the documentation of version 1.x is not permitted.

---end

Example
<form action="https://frontend.pay1.de/frontend/v2/" method="POST">
<input type="hidden" name="portalid" value="2000000">
<input type="hidden" name="aid" value="10000">
<input type="hidden" name="mode" value="test">
<input type="hidden" name="request" value="createaccess">
<input type="hidden" name="clearingtype" value="elv">
<input type="hidden" name="reference" value="1234567">
<input type="hidden" name="productid" value="1234">
<input type="hidden" name="autosubmit" value="yes">
<input type="hidden" name="hash" value="70eaec2a33fa1b4674c0b1ge5e982966">
<input type="hidden" name="bankcountry" value="DE">
<table>
<tr>
<td>Kontonummer</td><td><input type="text" name="bankaccount"></td>
</tr>
<tr>
<td>BLZ</td><td><input type="text" name="bankcode"></td>
</tr>
</table>
<input type="submit" value="Buy now!">
</form>

Please use either:
To be SAQ A compliant PAYONE recommends implementation of the PAYONE hosted-iFrame-solution when processing the full original creditcard number (PAN) as the feature "auto-submit" must not be used with credit card data.
One-Click Checkout

The PAYONE Platform supports the automatic storage of your customers' master and payment data. The PAYONE Platform Frontend can use these data to accelerate the payment process for the customer. If the customer is already known to the PAYONE Platform, it is possible for these data not having to be requested again during the payment process via the Frontend. The data are only displayed to the customer for checking. If the customer does not wish to change the data, he can complete the payment process with a single click.

To use the One-Click Checkout function you have to have it activated by the PAYONE Merchant Service. It is also technically necessary to transmit the customer ID („customerid") of your customer with every request. This is necessary for the unique identification of the customer. In addition, you must use the hash method in this documentation (2.x). The hash method from the documentation of version 1.x is not permitted.

Note:

The PAYONE Platform supports the automatic storage of your customers' master and payment data. The PAYONE Platform Frontend can use these data to accelerate the payment process for the customer. If the customer is already known to the PAYONE Platform, it is possible for these data not having to be requested again during the payment process via the Frontend. The data are only displayed to the customer for checking. If the customer does not wish to change the data, he can complete the payment process with a single click.

This method requires a certain level of security on behalf of the merchant. It must be ensured that the user is indeed the correct customer. This must be ensured using correspondingly secure login mechanisms. Otherwise it might be possible that a customer misuses the payment data of a third party.

Calculation of the HASH value

To prevent changes to the request to PAYONE, we need to incorporate a checksum of the used parameters to the PAYONE platform. For this, we use the parameter hash.

The hash value is calculated from the request parameters and a secret key using the hash function hash("md5" , $data) or hash("sha384", $data). Any parameter values to be protected are concatenated in alphabetical order. Finally, the key will be attached to the string and the hash value is calculated.

Parameters are sorted alphabetically by their name. It does not matter in which order they are used in the request URL. The parameters to be protected can be found in FE - Parameters in the request URL. They have been identified with a "+" in the hash column.

Configuring the Preferred Hash Method

You can assign the key to be used in the PMI (PAYONE Merchant Interface). Do not pass this key to third parties in any case. You can also choose the desired hash algorithm in the PMI:

You can assign the key to be used in the PMI (PAYONE Merchant Interface). Do not pass this key to third parties in any case. You can also choose the desired hash algorithm in the PMI:
PMI-Selection Meaning

md5 (current method)

PAYONE platform expects hash value as md5
(md5 is compromised and should be replaced by sha2-384)
for compatibility reason this is currently default.

md5 is considered unsafe and should not be used anymore!

sha2-384 (recommended method)

PAYONE platform expects hash value as sha2-384
(if you want to use sha2-384 hash values this option has to be activated)

md5_or_sha2-384 (during migration)

PAYONE platform accepts both hash calculations (md5 and sha2-384)
(this option should only be use for migration from md5 to sha2-384)

The PAYONE Platform expects the hash value in small letters.

Please pay attention that for "sha2-384" the portal key is not part of parameters for hash-function, but a separate parameter passed to hash-function "hash_hmac".

---end

Example 
// Important notes:
//
// * Intention of this sample is to show the concept of HASH-calculation
//   It’s not a fully valid payment request
//
// * Please add further parameters as needed:
//     clearingtype / subtype
//     mode (“live” or “test”)
//     further as needed - depending on clearingtype, subtype, ...
//
// * Please refer to the table in https://docs.payone.com/x/tIUS and add values to
//   HASH-calculation as indicated by column “Hash”
//
$request="authorization";    // Request
$portalid=2000001;           // Portal ID
$aid=10002;                  // Sub Account ID
$key="geheim";               // Key (configurable in the payment portal)

$id[1]="123-345";            // Your item no.
$pr[1]=5900;                 // Price in Cent
$no[1]=1;                    // Quantity
$de[1]="Puma Outdoor";       // Item description
$va[1]=19;                   // VAT (optional)
$amount=round($pr[1]*$no[1]);// Total amount
$currency="EUR";             // Currency
$reference="73464354";       // Merchant reference no.
$customerid="123456";        // Merchant customer ID (option)

// usage of md5-hash
// select “md5” in PMI-portal-settings
// $hash=md5($aid . $amount . $currency . $customerid .
//        $de[1] . $id[1] . $no[1] . $portalid . $pr[1] .
//        $reference . $request . $va[1] .
//        $key);  // Parameters in sorted order + key

// usage of sha2-384-hash
// select “sha2-384” in PMI-portal-settings
$hash=hash_hmac(“sha384”, $aid .
          $amount .
          $currency .
          $customerid .
          $de[1] .
          $id[1] .
          $no[1] .
          $portalid .
          $pr[1] .
          $reference .
          $request .
          $va[1], // !! Parameters in sorted order
          $key);  // !! $key is an individual parameter !

$url="https://frontend.pay1.de/frontend/v2/?request=" . $request .
          "&aid=" . $aid .
          "&portalid=" . $portalid .
          "&customerid=" . $customerid .
          "&currency=" . $currency .
          "&amount=" . $amount .
          "&reference=" . $reference .
          "&id[1]=" . $id[1] .
          "&pr[1]=" . $pr[1] .
          "&no[1]=" . $no[1] .
          "&de[1]=" . $de[1] .
          "&va[1]=" . $va[1] .
          "&hash=" . $hash;

CSS style

You can adjust the look and feel of the Frontend using templates. The template consists of an HTML header and an HTML footer. In the HTML header you must define a stylesheet (CSS) amongst other things. Ideally use the "Default CSS" and adapt it as desired.

---end

Default CSS: 
table {
padding: 0px;
border-width: 0px;
outline-width: 0px;
}
img {
border-width: 0px;
outline-width: 0px;
}
td {
font-size: 11px;
font-family: Arial, Helvetica, Geneva, SunSans-Regular
line-height: 14px;
padding-top: 2px;
padding-bottom: 2px;
}
input.long {
font-size: 10px;
line-height: 12px;
width: 98%;
border: solid 1px #999;
}
input.short {
font-size: 10px;
line-height: 12px;
width: 47%;
border: solid 1px #999;
}
input.submit {
color: #fff;
font-size: 11px;
background-color: #666;
text-transform: uppercase;
letter-spacing: 1px;
cursor: pointer;
}

input.submit[disabled]

{
color: gray;
cursor: wait;
}
form {
display: inline;
}
select.long {
font-size: 10px;
width: 100%;
}
select.short {
font-size: 10px;
width: 47%;
}
a {
color: #000;
}
a:hover {
color: #666;
}
.fullbox {
background-color: #e6e6e6;
width: 320px;
padding-right: 10px;
padding-bottom: 10px;
padding-left: 10px;
}
.headbox {
color: white;
background-color: #666;
text-transform: uppercase;
letter-spacing: 1px;
width: 100%;
height: 20px;
margin-top: 20px;
margin-bottom: 10px;
}
.formbox {
width: 100%;
}
.infobox {
width: 100%;
border-color: #666666;
border-width: 1px;
border-style: solid;
}
.footer {
width: 320px;
height: 30px;
}
.stripline {
border-top: 1px solid #999;
}
.errortext {
color: #c00;
}

Integration

Frontend API Endpoints

Request URL to PAYONE Frontend hosted-iFrame: https://frontend.pay1.de/frontend/v2/

The Endpoint  to Frontend Classic: https://secure.pay1.de/frontend/ should not be used for new implementations; existing implementations should be migrated.

Request Parameters

The UsedInHash-column defines whether the parameter value has to be included in your hash.
The parameters with a "+" must be included in the calculation of the hash value to prevent changes by the customer.

---end

Account Parameters
request
required
usedinhash
Format LIST
Request tpyes
Preauthorization
Authorization
Capture
Debit
Refund
...

---end 

mid
required
usedinhash
Format NUMERIC(5..6)
Merchant ID, defined by PAYONE
aid
required
usedinhash
Format NUMERIC(5..6)
Sub-Account ID, defined by PAYONE
portalId
required
usedinhash
Format LIST
Portal ID, defined by PAYONE
api_version
required
usedinhash
Format LIST
api_version Comment Description
3.8

Current API-version (Default if not present)

3.9

New API-version
from 2015-01-05

New response “pending” added for “preauthorization” / “authorization”

3.10

New API-version
from 2016-06-01

Response for “customermessage” can be more specific in case of error by containing detailed error messages from external payment gateways (e.g. Ratepay, …)

3.11

New API-version
from 2018-02-01

Request “capture” with response “pending”

Announcement for upcoming request “refund” / response “pending”
Announcement for upcoming request “createaccess” / response “pending”

New parameter api_version should be added to current implementations as it will be mandatory in future.

mode
required
usedinhash
Format LIST
Value Comment
live

Transaction should be performed in live mode.

test

Transaction should be simulated

Mode for transactions, either ‘live’ or ‘test’

encoding
optional
usedinhash
Format LIST
Value Comment
ISO-8859-1

Default if not specified

UTF-8

The type of character encoding used in the request.

key
required
usedinhash
your key value, alpha-numeric

---end

Common Parameters
clearingtype
required
usedinhash
Format LIST
Value Comment
elv

Debit payment

cc

Credit card

rec

Invoice

cod

Cash on delivery

vor

Prepayment

sb

Online Bank Transfer

wlt

e-wallet

fnc

Financing

csh

Cash or Hybrid Payments 

---end

reference
required
usedinhash
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]

Merchant reference number for the payment process (case insensitive)

customerid
optional
usedinhash
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]

Merchant's customer ID, defined by you / merchant to refer to the customer record. "customerid" can be used to identify a customer record.

If "customerid" is used then stored customer data are loaded automatically.

invoiceid
optional
usedinhash
Format CHAR(1..20)

Merchant's invoice number

invoice_deliverydate
optional
usedinhash
Format DATE(8), YYYYMMDD
Delivery date (YYYYMMDD)
invoice_deliveryenddate
optional
usedinhash
Format DATE(8), YYYYMMDD

Delivery end date (YYYYMMDD)

invoiceappendix
optional
usedinhash
Format CHAR(1..255)

Dynamic text on the invoice

param
optional
usedinhash
Format CHAR(1..255)

Individual parameter (per payment process)

narrative_text
optional
usedinhash
Format CHAR(1..81)

Dynamic text element on account statements
(3 lines with 27 characters each) and credit card statements.

display_name
optional
usedinhash
Format LIST
Value Comment
yes

Name will be queried (default)

no

name/company will not be queried if all necessary data were already transferred and are correct.

Specifies whether the customer name / company should be queried - instead of providing them in the Frontend request URL.

display_address
optional
usedinhash
Format LIST
Value Comment
yes

Name will be queried (default)

no

name/company will not be queried if all necessary data were already transferred and are correct

Specifies whether the customer address should be queried - instead of providing them in the Frontend request URL.

display_change_order
optional
Format LIST
Value Comment
no

Unchanged order (default)

yes

Changed order: Payment details are listed after the payment information.

Specifies whether payment details or payment information should be displayed first.

autosubmit
optional
usedinhash
Format LIST
Value Comment
no

No auto-submit (default)

yes

Payment is executed immediately without customer interaction. If the payment was successful the customer is forwarded directly to the „successurl“.

All payment data must be transmitted in this version.

Specifies whether payment details should be queried with customer interaction or with payment details provided in Frontend request URL.

successurl
required
usedinhash
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "payment successful"

backurl
required
usedinhash
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "Back" or "Cancel"

targetwindow
optional
usedinhash
Format LIST
Value1
window
opener
top
parent
blank
self

---end

Specifies target window for Frontend form.

hash
required
Format CHAR(1..96) lowercase
Permitted Symbols [0-9,a-z]
   
The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount).
MD5 hash code SHA2-384 hash code.

---end

path Parameters
amount
required
usedinhash
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
usedinhash

Format LIST

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples
EUR
USD
GBP


Specifies currency for this transaction

it[n]
required
usedinhash
Format LIST
Array Array elements [n] starting with [1]; serially numbered; max [400]
it[n] Comments
goods

Goods

shipment

Shipping charges
 

Parameter it[n] specifies the item type of a shopping cart item.

id[n]
required
usedinhash
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400] Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]

Product number, SKU, etc. of this item

pr[n]
required
usedinhash
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400] 

Unit gross price of the item in smallest unit! e.g. cent

no[n]
required
usedinhash
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400] 

Quantity of this item

de[n]
required
usedinhash
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

Description of this item. Will be printed on documents to customer.

va[n]
optional
usedinhash
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400] 

VAT rate (% or bp)

---end

Parameter (createaccess)
productid
required
usedinhash
Format CHAR(1..7)
ID for the offer
accessname
optional
usedinhash
Format CHAR(1..32)

Customer's user name

accesscode
optional
usedinhash
Format CHAR(1..32)

Customer's password

frontend_description
optional
usedinhash
Format CHAR(1..10000)

Confirmation text for the end customer after creating access. The transfer of HTML elements is permitted. At 10,000 characters this parameter is truncated.

amount_trail
optional
usedinhash
Format NUMERIC(1..8), max. value 999 999 99

Total gross amount for initial term

Must equal the sum (quantity x price) of all items for the initial term.

Required when item is submitted.

Amount can be "0" (e.g. for test period).

amount_recurring
optional
usedinhash
Format NUMERIC(1..8), max. value 999 999 99
Total gross amount of all items of one period during the subsequent term

Must equal the sum (quantity x price) of all items during the subsequent term.

Required when item is submitted.

Amount must not be "0".

period_unit_trail
optional
usedinhash
Format LIST
Value Comment
Y

Value “length” is in years

M

Value “length” is in months

D

Value “length” is in days

---end

Time unit for initial term

Do not use with “access_expiretime”.

Do not exceed 5 years / 60 months.

period_length_trail
optional
usedinhash
Format NUMERIC(1..4)

Duration of the initial term. Can only be used in combination with period_unit_trail.

Required when period_unit_trail is submitted.

Do not use with “access_expiretime”

period_unit_recurring
optional
usedinhash
Format LIST
Value Comment
Y

Value “length” is in years

M

Value “length” is in months

D

Value “length” is in days

N

No subsequent term given

---end

Time unit for subsequent term

Do not exceed 5 years / 60 months.

period_length_recurring
optional
usedinhash
Format NUMERIC(1..4)

Duration of the subsequent term. Can only be used in combination with period_unit_recurring.

Required when period_length_recurring is submitted.

id_trail[n]
required
usedinhash
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Product number, order number, etc. of this item (initial term)
no_trail[n]
required
usedinhash
Format NUMERIC(8) max. 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]

Quantity of this item (initial term)
pr_trail[n]
required
usedinhash
Format NUMERIC(8) max. 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item (initial term) in smallest unit.
de_trail[n]
required
usedinhash
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100
Description of this item (initial term)
ti_trail[n]
required
usedinhash
Format CHAR(1..100)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Title (initial term)
va_trail[n]
required
usedinhash
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) (first term)
id_recurring[n]
optional
usedinhash
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]
Product number, order number, etc. of this item (subsequent term)
no_recurring[n]
optional
usedinhash
Format NUMERIC(5)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item (subsequent term)
pr_recurring[n]
optional
usedinhash
Format NUMERIC(8) max. 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item (subsequent term) in smallest unit.
de_recurring[n]
optional
usedinhash
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100
Description of this item (subsequent term)
ti_recurring[n]
optional
usedinhash
Format CHAR(1..100)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Title (subsequent term)
va_recurring[n]
optional
usedinhash
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]
VAT rate (% or bp) (subsequent term)

---end

Parameter (personal data)
businessrelation
optional
Format LIST
Value Comment
b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

Value specifies business relation between merchant and customer

firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

lastname
optional
Format CHAR(2..50)

Lastname of customer; optional if company is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Campany name of customer; optional if company is used, i.e.: you may use

"company"
or "lastname"
or "firstname" plus "lastname"

street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)

addressaddition
optional
Format CHAR(1..50)
Samples
7th floor
c/o Maier

Specifies an additional address line for the invoice address of the customer.

zip
optional
Format CHAR(2..50)
Permitted Symbols[0-9][A-Z][a-z][_.-/ ]

Postcode

city
optional
Format CHAR(2..50)

City of customer.

country
optional
Format LIST
Permitted values ISO 3166 2-letter-codes

Specifies country of address for the customer

telephonenumber
optional
Format CHAR(1..30)

Phone number of customer

birthday
optional
Format DATE(8), YYYYMMDD
Samples
20190101
19991231

Date of birth of customer

language
optional
Format LIST
Permitted values ISO 639-1 (Language)2-letter-codes

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

gender
optional
Format LIST
Permitted values f, m, d

Gender of customer (female / male / diverse* )

email
optional
Format CHAR(5..254)
Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters
Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters 
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]


"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.
 

email-address of customer

personalid
optional
Format CHAR(1..32)
Permitted Symbols [0-9][A-Z][a-z][+-./()]

Person specific numbers or characters, e.g. number of passport / ID card

---end

Parameter (delivery data)
shipping_firstname
optional
Format CHAR(1..50)

First name of delivery address

shipping_lastname
optional
Format CHAR(1..50)

Surname of delivery address

shipping_company
optional
Format CHAR(2..50)

Company Name of the delivery address

shipping_street
optional
Format CHAR(2..50)

Street number and name of delivery address

shipping_zip
optional
Format CHAR(2..10)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode of delivery address

shipping_city
optional
Format CHAR(2..50)

City of delivery address

shipping_country
optional
Format LIST
Permitted values ISO 3166 2-letter-codes

Specifies country of delivery address for the customer

---end

Parameter („autosubmit“ - credit card)
cardholder
optional
Format CHAR(1..50)

Cardholder of credit card.

cardpan
required
Format NUMERIC(13..19)

Primary account number of credit card

If your system handles "cardpan" directly you can not be PCI DSS SAQ A compliant. 
For simple PCI DSS SAQ A compliance please use PAYONE hosted iFrames together with pseudocardpan.

---end

cardtype
required
Format LIST

Card type of credit card

cardexpireyear
required
Format NUMERIC(4), YYYY

Credit card expiry year YYYY

cardexpiremonth
required
Format NUMERIC(2), MM

Credit card expiry month MM

cardcvc2
optional
Format NUMERIC(3..4)

Credit card security number

For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used. 

---end

Parameter („autosubmit“ - direct debit)
iban
optional
Format CHAR(10..34)
Permitted Symbols [0-9][A-Z]

IBAN to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked
BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

bankaccountholder
optional
Format CHAR(1..50)

Account holder

bankcountry
optional
Format LIST

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

bankaccount
optional
Format NUMERIC(1..10)

Account number (BBAN)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

bankcode
optional
Format NUMERIC(8)

Sort code (BBAN) (only in DE)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

mandate_identification
optional
Format CHAR(1..35)
Permitted Symbols [A-Z,a-z,0-9,+,-,.,(,)]

A SEPA mandate can be created if a payment is initiated (amount > 0). Can be used to enforce a merchant specific mandate identification. The mandate_identification has to be unique.

If the mandate_identification is not set PAYONE will create an unique mandate identification (pattern: PO-nnnnnnnnnn).

PPS (PAYONE Payment Service): This parameter must not be used! For PPS the PAYONE platform defines the mandate_identification

Parameter („autosubmit“ - Online transfer)
onlinebanktransfertype
optional
Format LIST
Value Comment
EPS

eps – online transfer (AT)

GPY

giropay (DE)

IDL

iDEAL (NL)

P24

Przelewy24 (PL)

PFC

PostFinance Card (CH)

PFF

PostFinance E-Finance (CH)

PNT

SOFORT Überweisung

---end

bankcountry
required
Format LIST

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

iban
optional
Format CHAR(10..34)
Permitted Symbols [0-9][A-Z]

IBAN to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. 

bankaccount
optional
Format NUMERIC(1..10)

Account number (BBAN)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

bankcode
optional
Format NUMERIC(8)

Sort code (BBAN) (only in DE)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

bankgrouptype
optional
Format LIST 

Issuer of Online-Bank-Transfer used for iDEAL and EPS

---end

Parameter („autosubmit“ - e-wallet)
wallettype
required
Format LIST
Value Comment
ALP

Alipay

PDT

paydirekt

PPE

PayPal

---end

Used with "clearingtype=wlt" to identify wallet payment types

---end

Parameter („autosubmit“ - Financing)
financingtype
required
Format LIST
Value Comment
RPV

Ratepay Open Invoice

RPP

Ratepay Prepayment

RPD

Ratepay Direct Debit

---end

Used with "clearingtype=fnc" to identify Financing type

---end

Host:
Content-Type: application/x-www-form-urlencoded
Edit your payload here
key1=value1
key2=value2
key3=value3
...
Edit your response here
key1=value1
key2=value2
key3=value3
...