- Created by PAYONE Admin, last modified by PAYONE Writer on 2022-08-03
Introduction
With the "authorization" request the payment process is initiated. According to the type of payment, specific functions are carried out.
This request is only available in the "Shop" version.
Credit card | Card data is verified Card is charged immediately |
Debit payment | Account data is verified Debit payment is carried out |
Online transfer | Account data is verified where applicable Online transfer session is initialised Amount will be charged to the account directly after payment is completed |
e-wallet | E-wallet session is initialised Amount will be charged to the account directly after payment is completed |
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 based on the returned clearing account data. Billing and delivery address need to be identical. |
PAYONE Business
The request is booked to the transaction account immediately after the successful payment. The time of payment therefore depends on the type of payment. The only exception is payment by invoice or cash on delivery – in this case the request is booked immediately independent of the payment.
The TransactionStatus informs you about the status of the requests. The TransactionStatus communicates, among other things, incoming payments when using the payment type invoice/prepayment and return debit notes or chargebacks if applicable (see Parameter for the TransactionStatus query).
Module invoicing
For invoicing via the PAYONE Platform you must submit all items that shall appear on the invoice. To do so, submit the parameters id[n], pr[n], no[n], de[n], va[n]. Start with item n=1. For all following articles use n=2, n=3, and so on. Accordingly, id[2],pr[2],no[2],de[2],va[2] are the parameters for item 2, and so on.
Attention
- If a parameter is missing, the whole item will not be considered!
- [n] starting with [1]; serially numbered; max [400]
Request "authorization" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Common Parameter | Required | Format | Short explanation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+ | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format LIST
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Specifies the total gross amount of a payment transaction. Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona. The amount must be less than or equal to the amount of the corresponding booking. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Individual parameter (per payment process) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | 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). Format Permitted Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format none a non recurring payment, i.e. a single authorization which might be captures at once or later in one or multiple charges oneclick a form of payment on which the cardholder is authenticated only on the initial transaction. Follow-up transactions are authorized without active interaction of the cardholder recurring a recurring payment, which has an a priori defined frequency and limit/threshold installment a recurring payment, which has an a priori defined frequency, limit/threshold and end date | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( PAYONE Secure Invoice ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice. Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( PAYONE Business ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
settleaccount | - | Format | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Format | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Due date (Unixtimestamp) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( BillSAFE, Klarna, module Invoicing ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Used with "clearingtype=fnc" to identify Financing type Format RPV Ratepay Open Invoice RPS Ratepay Installments RPP Ratepay Prepayment RPD Ratepay Direct Debit PYV Unzer Invoice PYS Unzer Installment PYM Unzer Monthly PYD Unzer Direct Debit KLV Klarna Checkout Invoice KLS Klarna Checkout Installment | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Merchant's invoice number Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer. Format M Postal Mail P PDF (via email) N no delivery | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Parameter it[n] specifies the item type of a shopping cart item. Format LIST Array Array elements [n] starting with [1]; serially numbered; max [400]
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Unit gross price of the item in smallest unit! e.g. cent Format NUMERIC(10) max. 19 999 999 99 Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Description of this item. Will be printed on documents to customer. Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Array Array elements [n] starting with [1]; serially numbered; max [400] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( personal data ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Value specifies business relation between merchant and customer Format b2c Indicates business to private customer b2b indicates business to business customer (company) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Samples | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | First name of customer; optional if company is used, i.e.: you may use Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Last name of customer; optional if company is used, i.e.: you may use
Format CHAR(2..50) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Company name of customer; The company name is optional if lastname is used, i.e.: you may use Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Samples | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Permitted values Samples US Samples CA | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Special Remark email validation: Max. length for email is 254 characters. Validation is set up in the following way: 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Date of birth of customer Format DATE(8), YYYYMMDD Samples 20190101 19991231 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | 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. Format LIST Permitted values ISO 639-1 (Language) 2-letter-codes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Permitted values * currently not in use | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Person specific numbers or characters, e.g. number of passport / ID card Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Customer's IP-V4-address (123.123.123.123) or IP-V6-address Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( delivery data ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Permitted values Samples US Samples CA | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format Permitted values Samples Some countries require additional information in parameter shipping_state | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( debit payment ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Bank Identifier Code to be used for payment or to be checked Format BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | 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 Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Account number (BBAN) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Sort code (BBAN) (only in DE) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bankaccountholder | o | Account holder Format CHAR(1..50) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | 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. Format 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 ( online transfer ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format LIST
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE DE: Mandatory with bankcode, bankaccount, optional with IBAN Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Account number (BBAN) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Sort code (BBAN) (only in DE) Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Issuer of Online-Bank-Transfer used for iDEAL and EPS Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Bank Identifier Code to be used for payment or to be checked Format BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "payment successful" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "faulty payment" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "Back" or "Cancel" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ip | o | Mandatory for P24 (PAC) Customer's IP-V4-address (123.123.123.123) or IP-V6-address Format | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( e-wallet ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Format PDT PPE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "payment successful" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "faulty payment" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | URL for "Back" or "Cancel" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( cash on delivery ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Shipping Provider Format LIST
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( credit card ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Primary account number of credit card Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Card type of credit card Format V Visa 4 M MasterCard A American Express 300-305,3095,36,38,39 601, 64, 65 J JCB O Maestro International *girocard is currently only viable for e-commerce-payments via Apple Pay. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Credit card expiry date YYMM Format NUMERIC(4), YYMM | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o | Format For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Cardholder of credit card. Format CHAR(1..50) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | Format internet eCommerce Transaction (SSL secured) 3dsecure 3-D Secure transaction (can be enabled alternatively in the risk settings) moto Mail or telephone order transaction | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( credit card with pseudo card number ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ | Pseudo primary account number for a credit card. Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameter ( 3-D Secure ) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o |
3-D Secure transaction ID (if the request "3dscheck" was used previous transactions), i.e.: Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | 3-D Secure authentication value Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
- | 3-D Secure e-commerce indicator Format | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o |
URL for "payment successful" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ |
URL for "faulty payment" Format Scheme | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
o |
URL for "Back" or "Cancel" Format Scheme |
Response "authorization" | |||
Common Parameter | Required | Format | Comment |
---|---|---|---|
status | + | Default | APPROVED / REDIRECT / ERROR / PENDING |
Parameter (APPROVED) | |||
+ | Format | ||
+ | Format | ||
Parameter (PENDING) | |||
+ | Format | ||
+ | Format | ||
Parameter (REDIRECT) (3-D Secure/online transfer/e-wallet) | |||
+ | Format | ||
+ | Format | ||
+ | Redirect URL → zMerchant system has to redirect customer to this URL to complete payment Format | ||
Parameter (ERROR) | |||
+ | In case of error the PAYONE Platform returns an error code for your internal usage. Format | ||
+ | In case of error the PAYONE Platform returns an error message for your internal usage. Format | ||
- | 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") Format | ||
Parameter ( credit card – if AVS has been ordered) | |||
protect_result_avs | - | A1 | AVS return value, see AVS-Returns (protect_result_avs) |
Parameter ( prepayment/invoice/cash on delivery ) | |||
clearing_bankaccountholder | + | AN..35 | Recipient bank account holder |
clearing_bankcountry | + | Default | Recipient account type/ country (e.g. DE, AT, etc.) |
clearing_bankaccount | + | AN..26 | Recipient account number |
clearing_bankcode | o | AN..11 | Recipient sort code |
clearing_bankiban | - | AN..35 | Recipient IBAN |
clearing_bankbic | - | AN..11 | Recipient BIC |
clearing_bankcity | - | AN..50 | Recipient city or bank |
clearing_bankname | - | AN..50 | Recipient bank name |
clearing_instructionnote | o | AN..200 | For KLV, KLS: A URL pointing to a PDF of the invoice (If invoice by post or by e-mail isn’t activated). The URL is valid for 30 days. |
Parameter ( direct debit ) | |||
mandate_identification | - | AN..35 | used mandate_identification for debit payment |
mandate_dateofsignature | - | N..10 | date when mandate has been created (format YYYYMMDD) |
creditor_identifier | - | AN..35 | used CID for debit payment |
creditor_name | - | AN..35 | as recorded in PAYONE Platform |
creditor_street | - | AN..35 | as recorded in PAYONE Platform |
creditor_zip | - | AN..10 | as recorded in PAYONE Platform |
creditor_city | - | AN..50 | as recorded in PAYONE Platform |
creditor_country | - | Default | Country (ISO 3166) |
creditor_email | - | AN..254 | as recorded in PAYONE Platform |
clearing_date | - | N..8 | only provided if due_time is not specified |
clearing_amount | - | N..10 | only provided if due_time is not specified |
Content
- No labels