Versions Compared

Key

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

Explanation

UI Text Box
typenote

For PayPal ECS the request type genericpayment is mandatory. With the first genericpayment the workorderid will be generated from the PAYONE platform and will be sent to you in the response. The ID is unique. The returned workorderid is mandatory for the following requests of PayPal Express Checkout.


UI Steps

Process-description:

UI Step

First of all you have to use the request “genericpayment” with “add_paydata[action]=setexpresscheckout”


UI Step

With “setexpresscheckout”  you initiate the transaction at PayPal and get an unique “workorderid” from the PAYONE platform


UI Step

After the successful request you do another “genericpayment” request with “add_paydata[action]=getexpresscheckoutdetails” to get the shipping and email address of the customer


UI Step

To charge the customers PayPal account you have to do a request “preauthorization/capture” or an “authorization” with the unique “workorderid”


UI Step

After completing step 4 you will get the “txid” which is used for further steps like “capture”, “debit” or “refund”



UI Text Box
typenote

It is mandatory to send the shipping address in the “authorization” or “preauthorization” request if the data is different to the received shipping address from the “genericpayment[action]=getexpresscheckoutdetails”. Otherwise you don’t have the PayPal sellers-protection. With “genericpayment[action]=getexpresscheckoutdetails” you only get the customer shipping address from PayPal. Use shipping address also as billing address. Your customer should have an option to change billing address while checking out. If you want to use multi partial capture, you need to set settleaccount to yes or auto, to be able to send another capture afterwards. Do not use settleaccount=no.

Genericpayment

Request 

Common Parameter

Required

Comment

aid

+

Excerpt Include
aid - definition
aid - definition
nopaneltrue

clearingtype
Has to be "wlt"

amount

+

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

narrative_text

-

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

add_paydata[action]

o

  1. action=setexpresscheckout
  2. action=getexpresscheckoutdetails

workorderid

o

With the first genericpayment the workorderid will be generated from the PAYONE platform and will be sent to you in the response. The ID is unique. The returned workorderid is mandatory for the following requests of PayPal Express Checkout.

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[request_billing_address]

-

Set to “1” if you want to receive customers billing address. Don’t send this parameter, if you don’t want to receive billing address.

Your paypal account needs to be activated by paypal in order to receive billing address. Please consult paypal for further details.

add_paydata[PaymentAction]-
To set initiate a "final sale" transaction (PaymentAction=Sale). By default - without this parameter - the transaction is initiated as an authorization, which is e.g. not suitable for some industries.


Section


Layout box
cssClasspayonePermittedSymbols
floatingleft

Fixed Value


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
Sale


(only available for genericpayment-Requests, where add_paydata[action]=setexpresscheckout)

Parameter ( delivery data )



shipping_firstname

-

Excerpt Include
shipping_firstname - definition
shipping_firstname - definition
nopaneltrue

shipping_lastname

-

Excerpt Include
shipping_lastname - definition
shipping_lastname - definition
nopaneltrue

shipping_company

-

Excerpt Include
shipping_company - definition
shipping_company - definition
nopaneltrue

shipping_street

-

Excerpt Include
shipping_street - definition
shipping_street - definition
nopaneltrue

shipping_zip

-

Excerpt Include
shipping_zip - definition
shipping_zip - definition
nopaneltrue

shipping_city

-

Excerpt Include
shipping_city - definition
shipping_city - definition
nopaneltrue

shipping_state

-

Excerpt Include
shipping_state - definition
shipping_state - definition
nopaneltrue

shipping_country

-

Excerpt Include
shipping_country - definition
shipping_country - definition
nopaneltrue

Parameter ( e-wallet )



wallettype

+

PPE: PayPal Express

successurl

o

URL "payment successful"

errorurl

o

URL "payment faulty"

backurl

o

URL "Back" or "Cancel"

Response

Common Parameter

Required

Comment

status

+

REDIRECT / OK / ERROR

Parameter (OK)

workorderid

+

Workorderid (PAYONE)

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

Parameter ( personal data )

add_paydata[email]

-


add_paydata[payerid]

-

Unique PayPal Customer Account identification number.

add_paydata[telephonenumber]-

Buyer's phone number

Section


Layout box
cssClasspayonePermittedSymbols
floatingleft
Sample Value


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
+49 1721234567



add_paydata[payerstatus]-

PayPal payer status.

The criteria for a PayPal account to become "verified" varies from country to country, but usually depend on adding or confirming either a bank or a card. Before that is done an account is "unverified".

Section


Layout box
cssClasspayonePermittedSymbols
floatingleft
PermittedValues


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
verified
unverified



Parameter ( delivery data )

add_paydata[shipping_firstname]

-


add_paydata[shipping_lastname]

-


add_paydata[shipping_company]

-


add_paydata[shipping_street]

-


add_paydata[shipping_addressaddition]

-


add_paydata[shipping_zip]

-


add_paydata[shipping_city]

-


add_paydata[shipping_state]

-


add_paydata[shipping_country]

-


Parameter ( billing address )

UI Text Box

If add_paydata[request_billing_address] is set to “1” in “setexpresscheckout”-request, you’ll receive the following billing address parameters in “getexpresscheckoutdetails”-response


add_paydata[street]

o

Billing street

add_paydata[city]

o

Billing city

add_paydata[country]

o

Billing country (ISO 3166)

add_paydata[zip]

o

Billing zip

add_paydata[lastname]

o

Billing name (Paypal sends firstname and lastname separated by a space.)

Parameter (REDIRECT) (e-wallet)

redirecturl

+

Redirect URL

add_paydata[token]

+

Express Checkout Token for use with “Magnes Library” (Fraud)

Parameter (ERROR)

errorcode

+

Excerpt Include
errorcode - definition
errorcode - definition
nopaneltrue

errormessage

-

Excerpt Include
errormessage - definition
errormessage - definition
nopaneltrue

customermessage

-

Excerpt Include
customermessage - definition
customermessage - definition
nopaneltrue

Use of Magnes Library

UI Text Box

To use Magnes Library support with express checkout, please start the process with a generic payment request with action “setexpresscheckout” as described above. Part of the response will be the add_paydata[token] that contains the express checkout token, you need to initialise the magnes library.

In addition to the use of magnes library in express echeckout context, you can also acquire the express checkout token while using the “normal” paypal checkout. In this case, you can send an authorization or preauthorization to our server api and the response will contain the token inside the parameter add_paydata[token]. Please use this token like in the express checkout to initialise the magnes library and send data to paypal.

Please see the following response parameter:

Preauthorization/Authorization 

Response 

Parameter

Required

Comment

add_paydata[token]

+

Express Checkout Token for use with “Magnes Library” to prevent fraud


UI Text Box
typeinfo

After initialization the magnes library will automatically send the risk payload to paypal. For further details please read the magnes library documentation provided by paypal.

The express checkout uses the complete process including generic payment requests. If you don’t want to use the complete express checkout experience, the process will start with the “place order” button.

Sequence Diagrams

Sale ECS

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision6
diagramNamePayPal_Sale_ECS
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Order & Delivery ECS

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision7
diagramNamePayPal_ecs_order_delivery
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Table of Contents
outlinetrue
indent2em