Paypal 

Parameters for PayPal Payments

Structure redirectPaymentMethodSpecificInput

paymentProductId

840

requiresApproval

boolean

  • true = the payment requires approval before the funds will be captured using the Approve payment or Capture payment 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.

---end

Example

Simple example for a PayPal payment via Commerce Platform

  • Creating an 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 delivery and capture of the order amount (partial delivery also possible)

Create CommerceCase/Checkout

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

POST Commerce Case

---end

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
                    }
                }
            ]
        }
    }
}

---end

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
                }
            }
        ]
    }
}

---end

Order with PayPal payment

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

POST Order

---end

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"
    }
}

---end

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
                        }
                    ]
                }
            }
        ]
    }
}

---end

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.

---end

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"
}

---end

---end

Delivery

Full Deliver to capture the complete order amount.

POST Deliver

---end

Request
/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/deliver
{
    "deliverType": "FULL",
    "isFinal": true
}

---end

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
                        }
                    ]
                }
            }
        ]
    }
}

---end

---end

Webhook after successful Deliver

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

---end

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"
}

---end