For processing a purchase transaction in connection with session management or with initiating a subscription.
This request is only available with the version "Access".
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.
POST Request - Createaccess
| 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
|
| 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) deprecated, should not be used. Please use “period_unit_trail”, “period_length_trail” instead. |
||||||||||
| 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
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
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. |
| 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
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
Credits will be booked on the most recent payment process. |
| invoice_deliverymode optional
|
Format LIST
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) |
| 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
Specifies state / region of country for the customer. |
||||||
| 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 "@" 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 |
| 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. |
| 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. |
| 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
|
| 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
*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. |
| xid required
|
Format CHAR(1..60)
3-D Secure transaction ID (if the request "3dscheck" was used previous transactions), i.e.:
|
| 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}
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) 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) URL for "Back" or "Cancel" |
| status |
Permitted Values
>APPROVED
PENDING REDIRECT ERROR |
| 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 |
| 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 |
| 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 |
| 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