With the "authorization" request the payment process is initiated. According to the type of payment, specific functions are carried out.
This option is only available in the "Shop" option.
Initialing an authorization with the different payment types causes the following actions:
|
Credit card |
Credit card data is verified and stored. |
|---|---|
|
Debit payment |
Account data is verified. |
|
Online Bank Transfer |
Account data is verified |
|
e-wallet |
E-wallet session is initialised |
|
Prepayment |
Not supported by this request!
|
|
Invoice |
Payment process is initialised |
|
Cash on delivery |
Payment process is initialised |
|
Financing |
For payment type BillSAFE and Klarna it is mandatory to create an invoice after positive acknowledge of this request |
POST Request - authorization
| request
required
|
Fixed Value: preauthorisation
|
| mid
required
|
your merchant ID, 5-digit numeric
|
| aid
required
|
your subaccount ID, 5-digit numeric
|
| portalId
required
|
your Portal ID, 7-digit numeric
|
| key
required
|
your key value, alpha-numeric
|
| clearingtype
required
|
Fixed Value elv/cc/rec/cod/vpr/sb/wlt/fnc/csh
cod/vor/sb/wlt/fnc/csh are not allowed for vauthorization, createaccess, updateaccess
Direct Debit: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. Please use request “updateuser” to update customers address data. This means that the whole address for bank transfers needs to be provided.
|
||||||||||
| clearingsubtype optional
|
Fixed Value POV
Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice. |
||||||||||
| mode
required
|
Fixed Value test/live
Can be either test environment (test) or live environment (live) |
||||||||||
| reference
optional
|
Format CHAR(2..255)
A unique ID that will be displayed in your shop backend and for the customer |
||||||||||
| amount
optional
|
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
optional
|
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR USD GBP |
||||||||||
| param optional
|
Format CHAR(1..255)
Individual parameter (per payment process) |
||||||||||
| transaction_param optional
|
Format CHAR(1..50)
Permitted Symbols [0-9][A-Z][a-z][.-_/]
Optional parameter for merchant information (per payment request) |
||||||||||
| narrative_text optional
|
Format CHAR(1..81)
Dynamic text element on account statements. (3 lines with 27 characters each) and credit card statements. |
||||||||||
| 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). |
||||||||||
| recurrence optional
|
Format LIST
Indicates recurring payments. Currently only supported for PayPal and Credit Card. |
| settleaccount
optional
|
Format LIST
Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund. cod/vor/sb/wlt/fnc/csh are not allowed for vauthorization, createaccess, updateaccess
Direct Debit: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. Please use request “updateuser” to update customers address data. This means that the whole address for bank transfers needs to be provided.
|
||||||||||
| document_date optional
|
Document date, Format: DATE(8), YYYYMMDD
|
||||||||||
| booking_date optional
|
Document date, Format: DATE(8), YYYYMMDD
|
||||||||||
| due_time optional
|
Document date, Format: DATE(8), YYYYMMDD
|
||||||||||
| invoiceid
optional
|
Format: CHAR(1..20)
Merchant's invoice number |
||||||||||
| invoice_ optional
|
Format LIST
Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer. A unique ID that will be displayed in your shop backend and for the customer |
||||||||||
| invoice_ optional
|
Format: DATE(8), YYYYMMDD
Delivery date (YYYYMMDD). |
||||||||||
| invoice_ optional
|
Format: DATE(8), YYYYMMDD
Delivery end date (YYYYMMDD). |
||||||||||
| param optional
|
Format CHAR(1..255)
Dynamic text on the invoice |
||||||||||
| transaction_ optional
|
Format CHAR(1..50)
Permitted Symbols [0-9][A-Z][a-z][.-_/]
Optional parameter for merchant information (per payment request) |
||||||||||
| narrative_text optional
|
Format CHAR(1..81)
Dynamic text element on account statements. (3 lines with 27 characters each) and credit card statements. |
||||||||||
| customer_ 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). |
||||||||||
| recurrence optional
|
Format LIST
Indicates recurring payments. Currently only supported for PayPal and Credit Card. |
| 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" |
||||||
| businessrelation optional
|
Format LIST
Value specifies business relation between merchant and customer. |
||||||
| 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
optional
|
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. |
||||||
| gender optional
|
Format LIST
Permitted values: f / m / d
Gender of customer (female / male / diverse* ) * currently not in use |
||||||
| 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 |
||||||
| ip optional
|
Format CHAR(1..39)
Customer's IP-V4-address (123.123.123.123) or IP-V6-address |
| 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 delivery address |
||||||
| shipping_street optional
|
Format CHAR(2..50)
Street number and name of delivery address |
||||||
| shipping_zip optional
|
Format CHAR(2..50)
Postcode of delivery address |
||||||
| shipping_city optional
|
Format CHAR(2..50)
City of delivery address |
||||||
| shipping_ optional
|
Format CHAR(1..50)
Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier". |
||||||
| shipping_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" |
||||||
| shipping_state optional
|
Format LIST
Permitted values ISO 3166-2 States (regions)
2-letter-codes
Specifies state / region of country for the customer. |
| 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}
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}
URL for "Back" or "Cancel" |
| it[n] optional
|
Required for physical goods in order to ensure PayPal seller protection.
|
||||||||||
| id[n] optional
|
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]Permitted Symbols [0-9][a-z][A-Z], .,-,_,/
Required for physical goods in order to ensure PayPal seller protection International Article Number (EAN bzw. GTIN) Product number, SKU, etc. of this item. |
||||||||||
| pr[n] optional
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Required for physical goods in order to ensure PayPal seller protection Unit gross price of the item in smallest unit! e.g. cent. |
||||||||||
| no[n] optional
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400] Required for physical goods in order to ensure PayPal seller protection Quantity of this item. |
||||||||||
| de[n] optional
|
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400] Required for physical goods in order to ensure PayPal seller protection Description of this item. Will be printed on documents to customer. |
||||||||||
| va[n] optional
|
Format NUMERIC(4)
VAT rate (% or bp) Array elements [n] starting with [1]; serially numbered; max [400] |
||||||||||
| sd[n] optional
|
Format: DATE(8), YYYYMMDD
Delivery date, Array elements [n] starting with [1]; serially numbered; max [400] |
||||||||||
| ed[n] optional
|
Format: DATE(8), YYYYMMDD
Delivery period end date, Array elements [n] starting with [1]; serially numbered; max [400] |
| onlinebank optional
|
Format LIST
|
|||||||||||||||||||||||||||||||||||||||
| bankgrouptype optional
|
Format LIST
Issuer of Online-Bank-Transfer used for iDEAL and EPS |
|||||||||||||||||||||||||||||||||||||||
| 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 |
|||||||||||||||||||||||||||||||||||||||
| 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_ 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
|
| wallettype required
|
Format LIST
Used with "clearingtype=wlt" to identify wallet payment types |
| shippingprovider optional
|
Format LIST
Fixed Value DHL
Only mandatory for cash on delivery |
| cardpan optional
|
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 optional
|
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 optional
|
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. |
||||||||||||||||||||||||||||||
| ecommercemode optional
|
Format LIST
Specifies how the payment transaction should be processed - if not default. |
||||||||||||||||||||||||||||||
| pseudocardpan optional
|
Format NUMERIC(16..19)
Pseudo primary account number for a credit card. |
| xid optional
|
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 |
| 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) 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" |
| financingtype optional
|
Format LIST
Used with "clearingtype=fnc" to identify Financing type
|
||||||||||||||||||||||||||||||||||||||
| workorderid optional
|
Format CHAR(1..50)
The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request. |
| status |
Permitted Values : APPROVED
PENDING REDIRECT ERROR |
| txid |
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
Format NUMERIC(6..12)
PAYONE User ID, defined by PAYONE |
| protect_result_avs |
Format A1
AVS return value, see AVS-Returns (protect_result_avs) |
| clearing_bankaccountholder |
Format AN..35
Recipient bank account holder |
| clearing_bankcountry |
Recipient account type/ country (e.g. DE, AT, etc.) |
| clearing_bankaccount |
Format AN..26
Recipient account number |
| clearing_bankcode |
Format AN..11
Recipient sort code |
| clearing_bankiban |
Format AN..35
Recipient IBAN |
| clearing_bankbic |
Format AN..11
Recipient BIC |
| clearing_bankcity |
Format AN..50
Recipient city or bank |
| clearing_bankname |
Format AN..50
Recipient bank name |
| mandate_identification |
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. PPS (PAYONE Payment Service): This parameter must not be used! For PPS the PAYONE platform defines the mandate_identification If the mandate_identification is not set PAYONE will create an unique mandate identification
(pattern: PO-nnnnnnnnnn). |
| mandate_dateofsignature |
Format N..10
Date when mandate has been created (format YYYYMMDD) |
| creditor_identifier |
Format AN..35
Used CID for debit payment |
| creditor_name |
Format AN..35
As recorded in PAYONE Platform. |
| creditor_street |
Format AN..35
As recorded in PAYONE Platform. |
| creditor_zip |
Format AN..10
As recorded in PAYONE Platform. |
| creditor_city |
Format AN..50
As recorded in PAYONE Platform. |
| creditor_country |
Format AN..50
As recorded in PAYONE Platform. |
| creditor_email |
Format AN..254
As recorded in PAYONE Platform. |
| txid |
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
Format NUMERIC(6..12)
PAYONE User ID, defined by PAYONE |
| txid |
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
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=52078
amount=3499
cardholder=max testerei
city=Dresden
clearingtype=cc
country=DE
currency=EUR
customer_is_present=yes
de[1]=Hauptartikel mit Eigenschaften XL
de[2]=Hauptartikel mit Kennzeichnung
de[3]=Standard Versand
email=test@payone.com
encoding=UTF-8
errorurl=https://yourdomain.dev/mopt_payment_payone/failure/appendSession/
firstname=Maximillian
gender=m
id[1]=SW10007.3
id[2]=SW10006
id[3]=ship9
ip=172.19.0.34
it[1]=goods
it[2]=goods
it[3]=shipment
key=17031f73e2c6f9755788bddfff04169b
language=de
lastname=Testerei
mid=14648
mode=test
no[1]=1
no[2]=1
no[3]=1
param=session-1|n2ikm4l9ifpds5p1efv6dede76|f8222c6f3c6999ce98f5198078522be4
portalid=2037267
pr[1]=1999
pr[2]=1500
pr[3]=0
pseudocardpan=9410010000167640853
recurrence=oneclick
reference=1234000243
request=authorization
salutation=Herr
shipping_city=Dresden
shipping_country=DE
shipping_firstname=Maximillian
shipping_lastname=Testerei
shipping_street=Wegeweg 25
shipping_zip=01099
street=Wegeweg 25
successurl=https://yourdomain.dev/mopt_payment_payone/success/swPaymentToken/WQXEBlwaY9jx9lZFQyxocKc5Cj86rsU3/appendSession/
telephonenumber=01752345678
va[1]=1900
va[2]=1900
va[3]=0
zip=01099
RESPONSE
status=APPROVED
txid=987654321
userid=123456789