Table Of Contents
  CHECKOUT & PAY - BUILDING UP A CHECKOUT STEP BY STEP  PROCESS FLOW

Checkout & Pay - Building up a Checkout step by step

There are different ways of creating a Checkout and initializing a Payment. In the step-by-step approach the process can be compared to the actual interactions from the customer in the shop system: items are added / updated along the way as well as billing and shipping information. The initialization of the payment for the Checkout starts when the customer confirms the order.

Process flow

High-level summary:

  • The Commerce Case and the Checkout are created when the customer starts the order process
  • For returning / existing customers the same Commerce Case can also be used
  • Alternatively the Checkout can also be created when the customer adds the first item to the shopping cart 
  • The Checkout is still modifiable and the customer can add and change details
  • Only after the order is completed, the payment request will be triggered
  • The payment can be triggered via the Order endpoint (which will return a dedicated item status) or via the PaymentExecution endpoint

 

Building up the Checkout step by step and already providing the information to the Commerce Platform allows a better tracking of customers that have not completed the Order. The Checkouts without or with a failed payment are displayed with Checkout status OPEN.
Create Commerce case with Checkout

In a first step, a Commerce Case with a Checkout and only the shopping cart items will be created.

POST Commerce Case
Request
POST/v1/{merchantId}/commerce-cases 
{
    "merchantReference": "Sample-Commerce-Case",
    "checkout": {
        "amountOfMoney": {
            "amount": 8000,
            "currencyCode": "EUR"
        },
        "references": {
            "merchantReference": "Checkout-12345"
        },
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "T-Shirt (weiß)"
                    },
                    "orderLineDetails": {
                        "productCode": "NKE-235",
                        "productPrice": 3000,
                        "productType": "GOODS",
                        "quantity": 1,
                        "taxAmount": 19
                    }
                },
                {
                    "invoiceData": {
                        "description": "Chino-Hose"
                    },
                    "orderLineDetails": {
                        "productCode": "LVIS-286",
                        "productPrice": 5000,
                        "productType": "GOODS",
                        "quantity": 1,
                        "taxAmount": 19
                    }
                }
            ]
        }
    }
}
Response
{
    "commerceCaseId": "d3ec7d23-0b12-4ad9-8f8f-c909b145940c",
    "merchantReference": "Sample-Commerce-Case",
    "checkout": {
        "checkoutId": "b1faca60-09eb-47e1-99a3-07de1ae35dc6",
        "shoppingCart": {
            "items": [
                {
                    "invoiceData": {
                        "description": "T-Shirt (weiß)"
                    },
                    "orderLineDetails": {
                        "id": "5477ad50-25d8-401e-ada4-4a9713378d30",
                        "productCode": "NKE-235",
                        "productPrice": 3000,
                        "productType": "GOODS",
                        "quantity": 1,
                        "taxAmount": 19
                    }
                },
                {
                    "invoiceData": {
                        "description": "Chino-Hose"
                    },
                    "orderLineDetails": {
                        "id": "d9a6b2ff-e4b6-4276-8d92-db0ba4456dcf",
                        "productCode": "LVIS-286",
                        "productPrice": 5000,
                        "productType": "GOODS",
                        "quantity": 1,
                        "taxAmount": 19
                    }
                }
            ]
        },
        "amountOfMoney": {
            "amount": 8000,
            "currencyCode": "EUR"
        },
        "references": {
            "merchantReference": "Checkout-12345"
        },
        "checkoutStatus": "OPEN",
        "statusOutput": {
            "paymentStatus": "WAITING_FOR_PAYMENT",
            "isModifiable": true,
            "openAmount": 0,
            "collectedAmount": 0,
            "cancelledAmount": 0,
            "refundedAmount": 0,
            "chargebackAmount": 0
        },
        "creationDateTime": "2024-02-08T14:16:30.97728473Z",
        "allowedPaymentActions": [
            "ORDER_MANAGEMENT",
            "PAYMENT_EXECUTION"
        ]
    },
}

Adding Personal Data

In the next step, personal information such as billing and shipping details will be added to the existing Checkout.

