Credit and debit Card Payments

Supported Schemes

Scheme Payment Product Id
Visa

1

American Express

2

Mastercard

3

JCB

125

Diners Club

132

---end

Parameters for Credit Card Payments

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

---end

Structure CardPaymentMethodSpecificInput

authorizationMode

Determines the type of the authorization that will be used. Allowed values:

  • PRE_AUTHORIZATION - The payment creation results in a pre-authorization that is ready for capture. Pre-authortizations can be reversed and can be captured within 30 days. The capture amount can be lower than the authorized amount.
  • SALE - The payment creation results in an authorization that is already captured at the moment of approval.
token

ID of the token to use to create the payment.

transactionChannel

Indicates the channel via which the payment is created. Allowed values:

  • ECOMMERCE - The transaction is a regular E-Commerce transaction.
  • MOTO - The transaction is a Mail Order/Telephone Order.
paymentProductId

Payment product identifier - see above for a full overview of possible values

card.cardholderName

The card holder's name on the card.

returnUrl

The URL that the customer is redirect to after the payment flow has finished.

---end

Example

Simple example for a credit card 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 with 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
{
    "orderType": "FULL",
    "orderReferences": {
        "descriptor": "credit card payment",
        "merchantReference": "Order-1234521236"
    },
    "paymentMethodSpecificInput": {
        "cardPaymentMethodSpecificInput": {
            "card": {
                "cardholderName": "Max Mustermann"
            },
            "token": "9410000000000000713",
            "paymentProductId": 1,
            "transactionChannel": "ECOMMERCE",
            "authorizationMode": "PRE_AUTHORIZATION",
            "returnUrl": "https://return.url"
        },
        "paymentChannel": "ECOMMERCE"
    }
}

---end

If 3DS authentication is required, you'll get a redirect URL. Forward your end customer to the given URL.

---end

Response
{
    "createPaymentResponse": {
        "merchantAction": {
            "actionType": "REDIRECT",
            "redirectData": {
                "redirectURL": "https://threeds-authentication.url"
            }
        },
        "payment": {
            "paymentOutput": {
                "amountOfMoney": {
                    "amount": 67900,
                    "currencyCode": "EUR"
                },
                "references": {
                    "merchantReference": "Order-1234521236"
                },
                "cardPaymentMethodSpecificOutput": {
                    "paymentProductId": 1
                },
                "paymentMethod": "card"
            },
            "status": "REDIRECTED",
            "statusOutput": {
                "isCancellable": false,
                "statusCategory": "PENDING_PAYMENT",
                "isAuthorized": false,
                "isRefundable": false
            },
            "id": "PP2AAD9A0JMBBQDS"
        },
        "paymentExecutionId": "c6e6eadb-b066-4756-83ed-292fbb85da12"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "Lawnmower"
                },
                "orderLineDetails": {
                    "id": "81618ad9-18a5-483e-8bf8-e003f6917958",
                    "productCode": "ABC01",
                    "productPrice": 67900,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "WAITING_FOR_PAYMENT",
                            "quantity": 1
                        }
                    ]
                }
            }
        ]
    }
}

---end

Webhook after successful 3DS authentication

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-13T11:54:23.866352902+00:00",
    "id": "9ec3114e-a2e1-47b9-9a55-75bb4a150a8b",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 67900,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-1234521239"
            },
            "cardPaymentMethodSpecificOutput": {
                "paymentProductId": 1
            },
            "paymentMethod": "card"
        },
        "status": "PENDING_CAPTURE",
        "statusOutput": {
            "isCancellable": true,
            "statusCategory": "PENDING_MERCHANT",
            "isAuthorized": true,
            "isRefundable": false
        },
        "id": "PP2AAD9A0JMBBQDS"
    },
    "type": "payment.pending_capture"
}

---end

Deliver

Full Deliver to capture the complete order amount (initialization of clearing at acquirer).

POST Deliver

---end

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

---end

Response
{
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 67900,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-1234521239"
            },
            "paymentMethod": "card"
        },
        "status": "CAPTURED",
        "id": "PP2AAD9A0JMBBQDS"
    },
    "shoppingCart": {
        "items": [
            {
                "invoiceData": {
                    "description": "Lawnmower"
                },
                "orderLineDetails": {
                    "id": "2344efee-3adf-4b2e-b26f-dc6a8dd9cd06",
                    "productCode": "ABC01",
                    "productPrice": 67900,
                    "productType": "GOODS",
                    "quantity": 1,
                    "taxAmount": 19,
                    "status": [
                        {
                            "lineItemStatus": "DELIVERED",
                            "quantity": 1
                        }
                    ]
                }
            }
        ]
    }
}

---end

Webhook after successful Delivery

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

---end

Request
/v1/{merchantId}/commerce-cases
{
    "apiVersion": "v1",
    "created": "2023-11-13T12:10:14.907858991+00:00",
    "id": "d9285ca8-5361-46a3-80b4-0b0191ff3211",
    "merchantId": "P1_18323_2013224",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 67900,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "Order-1234521239"
            },
            "cardPaymentMethodSpecificOutput": {
                "paymentProductId": 1
            },
            "paymentMethod": "card"
        },
        "status": "CAPTURED",
        "statusOutput": {
            "isCancellable": false,
            "statusCategory": "COMPLETED",
            "isAuthorized": true,
            "isRefundable": true
        },
        "id": "PP2AAD9A0JMBBQDS"
    },
    "type": "payment.captured"
}

---end