- Created by PAYONE Writer, last modified on 2022-07-21
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 |
|---|---|---|
+ | Format | |
| clearingtype | Has to be "wlt" | |
+ | 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 | |
- | Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. | |
add_paydata[action] | o |
|
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. Format | |
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 the billing address. Please consult your PayPal CSM for further details. |
| add_paydata[payment_action] | - | 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 ) | ||
- | Format | |
- | Format | |
- | Format | |
- | Format | |
- | Postcode of delivery address Format CHAR(2..10) Permitted Symbols
[0-9][A-Z][a-z][_.-/ ] | |
- | Format | |
- | Format Permitted values Samples US Samples CA | |
- | Format Permitted values Samples Some countries require additional information in parameter shipping_state | |
Parameter ( e-wallet ) | ||
+ | PPE: PayPal Express | |
o | URL "payment successful" | |
o | URL "payment faulty" | |
o | URL "Back" or "Cancel" |
Response
Common Parameter | Required | Comment |
status | + | REDIRECT / OK / ERROR |
Parameter (OK) | ||
+ | Workorderid (PAYONE) Format | |
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
verifiedunverified |
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) | ||
+ | Redirect URL | |
add_paydata[token] | + | Express Checkout Token for use with “Magnes Library” (Fraud) |
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 | |
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