PATCH Checkout
Request
PATCH/v1/{merchantId}/commerce-cases/{commerceCaseId}(checkouts/{checkoutId}
{
    "customer": {
        "companyInformation": {
            "name": "Customer Company Name"
        },
        "billingAddress": {
            "city": "Musterstadt",
            "countryCode": "DE",
            "houseNumber": "1",
            "state": "SH",
            "street": "Musterstraße",
            "zip": "12345"
        },
        "merchantCustomerId": "Test-Customer",
        "contactDetails": {
            "emailAddress": "max@mustermann.de",
            "phoneNumber": "+1234567890"
        },
        "fiscalNumber": "fiscalNumber",
        "businessRelation": "B2C",
        "locale": "de",
        "personalInformation": {
            "gender": "MALE",
            "name": {
                "firstName": "Max",
                "surname": "Mustermann"
            },
            "dateOfBirth": "19950411"
        }
    },
    "checkout": {
        "shipping": {
            "address": {
                "city": "Musterstadt",
                "countryCode": "DE",
                "houseNumber": "1",
                "state": "SH",
                "street": "Musterstraße",
                "zip": "12345",
                "name": {
                    "firstName": "Max",
                    "surname": "Mustermann"
                }
            }
        }
    }
}

Confirmation of Order

In the last step, the customer will confirm the order by choosing the preferred payment method. The confirmation of the customer will trigger the payment for the Checkout. 

Example for Order endpoint

POST Order
Request
POST/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/order
{
    "orderType": "FULL",
    "orderReferences": {
        "merchantReference": "Visa-PreAuth"
    },
    "paymentMethodSpecificInput": {
        "cardPaymentMethodSpecificInput": {
            "card": {
                "cardholderName": "Max Mustermann"
            },
            "paymentProcessingToken": "9410000000000000713",
            "paymentProductId": 1,
            "transactionChannel": "ECOMMERCE",
            "authorizationMode": "PRE_AUTHORIZATION",
            "returnUrl": "your-return-url-after-payment"
        },
        "paymentChannel": "ECOMMERCE"
    }
}

Important remark: The Commerce Platform does not handle clear PANs, credit card payment will be done only with a token (paymentProcessingToken). In order to create the paymentProcessingToken, a separate integration is required: Client API Hosted iFrames
Response
{
    "createPaymentResponse": {
        "merchantAction": {
            "actionType": "REDIRECT",
            "redirectData": {
                "redirectURL": "your-redirect-url"
            }
        },
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 8000,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Visa-PreAuth"
                },
                "cardPaymentMethodSpecificOutput": {
                    "paymentProductId": 1
                },
                "paymentMethod": "card"
            },
            "status": "REDIRECTED",
            "statusOutput": {
                "isCancellable": false,
                "statusCategory": "PENDING_PAYMENT",
                "isAuthorized": false,
                "isRefundable": false
            },
            "id": "PP2AADC67J3YME8Y"
        },
        "paymentExecutionId": "ae6c2989-d636-4e34-aabd-473875d3ee9f"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "T-Shirt (weiß)"
                },
                "orderLineDetails": {
                    "id": "414f4c62-294e-4aba-a626-eabeaa38d479",
                    "productCode": "NKE-235",
                    "productPrice": 3000,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "WAITING_FOR_PAYMENT",
                            "quantity": 1
                        }
                    ]
                }
            },
            {
                "invoiceData": {
                    "description": "Chino-Hose"
                },
                "orderLineDetails": {
                    "id": "0eaff864-6dc5-441e-9c5d-116c86c0eb07",
                    "productCode": "LVIS-286",
                    "productPrice": 5000,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "WAITING_FOR_PAYMENT",
                            "quantity": 1
                        }
                    ]
                }
            }
        ]
    }
}

Note: Redirect / authentication not shown here

GET Commerce Case with Checkout after successful order

After completing the order (that resulted in a successful payment) all the details for the Commerce Case and Checkout can be retrieved.

