Table Of Contents
  CREDIT AND DEBIT CARD PAYMENTS  SUPPORTED SCHEMES  PARAMETERS FOR CREDIT CARD PAYMENTS  INTEGRATION ON TEST ENVIRONMENT  STEP 4: TEST CARDS FOR TESTING OF INTEGRATION  STEP 5: GOING TO PRODUCTION

Credit and debit Card Payments

Supported Schemes

Scheme Payment Product Id
Visa

1
American Express

2
Mastercard

3
JCB

125
Diners Club

132

Parameters for Credit Card Payments

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 (reservation) of the payment amount that is ready for capture. Pre-authorizations can be reversed and can usually 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 directly captured at the moment of approval.
recurring.recurringPaymentSequenceIndicator

Determines the series of a recurring card on file transaction. Allowed values:

  • first - Should be provided if the transaction is the first of a series of recurring transactions. Usually requires a strong customer authentication.
  • recurring - Should be provided if the transaction is a subsequent transaction in a series of recurring transactions and a previous card on file agreement with an initial successful strong customer authentication has occured.
paymentProcessingToken

String of the token that is required to initiate the payment. Will be created during the creditcardcheck request using a separate integration (see documentation below)
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.
unscheduledCardOnFileRequestor

Determines the initiator of the an unscheduled card on file transaction. Allowed values:

  • merchantInitiated - The merchant has initiated the transaction meaning that the customer usually is not present. 
  • cardholderInitiated - The cardholer has initiated the transaction (e.g. One-Click transactions).
unscheduledCardOnFileSequenceIndicator

Determines the series of an unscheduled card on file transaction. Allowed values:

  • first - Should be provided if the transaction is the first of a series of unscheduled transactions. Usually requires a strong customer authentication.
  • subsequent - Should be provided if the transaction is a subsequent transaction in a series of unscheduled transactions and a previous card on file agreement with an initial successful strong customer authentication has occured.
paymentProductId

Payment product identifier - see above for a full overview of possible values. The cardType of the credit card is part of the response of the creditcardcheck.
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.

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. A step by step guide for the integration on the test environment as well as for production can be found below.

---end

Integration on test environment

The following steps are also implemented in our SDKs. If you are using those, please head over to our Integration Guide.

Step 1: JWT Token Generation

Create a Json Web Token 

Creating a JWT needed for later authentication within JS form when is being submitted for card processing.

POST JWT Request
Request - Empty Body
/v1/{merchantId}/authentication-tokens

Response JWT
{
  "token": "xxxxxxxxxxxxx.eyJzdWIiOiIxMjxxxxxxxxxxxxxbmFtZSI6IkpvaG4gRG9lIiwiaWxxxxxxxxxxxxxxx5MDIyfQ.SflKxwRxxxxxxxxxxxxMeJf36POk6yJV_adQssw5c",
  "id": "b3xxxx35-57c9-4118-8712-9a5xxxx3eb37",
  "creationDate": "2025-07-01T00:00:00.000Z",
  "expirationDate": "2025-08-01T00:00:00.000Z"
}

Step 2: hosted iframe for tokenization of credit and debit cards

---end

Tokenization page example
<html>
    <head>
        <script src="https://sdk.preprod.tokenization.secure.payone.com/1.0.1/hosted-tokenization-sdk.js" integrity="sha384-Ec6OPQvn8poHUzTwcUYWC/pwd5wgVuVB+jKl+Eml5MWou154pm6j2MdhhJb9uqML" crossorigin="anonymous"></script>
        <script>
            function tokenizationSuccessCallback(statusCode, token, cardDetails) {
                // This is where you can do stuff with the token and the cardDetails e.g.:
                console.log("Tokenized card sucessfully");

                console.log(statusCode); // e.g. 201
                console.log(token);
                console.log(cardDetails.cardholderName);
                console.log(cardDetails.cardNumber);
                console.log(cardDetails.expiryDate);
                console.log(cardDetails.cardType);
            }

            function tokenizationFailureCallback(statusCode, errorResponse) {
                // This is where you can handle errors that can happen during the tokenization (e.g. expired JWTs or malformated JWTs)
                console.log("Tokenization of card failed");

                console.log(statusCode); // e.g. 400
                console.log(errorResponse.error); // optional e.g. "JWT structure is incorrect."
            }

            const config = {
                iframe: {
                    iframeWrapperId: "payment-IFrame",
                    height: 400,
                    width: 400
                },
                uiConfig: {
                    formBgColor: "#64bbb7",
                    fieldBgColor: "wheat",
                    fieldBorder: "1px solid #b33cd8",
                    fieldOutline: "#101010 solid 5px",
                    fieldLabelColor: "#d3d83c",
                    fieldPlaceholderColor: "blue",
                    fieldTextColor: "crimson",
                    fieldErrorCodeColor: "green"
                },
                locale: "de_DE",
                token: "Token to be retrieved from the CommercePlatform-API",
            }

            if (window.HostedTokenizationSdk) {
                console.log('HTP-SDK initialized successfully');

                async function loadSDK() {
                    try {
                        await window.HostedTokenizationSdk.init();
                        window.HostedTokenizationSdk.getPaymentPage(config);
                        console.log('HTP-SDK loaded successfully');
                    } catch (error) {
                        console.error('Error initializing HTP-SDK:', error);
                    }
                }
                loadSDK();
            } else {
                console.log("HTP-SDK failed to load");
            }
        </script>
    </head>
    <body>
        <div id="payment-IFrame"></div>
            <button onClick="window.HostedTokenizationSdk.submitForm(tokenizationSuccessCallback, tokenizationFailureCallback)">Submit</button>
    </body>
</html>
In the iFrame example the JWT Token previously generated needs to be used.

---end

Step 3: Run html on a webserver to load the javaScript file from payone server

If you want to test this script locally, you can use docker to test it:

docker run -p 80:80 -v <your directory>:/usr/local/apache2/htdocs/ httpd:latest
The page will load the JavaScript and use the configured credentials to perform a tokenization request.

---end

Step 4: Test cards for testing of integration

With the following test card data the described integration can be tested to create a token: https://docs.payone.com/security-risk-management/3d-secure#/

---end

STEP 5: Going to production

If you want to switch to production, please exchange the source domain of the JS by changing

<script src="https://sdk.preprod.tokenization.secure.payone.com/1.0.1/hosted-tokenization-sdk.js" integrity="sha384-Ec6OPQvn8poHUzTwcUYWC/pwd5wgVuVB+jKl+Eml5MWou154pm6j2MdhhJb9uqML" crossorigin="anonymous"></script>


to

<script src="https://sdk.tokenization.secure.payone.com/1.0.1/hosted-tokenization-sdk.js" integrity="sha384-Ec6OPQvn8poHUzTwcUYWC/pwd5wgVuVB+jKl+Eml5MWou154pm6j2MdhhJb9uqML" crossorigin="anonymous">

Creation of Commerce case and checkout with credit card payment 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
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"
    }
}

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

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

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.

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

Deliver

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

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

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

Webhook after successful Deliver

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

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