Introduction

For processing a purchase transaction in connection with session management or with initiating a subscription.

This request is only available with the version "Access".

Important notes

For the time-based settlement of goods or subscriptions you must first create offers in your merchant area.
You have the option to submit values that overwrite the settings for the offer used (e.g. price, term, etc.). These optional submitted values will be used for all following periods of this contract. The original offer is not changed.

If the time at which access is first granted is in the future or the initial term is free of charge, a reservation, which will later be cancelled automatically, is carried out. The amount for the reservation is one payment unit (e.g. 1 EUR). This procedure is simply used to verify the customer's payment data and to check the customer data using risk checks, provided that these are active. The first "real" booking will be effected at the start of the first period that requires a charge.
The periods (defined by “period_unit_trail”, “period_length_trail”, “period_unit_recurring”, “period_length_ recurring”) are limited to 60 months.

Integration

POST Request - Createaccess
Account Parameters
request
required
Fixed Value: createaccess
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 4-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype
required
Format LIST
reference
required
Format CHAR(1..20)
Permitted Symbols
[0-9][a-z][A-Z], .,-,_,/
 

Merchant reference number for the payment process (case insensitive)
productid
required
Format NUMERIC(1..7)

ID for the offer
param
optional
Format CHAR(1..255)

Individual parameter (per payment process)

This parameter is passed on to all follow-up bookings of the same contract
accessname
optional
Format CHAR(1..32)

Customer's user name
accesscode
optional
Format CHAR(1..32)

Customer's password
access_starttime
optional
Format Unixtimestamp

Access starting date as Unixtimestamp
access_expiretime
optional
Format Unixtimestamp

Can be either used with creating a new access (createaccess)
-> Set expiry date/time of the initial term as Unixtimestamp (e.g. date of first renewal)

deprecated, should not be used. Please use “period_unit_trail”, “period_length_trail” instead.
do not use with “period_unit_trail”, “period_length_trail”
or used with updating an existing access (updateaccess)
-> Update expiry date/time of the current term as Unixtimestamp (e.g. overwrite date of next renewal)
access_canceltime
optional
Format Unixtimestamp

Date of cancellation as Unixtimestamp in the future (after this date no further renewals will be carried out)
amount_trail
optional
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).
period_unit_trail
optional
Format LIST
Value Comment
Y Value “length” is in years
M Value “length” is in months
D Value “length” is in days

Time unit for initial term

Do not use with “access_expiretime”.

Do not exceed 5 years / 60 months.
period_length_trail
optional
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”
amount_recurring
optional
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_recurring
optional
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

Time unit for subsequent term

Do not exceed 5 years / 60 months.
period_length_recurring
optional
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.
Parameter (module billing)
vaccountname
required
Format CHAR(1..20)
Permitted Symbols
[0-9, a-z, A-Z, .,-,_,/]
 

ID/name of the merchant's billing account
settle_period_length
required
Format NUMERIC(1..3)

Length of the accounting period
settle_period_unit
required
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

Time unit of the accounting period
settletime
optional
Format Unixtimestamp

Date for the next invoicing Unixtimestamp in the future.
payout_open_balance
optional
Format LIST
Value Comment
yes Amount will be credited immediately (default)
no Credited amount will be offset with the subsequent transaction

Credits will be booked on the most recent payment process.
Parameter (module Invoicing)
invoice_deliverymode
optional
Format LIST
Value Comment
M Postal Mail
P PDF (via email)
N no delivery

Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.
invoiceappendix
optional
Format CHAR(1..255)

Dynamic text on the invoice
id_trail[n]
optional
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)
pr_trail[n]
optional
Format NUMERIC(8) max. 19 999 999 99

Quantity of this item (initial term)
no_trail[n]
optional
Format NUMERIC(5)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item (initial term)
de_trail[n]
optional
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

Description of this item (initial term)
va_trail[n]
optional
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]

VAT rate (% or bp) (first term)
ti_trail[n]
optional
Format CHAR(1..100)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Title (initial term)
id_recurring[n]
optional
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
Format NUMERIC(5)
Array Array elements [n] starting with [1]; serially numbered; max [400]Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

Quantity of this item (subsequent term)
pr_recurring[n]
optional
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
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

Description of this item (subsequent term)
va_recurring[n]
optional
Format NUMERIC(4)
Array Array elements [n] starting with [1]; serially numbered; max [400]

VAT rate (% or bp) (subsequent term)
ti_recurring[n]
optional
Format CHAR(1..100)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Title (subsequent term)
PERSONAL DATA Parameters
customerid
optional
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.
userid
optional
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE
salutation
optional
Format CHAR(1..10)

The customer's salutation
title
optional
Format CHAR(1..20)
Samples
Dr
Prof.
Dr.-Ing.

Title of the 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)

Last name 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)