GET Checkout
Request
GET/v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}
{
    "commerceCaseId": "e39c94c1-d425-46e5-acfd-ab13b492aaa5",
    "customer": {
        "companyInformation": {
            "name": "Customer Company Name"
        },
        "merchantCustomerId": "Test-Customer",
        "billingAddress": {
            "city": "Musterstadt",
            "countryCode": "DE",
            "houseNumber": "1",
            "state": "SH",
            "street": "Musterstraße",
            "zip": "12345"
        },
        "contactDetails": {
            "emailAddress": "max@mustermann.de",
            "phoneNumber": "+1234567890"
        },
        "fiscalNumber": "fiscalNumber",
        "businessRelation": "B2C",
        "locale": "de",
        "personalInformation": {
            "dateOfBirth": "19950411",
            "gender": "MALE",
            "name": {
                "firstName": "Max",
                "surname": "Mustermann"
            }
        }
    },
    "checkouts": [
        {
            "commerceCaseId": "e39c94c1-d425-46e5-acfd-ab13b492aaa5",
            "checkoutId": "faab91bf-afeb-4266-b1a0-1b2bcca33326",
            "merchantCustomerId": "Test-Customer",
            "amountOfMoney": {
                "amount": 8000,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Checkout-12345"
            },
            "shipping": {
                "address": {
                    "city": "Musterstadt",
                    "countryCode": "DE",
                    "houseNumber": "1",
                    "state": "SH",
                    "street": "Musterstraße",
                    "zip": "12345",
                    "name": {
                        "firstName": "Max",
                        "surname": "Mustermann"
                    }
                }
            },
            "shoppingCart": {
                "items": [
                    {
                        "invoiceData": {
                            "description": "T-Shirt (weiß)"
                        },
                        "orderLineDetails": {
                            "id": "414f4c62-294e-4aba-a626-eabeaa38d479",
                            "productCode": "NKE-235",
                            "productPrice": 3000,
                            "productType": "GOODS",
                            "quantity": 1,
                            "taxAmount": 19,
                            "status": [
                                {
                                    "lineItemStatus": "ORDERED",
                                    "quantity": 1
                                }
                            ]
                        }
                    },
                    {
                        "invoiceData": {
                            "description": "Chino-Hose"
                        },
                        "orderLineDetails": {
                            "id": "0eaff864-6dc5-441e-9c5d-116c86c0eb07",
                            "productCode": "LVIS-286",
                            "productPrice": 5000,
                            "productType": "GOODS",
                            "quantity": 1,
                            "taxAmount": 19,
                            "status": [
                                {
                                    "lineItemStatus": "ORDERED",
                                    "quantity": 1
                                }
                            ]
                        }
                    }
                ]
            },
            "paymentExecutions": [
                {
                    "paymentExecutionId": "ae6c2989-d636-4e34-aabd-473875d3ee9f",
                    "paymentId": "PP2AADC67J3YME8Y",
                    "cardPaymentMethodSpecificInput": {
                        "authorizationMode": "PRE_AUTHORIZATION",
                        "recurring": {},
                        "paymentProcessingToken": "9410000000000000713",
                        "transactionChannel": "ECOMMERCE",
                        "paymentProductId": 1,
                        "card": {
                            "cardholderName": "Max Mustermann"
                        },
                        "returnUrl": "your-return-url-after-payment"
                    },
                    "paymentChannel": "ECOMMERCE",
                    "references": {
                        "merchantReference": "Visa-PreAuth"
                    },
                    "events": [
                        {
                            "type": "RESERVATION",
                            "amountOfMoney": {
                                "amount": 8000,
                                "currencyCode": "EUR"
                            },
                            "paymentStatus": "PENDING_CAPTURE"
                        }
                    ]
                }
            ],
            "checkoutStatus": "COMPLETED",
            "statusOutput": {
                "paymentStatus": "PAYMENT_NOT_COMPLETED",
                "isModifiable": false,
                "openAmount": 8000,
                "collectedAmount": 0,
                "cancelledAmount": 0,
                "refundedAmount": 0,
                "chargebackAmount": 0
            },
            "creationDateTime": "2024-02-08T17:06:34.42673411Z",
            "allowedPaymentActions": [
                "ORDER_MANAGEMENT",
                "PAYMENT_EXECUTION"
            ]
        }
    ],
}

Deliver

Once the items are ready for shipment, the Delivery can be performed to capture the money from the reservation and to mark the items as DELIVERED.

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

Response
{
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 8000,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Visa-PreAuth"
            },
            "paymentMethod": "card"
        },
        "status": "CAPTURED",
        "id": "PP2AADC67J3YME8Y"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "T-Shirt (weiß)"
                },
                "orderLineDetails": {
                    "id": "414f4c62-294e-4aba-a626-eabeaa38d479",
                    "productCode": "NKE-235",
                    "productPrice": 3000,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "DELIVERED",
                            "quantity": 1
                        }
                    ]
                }
            },
            {
                "invoiceData": {
                    "description": "Chino-Hose"
                },
                "orderLineDetails": {
                    "id": "0eaff864-6dc5-441e-9c5d-116c86c0eb07",
                    "productCode": "LVIS-286",
                    "productPrice": 5000,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "DELIVERED",
                            "quantity": 1
                        }
                    ]
                }
            }
        ]
    }
}