Skip to end of metadata
Go to start of metadata

Explanation

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.


Process-description:

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

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

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

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

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


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

+

Sub-Account ID, defined by PAYONE

Format

NUMERIC(5..6)

clearingtype
Has to be "wlt"

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

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

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

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.

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)

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

Fixed Value

Sale

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

Parameter ( delivery data )



shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

-

Surname of delivery address

Format

CHAR(1..50)

shipping_company

-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street

-

Street number and name 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_city

-

City of delivery address

Format

CHAR(2..50)

shipping_state

-

Specifies state of country of delivery address for the customer
"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

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

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)

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)

Parameter ( personal data )

add_paydata[email]

-


add_paydata[payerid]

-

Unique PayPal Customer Account identification number.

add_paydata[telephonenumber]-

Buyer's phone number

Sample Value
+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".

PermittedValues
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 )

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

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

-

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

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

CHAR(1..1024)

Use of Magnes Library

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

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

Order & Delivery ECS

  • No labels