Page tree
Skip to end of metadata
Go to start of metadata

Explanation

This document is an additional specification and refers to the API documentation of the PAYONE platform and describes the parameters and requests within the PAYONE platform to support Paypal Installment.

Merchant Configuration

If the connector should receive IPN notifies which include mutated vowel than the merchant needs to set this up in his paypal account:

Language -> other Options -> Encoding -> UTF-8

Genericpayment – create payment

Request

Common Parameter

Required

Comment

clearingtype

+

Fixed value: "fnc": Financing

financingtype

+

Fixed value "PPI": Paypal Installment

add_paydata[action]

+

add_paydata[action]


installment_reservationFor Reservation Requests (later capture / order & delivery)
installment_saleFor Sale Requests

amount

+

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

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

country

+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

street

+

Street number and name

Format

CHAR(1..50)

city

+

City of customer

Format

CHAR(2..50)

zip

+

Postcode

Format

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

email

+

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

firstname

+

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

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

Format

CHAR(1..50)

lastname

+

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

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

Format

CHAR(2..50)

birthday

-

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

id[n]

+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

de[n]

+

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

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[400]=Product 400

no[n]

+

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

pr[n]

+

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]

va[n]

-

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

shipping_country

-

Specifies country of delivery address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state

shipping_street

-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_city

-

City of delivery address

Format

CHAR(2..50)

shipping_zip

-

Postcode of delivery address

Format

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

shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

-

Surname of delivery address

Format

CHAR(1..50)

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

add_paydata[experience_profile_id]

-

If you configured a experience_profile at paypal, you can submit the id. 
This id has higher priority than the configured checkout parameters.

successurl

+

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

cancelurl

+

URL "Back" or "Cancel"

errorurl

+

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

Response


Parameter

Required

Comment

workorderid

+

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.

Format

CHAR(1..50)

redirecturl

+

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Format

CHAR(2..2000)

Example Request

aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
amount=6300
request=genericpayment
clearingtype=fnc
financingtype=PPI
add_paydata[action]=installment_sale
currency=EUR
country=DE
street=Any street 1
city=Yourtown
zip=12345
email=installment@myemail.com
firstname=Ina
lastname=Stallment
birthday=19981030
it[1]=1
de[1]=firstproduct
pr[1]=6300
no[1]=1
va[1]=1900
shipping_country=DE
shipping_street=Any street 1
shipping_city=Yourtown
shipping_zip=12345
shipping_firstname=Ina
shipping_lastname=Stallment
narrative_text=Thanks for your order at www.myshop.com!
add_paydata[experience_profile_id]=12
successurl=http://www.myshop.com/success
cancelurl=http://www.myshop.com/cancel
errorurl=http://www.myshop.com/error

Example Response

status=OK
workorderid=WORKORDERID12345
redirecturl=http://redirecturl.com/paypal_installment/

Genericpayment – get payment

Request

Common Parameter

Required

Comment

clearingtype

+

fixed value "fnc": Financing

financingtype

+

fixed value "PPI": Paypal Installment

workorderid

+

Reference ID to the generic request. Needs to be the workorderid, responded by create_payment request.

add_paydata[action]

+

For “get_payment” requests this has to be: get_payment

Response

Common Parameter

Required

Comments

status

+

SUCCESS  / ERROR

workorderid

+

Reference ID to the generic Request.

add_paydata[monthly_payment_value]

-

Amount of monthly payment

add_paydata[monthly_payment_currency]

-

Currency of monthly payment

add_paydata[total_cost_value]

-

Amount of complete order

add_paydata[total_cost_currency]

-

Currency of complete order

add_paydata[total_interest_value]

-

Amount of interest of complete order

add_paydata[total_interest_currency]

-

Currency of interest

add_paydata[term]

-

Number of monthly payments

add_paydata[payer_id]

-

Identification of paypal user

Example Request

add_paydata[action]=get_payment
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test
request=genericpayment
clearingtype=fnc
financingtype=PPI
workorderid=WORKORDERID12345
add_paydata[action]=get_payment
 
Example response:
status=OK
workorderid=WORKORDERID12345
add_paydata[monthly_payment_value]=2100
add_paydata[monthly_payment_currency]=EUR
add_paydata[total_cost_value]=6300
add_paydata[total_cost_currency]=EUR
add_paydata[total_interest_value]=450
add_paydata[total_interest_currency]=EUR
add_paydata[term]=3
add_paydata[payer_id]=14f435fgr

Preauthorization/Authorization

Request

Parameter

Required

Comment

clearingtype

+

Fixed value "fnc": Financing

financingtype

+

Fixed value "PPI": Paypal Installment

amount

+

Needs to be same amount as in create payment request. Will be validated.

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

workorderid

+

Needs to be workorderid from create payment request

capturemode

+

Needs to be “completed”. There is no partial capture.

Response

Parameter

Required

Comment

status

+

APPROVED / PENDING / ERROR

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)


Example Request

aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
request=authorization
amount=6300
mode=test
clearingtype=fnc
financingtype=PPI
currency=EUR
country=DE
street=Any street 1
city=Yourtown
zip=12345
email=installer@myemail.com
firstname=Ina
lastname=Stallment
birthday=19981030
it[1]=1
de[1]=firstproduct
pr[1]=6300
no[1]=1
va[1]=1900
shipping_country=DE
shipping_street=Any street 1
shipping_city=Yourtown
shipping_zip=12345
shipping_firstname=Ina
shipping_lastname=Stallment
narrative_text=Thanks for your order at www.myshop.com!

Example Response

status=APPROVED
txid=12345678
userid=789654

Sequence Diagrams

Sale Installment

Order & Delivery Installment

  • No labels