Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Explanation

UI Text Box
typenote

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]

+


[action]

Comment
reservationFor Reservation Requests (later capture / order & delivery)
saleFor Sale Requests


amount

+

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

country

+

Excerpt Include
country - definition
country - definition
nopaneltrue

street

+

Excerpt Include
street - definition
street - definition
nopaneltrue

city

+

Excerpt Include
city - definition
city - definition
nopaneltrue

zip

+

Excerpt Include
zip - definition
zip - definition
nopaneltrue

state-

Excerpt Include
state - definition
state - definition
nopaneltrue

email

+

Excerpt Include
email - definition
email - definition
nopaneltrue

firstname

+

Excerpt Include
firstname - definition
firstname - definition
nopaneltrue

lastname

+

Excerpt Include
lastname - definition
lastname - definition
nopaneltrue

birthday

-

Excerpt Include
birthday - definition
birthday - definition
nopaneltrue

id[n]

+

Excerpt Include
id[n] - definition
id[n] - definition
nopaneltrue

de[n]

+

Excerpt Include
de[n] - definition
de[n] - definition
nopaneltrue

no[n]

+

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

pr[n]

+

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

va[n]

-

Excerpt Include
va[n] - definition
va[n] - definition
nopaneltrue

shipping_country

-

Excerpt Include
shipping_country - definition
shipping_country - definition
nopaneltrue

shipping_street

-

Excerpt Include
shipping_street - definition
shipping_street - definition
nopaneltrue

shipping_city

-

Excerpt Include
shipping_city - definition
shipping_city - definition
nopaneltrue

shipping_zip

-

Excerpt Include
shipping_zip - definition
shipping_zip - definition
nopaneltrue

shipping_state-

Excerpt Include
shipping_state - definition
shipping_state - definition
nopaneltrue

shipping_firstname

-

Excerpt Include
shipping_firstname - definition
shipping_firstname - definition
nopaneltrue

shipping_lastname

-

Excerpt Include
shipping_lastname - definition
shipping_lastname - definition
nopaneltrue

narrative_text

-

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

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

+

Excerpt Include
successurl - definition
successurl - definition
nopaneltrue

cancelurl

+

URL "Back" or "Cancel"

errorurl

+

Excerpt Include
errorurl - definition
errorurl - definition
nopaneltrue

add_paydata[payerid]-Can be used to validate the merchant's PayerID against the PayerID reported by PayPal. Unique PayPal Customer Account identification number.
add_paydata[transactionParam]-Content will be sent to paypal as "custom"-value.
add_paydata[risk_session_correlation_id]-Used for paypals "SetTransactionContext"-Feature. Merchant needs to generate a UUID and send it to paypal with this parameter. The following values (tc_keys) will then be sent to paypal as transaction-context referencing the UUID. With this information paypal can check the fraud risk for this payment process. This is a specific feature, that the merchant needs to setup with paypal first in order to use it.
add_paydata[tc_<key>]-

Will be used for all values defined for "SetTransactionContext" between merchant and paypal.

There can be more than 1 key.

Code Block
titleExample
add_paydata[tc_ota_type] = bus
add_paydata[tc_sender_account_id] = A12345


Code Block
titleWill be sent to paypal as:
ota_type = bus
sender_account_id = A12345


Response


Parameter

Required

Comment

workorderid

+

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

redirecturl

+

Excerpt Include
redirecturl - definition
redirecturl - definition
nopaneltrue

Example Request

Code Block
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

Code Block
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.

addResponseData[payerstatus]-
addResponseData[firstname]-
addResponseData[lastname]-
addResponseData[email]-
addResponseData[telephonenumber]-
addResponseData[street]-
addResponseData[city]-
addResponseData[country]-
addResponseData[countrycode]-
addResponseData[zip]-
addResponseData[shipping_firstname]-
addResponseData[shipping_lastname]-
addResponseData[shipping_street]-
addResponseData[shipping_city]-
addResponseData[shipping_country]-
addResponseData[shipping_zip]-
addResponseData[shipping_state]-
addResponseData[shipping_addressaddition]-

addResponseData[monthly_payment_value]

-

Amount of monthly payment

addResponseData[monthly_payment_currency]

-

Currency of monthly payment

addResponseData[total_cost_value]

-

Amount of complete order

addResponseData[total_cost_currency]

-

Currency of complete order

addResponseData[total_interest_value]

-

Amount of interest of complete order

addResponseData[total_interest_currency]

-

Currency of interest

addResponseData[term]

-

Number of monthly payments

addResponseData[payer_id]

-

Identification of paypal user

Example Request

Code Block
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

Code Block
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.

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

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

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue


Example Request

Code Block
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

Code Block
status=APPROVED
txid=12345678
userid=789654

Preauthorization/Authorization

Reservation / Sale

Common Parameter

Required

Comment

clearingtype

+

Fixed value "fnc": Financing

financingtype

+

Fixed value "PPI": Paypal Installment

workorderid

+

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

amount

+

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

Reservation / Sale (Standard Process)

Common Parameter

Required

Comment

Amount

+


Currency

+


BillingAddress/CountryCode

+


BillingAddress/Street

+


BillingAddress/City

+


BillingAddress/Zip

+


BillingAddress/State

-


Email

+


BillingPerson/FirstName

+


BillingPerson/LastName

+


BillingPerson/Email

-


BillingPerson/DateofBirth

-


id[n]

+


de[n]

+


no[n]

+


pr[n]

+


va[n]

-


ShippingAddress/CountryCode

-


ShippingAddress/Street

-


ShippingAddress/City

-


ShippingAddress/Zip

-


ShippingAddress/State

-


ShippingAddress /FirstName

-


ShippingAddress /LastName

-

The Shipping-FirstName is concatenated with the parameter ShippingAddress/LastName and transferred as 'recipient_name'. A space is inserted between the first and lastname.

NarrativeText

-

The content is transferred to the fields "soft_description" and "description".

TransactionParam

-

The content is transferred to the field "custom".

SuccessUrl 

+

Excerpt Include
successurl - definition
successurl - definition
nopaneltrue

CancelUrl 

+

URL "Back" or "Cancel"

ErrorUrl 

+

Excerpt Include
errorurl - definition
errorurl - definition
nopaneltrue

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.

add_paydata[payerid]

-

Can be used to validate the merchant's PayerID against the PayerID reported by PayPal. Unique PayPal Customer Account identification number.

add_paydata [risk_session_correlation_id]

-

Used for paypals "SetTransactionContext"-Feature. Merchant needs to generate a UUID and send it to paypal with this parameter. The following values (tc_keys) will then be sent to paypal as transaction-context referencing the UUID. With this information paypal can check the fraud risk for this payment process. This is a specific feature, that the merchant needs to setup with paypal first in order to use it.

add_paydata[tc_<key>]

-

Will be used for all values defined for "SetTransactionContext" between merchant and paypal.

There can be more than 1 key.

Code Block
titleExample
add_paydata[tc_ota_type] = bus
add_paydata[tc_sender_account_id] = A12345


Code Block
titleWill be sent to paypal as
ota_type = bus
sender_account_id = A12345


Capture

Common Parameter

Required

Comment

Amount

+


Currency

+


CaptureMode

+


Refund

Common Parameter

Required

Comment

Amount

+


Currency

+


Sequence Diagrams

Sale Installment

Drawio
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision4
diagramNamePayPal_Installment_sale
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Order & Delivery Installment

Drawio
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNamePayPal_Installment_order_delivery
simpleViewerfalse
width
diagramWidth1401
revision3

Table of Contents
outlinetrue
indent2em