PAYONE Documentation Platform

Paypal

Parameters for PayPal Payments

Structure redirectPaymentMethodSpecificInput

paymentProductId	840
requiresApproval	boolean true = the payment requires approval before the funds will be captured using the Deliver or Capture endpoint of the API false = the payment does not require approval, and the funds will be captured automatically
redirectionData.returnUrl	The URL that the customer is redirected to after the payment flow has finished.
tokenize	boolean true = the payment would tokenize / store PayPal account and a an id ( token ) will be received false = the payment does not require tokenization / account storage
paymentProcessingToken	The unique Id which needed to facilitate payments against a stored account. Usable for speeding up checkout process by asking customer to complete transaction using his stored PayPal account or , when customer is not present, to complete a transaction. ( e,g. : Subscription charge ) . Please notice that if tokenize = "true", the paymentProcessingToken will not be considered, and a new process to store consumer account will be initiated. To initiate a payment against a stored account, paymentProcessingToken has to contain the Token ID and tokenize = "false".
paymentProduct840SpecificInput.fraudNetId	A unique ID determined by the merchant, to link a Paypal transaction to a FraudNet PayPal risk session. Only applicable to customer-initiated transactions, when the FraudNet SDK is used, and to be passed in the API request the same tracking ID value (FraudNet Session Identifier). This SDK is available here https://developer.paypal.com/docs/checkout/apm/pay-upon-invoice/fraudnet/

Example

Simple example for a PayPal payment via Commerce Platform

Creating a checkout (here in one step, creating in multiple steps possible)
Creating an order for the entire checkout (partial orders also possible), payment is initialized automatically
Initialization of deliver to capture the amount of the order (partial deliver also possible)

Create CommerceCase/Checkout

Creating a Commerce Case with the initial Checkout including a reference, information about the customer and the items in the shopping cart.

POST Commerce Case

Request
/v1/{merchantId}/commerce-cases

{
    "merchantReference": "commerce-case-paypal-1",
    "customer": {
        "billingAddress": {
            "city": "Musterstadt",
            "countryCode": "DE",
            "houseNumber": "1",
            "street": "Musterstraße",
            "zip": "12345"
        },
        "merchantCustomerId": "Kunde2345",
        "contactDetails": {
            "emailAddress": "max@mustermann.de",
            "phoneNumber": "+1234567890"
        },
        "personalInformation": {
            "gender": "MALE",
            "name": {
                "firstName": "Max",
                "surname": "Mustermann"
            }
        }
    },
    "checkout": {
        "references": {
            "merchantReference": "paypal-001"
        },
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "paypal shirt"
                    },
                    "orderLineDetails": {
                        "productCode": "CBD01",
                        "productPrice": 599,
                        "productType": "GOODS",
                        "quantity": 5,
                        "taxAmount": 19
                    }
                }
            ]
        }
    }
}

Response

{
    "commerceCaseId": "a00b8b25-42d5-486d-8159-e69b3bc2a7e2",
    "checkoutId": "aed6c7f2-507b-4451-88b0-828e4b04f638",
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "paypal shirt"
                },
                "orderLineDetails": {
                    "id": "fab315b5-90f1-4529-8341-a8afdbc8c7ea",
                    "productCode": "CBD01",
                    "productPrice": 599,
                    "productType": "GOODS",
                    "quantity": 5,
                    "taxAmount": 19
                }
            }
        ]
    }
}

Order with PayPal payment

Creating an order for the entire Checkout with data for a PayPal payment.

POST Order

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/order

{
    "orderType": "FULL",
    "orderReferences": {
        "descriptor": "PayPal payment",
        "merchantReference": "Order-2234521243"
    },
    "paymentMethodSpecificInput": {
        "redirectPaymentMethodSpecificInput": {
            "requiresApproval": true,
            "paymentProductId": 840,
            "redirectionData": {
                "returnUrl": "returl.url"
            }
        },   
        "paymentChannel": "ECOMMERCE"
    }
}

Response

{
    "createPaymentResponse": {
        "merchantAction": {
            "actionType": "REDIRECT",
            "redirectData": {
                "redirectURL": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-4VS8792220190983C"
            }
        },
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 2995,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Order-2234521243"
                },
                "paymentMethod": "redirect",
                "redirectPaymentMethodSpecificOutput": {
                    "paymentProductId": 840
                }
            },
            "status": "REDIRECTED",
            "statusOutput": {
                "isCancellable": false,
                "statusCategory": "PENDING_PAYMENT",
                "isAuthorized": false,
                "isRefundable": false
            },
            "id": "PP2AAD9QHE48KG0E"
        },
        "paymentExecutionId": "c9b1bd7a-fd43-4ace-aeae-3f01a3622f19"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "paypal shirt"
                },
                "orderLineDetails": {
                    "id": "fab315b5-90f1-4529-8341-a8afdbc8c7ea",
                    "productCode": "CBD01",
                    "productPrice": 599,
                    "productType": "GOODS",
                    "quantity": 5,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "WAITING_FOR_PAYMENT",
                            "quantity": 5
                        }
                    ]
                }
            }
        ]
    }
}

Webhook after successful confirmation on PayPal portal by end customer

You can identify the corresponding transaction by the field createPaymentResponse.payment.id in the order response. The status PENDING_CAPTURE shows that the amount is authorized and the payment gateway is waiting for a capture.

Webhook

{
    "apiVersion": "v1",
    "created": "2023-11-15T09:54:18.097694888+00:00",
    "id": "88ec52d6-bd59-47bf-b21e-147508d85b02",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 2995,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-2234521243"
            },
            "redirectPaymentMethodSpecificOutput": {
                "paymentProductId": 840
            },
            "paymentMethod": "redirect"
        },
        "status": "PENDING_CAPTURE",
        "statusOutput": {
            "isCancellable": true,
            "statusCategory": "PENDING_MERCHANT",
            "isAuthorized": true,
            "isRefundable": false
        },
        "id": "PP2AAD9QHE48KG0E"
    },
    "type": "payment.pending_capture"
}

Deliver

Full Deliver to capture the complete order amount.

POST Deliver

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/deliver

{
    "deliverType": "FULL",
    "isFinal": true
}

Response

{
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 2995,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-2234521243"
            },
            "paymentMethod": "redirect"
        },
        "status": "CAPTURED",
        "id": "PP2AAD9QHE48KG0E"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "paypal shirt"
                },
                "orderLineDetails": {
                    "id": "fab315b5-90f1-4529-8341-a8afdbc8c7ea",
                    "productCode": "CBD01",
                    "productPrice": 599,
                    "productType": "GOODS",
                    "quantity": 5,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "DELIVERED",
                            "quantity": 5
                        }
                    ]
                }
            }
        ]
    }
}

Webhook after successful Deliver

The payment gateway informs you via webhook about the successful capture.

Webhook

{
    "apiVersion": "v1",
    "created": "2023-11-14T17:25:17.996829148+00:00",
    "id": "74e4fe0e-ee75-4c02-9b80-a3e3df8140d4",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 1998,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-1234521244"
            },
            "redirectPaymentMethodSpecificOutput": {
                "paymentProductId": 990
            },
            "paymentMethod": "redirect"
        },
        "status": "CAPTURED",
        "statusOutput": {
            "isCancellable": false,
            "statusCategory": "COMPLETED",
            "isAuthorized": true,
            "isRefundable": true
        },
        "id": "PP2AAD9B9UAW8BBD"
    },
    "type": "payment.captured"
}