Comany 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
Samples: DE / GB / US
Specifies country of address for the customer.
Some countries require additional information in parameter "state".
state
required (in CN)
Format LIST

Permitted values: ISO 3166-2 States (regions) 2-letter-codes

Samples US Samples CA
AK AB
AL BC

Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.
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
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.
vatid
optional
Format CHAR(1..50)

VAT identification number. Used for b2b transactions to indicate VAT number of customer.
ip
optional
Format CHAR(1..39)

Customer's IP-V4-address (123.123.123.123) or IP-V6-address
PARAMETER (debit payment)
bankcountry
optional
Format LIST
Permitted Values DE; DK; EE; ES; FI; IT; MT; NL; NO; PL; SE

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(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
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

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)

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)

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.
bankaccountholder
optional
Format CHAR(1..50)

Account holder
mandate_identification
optional
Format CHAR(1..35)

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 (credit card)
cardpan
required

Primary account number of credit card

Format NUMERIC(13..19)
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.
cardtype
required

Primary account number of credit card

Format LIST

Card type of credit card

Value Comment BIN-Range for automatic card type detection
V Visa 4
M MasterCard 51-55,2221-2720
A American Express 34, 37
D Diners / Discover

300-305,3095,36,38,39

601, 64, 65
J JCB 3528-3589
O Maestro International 50, 56-58,602, 61, 620, 627, 63, 67
P China Union Pay 62212600-62299800,624-626, 6282-6288
U UATP / Airplus 1220, 1920 -> coming soon; not available yet
G girocard 68*

*girocard is currently only viable for e-commerce-payments via Apple Pay.
cardexpiredate
required
Format NUMERIC(4), YYMM

Credit card expiry date YYMM
cardcvc2
optional
 Format NUMERIC(3..4)
For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used.
cardissuenumber
optional
Format NUMERIC(1..2)

Card issue number (only Maestro UK cards)
cardholder
optional
Format CHAR(1..50)

Cardholder of credit card.
pseudocardpan
optional
Format NUMERIC(16..19)

Pseudo primary account number for a credit card.
Parameter (3-D Secure)
xid
required
Format CHAR(1..60)
  • either "xid" (from previous 3dscheck)
  • or "successurl", "errorurl", "backurl" must be given.

3-D Secure transaction ID (if the request "3dscheck" was used previous transactions), i.e.:

  • value for "xid" is returned by request 3dscheck (optional request)
  • and then has to be used for request authorization, preauthorization or createaccess in request data
cavv
optional
Format CHAR(1..40)

3-D Secure authentication value
eci
optional
Format CHAR(1..2)

3-D Secure e-commerce indicator
customer_is_present
optional
Format LIST
Permitted Values: yes / no

Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).
successurl
optional
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}
  • either "xid" (from previous 3dscheck)
  • or "successurl", "errorurl", "backurl" must be given
  • or default "successurl" and "backurl" for a portal are configured within PMI.

URL for "payment successful"
errorurl
optional
Format CHAR(2..255)

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

- either "xid" (from previous 3dscheck)
- or "successurl", "errorurl", "backurl" must be given.
 

URL for "faulty payment"
backurl
optional
Format CHAR(2..255)

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

- either "xid" (from previous 3dscheck)
- or "successurl", "errorurl", "backurl" must be given
- or default "successurl" and "backurl" for a portal are configured within PMI.
 

URL for "Back" or "Cancel"
Response Parameters
status
Permitted Values
>APPROVED
PENDING
REDIRECT
ERROR
Response Parameter (approved)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform
userid
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE
accessid
Format NUMERIC(3..12)

Access ID, defined by PAYONE
Response Parameter (Pending)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform
userid
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE
accessid
Format NUMERIC(3..12)

Access ID, defined by PAYONE
Parameter (REDIRECT)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform
userid
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE
redirecturl
Format CHAR(2..2000)

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment
Response Parameter (Error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.
customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

 
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

aid=16442
amount_recurring=1599
amount_trail=1099
api_version=3.11
city=Kiel
clearingtype=elv
country=DE
email=jerret-jan.harms@payone.com
encoding=UTF-8
firstname=Paul
iban=DE85123456782599100003
invoiceappendix=Das ist eine Testrechnung ...
key=3adxxxxxxxxxxxxxxxxxxx1cb9e
language=de
lastname=Payer
mandate_identification=PO-TESTTEST
mid=14648
mode=test
param=c6d922426548b23ecb1346672a97b404
period_length_recurring=1
period_length_trail=1
period_unit_recurring=D
period_unit_trail=D
portalid=2035
productid=6548
reference=286419625962056
request=createaccess
street=Fraunhoferstr. 2 - 4
zip=24118
RESPONSE

status=APPROVED
txid=1062831600
userid=717750373
accessid=4634635