session

HTTP method: POST

This endpoint initiates a new payment using the Card Wallet flow and retrieves merchant session data.

  • Sends a payment request with all relevant payment information to the payment gateway so the payment can be registered for later authorization.
  • Includes any additional data required by the wallet provider to retrieve a session used to proceed with the payment (for example, for Apple Pay the validationUrl is appended).
  • The returned session object (Body.WalletData.Session in our response) must be passed to session.completeMerchantValidation(JSON.parse(merchantSession)); to enable payment authorization.
Parameter Description Type
terminal The title of your terminal string
shop_orderid The id of the order in your webshop. This is what we will post back to you so you know which order a given payment is associated with [a-zA-Z0-9-]{1,100}
amount The amount of the payment in english notation (ex. 89.95) float
currency The currency of the payment in ISO-4217 format. Either the 3- digit numeric code, or the 3- letter character code [0-9]{3} or [A-Z]{3}

The optional parameters follow the same logic as with eCommerce/API/createPaymentRequest. The parameters are listed here for convenience. For details on usage, see the documentation for createPaymentRequest.

Parameter Description Type
customer_info Customer info object Customer info
orderLines Order lines object Order lines
language Language [a-z]{2}
transaction_info Additional info about the payment string array, max 50 entries, each entry of max 255 chars

type

This is the authorization type. For more information, see Payment request types:

  • payment (default)
  • paymentAndCapture
  • verifyCard
  • credit
  • subscription
  • subscriptionAndCharge
  • subscriptionAndReserve

It is not possible to create a payment request with type=payment.

If the type is set to payment, it is automatically changed to paymentAndCapture.

string

 
sale_reconciliation_identifier Sale reconciliation identifier string{0,100}
sale_invoice_number Sale invoice number string{0,100}
sales_tax Sales tax float
cookie Cookie string
fraud_service Fraud service provider none
maxmind
red
test
shipping_method Shipping method type LowCost
DesignatedByCustomer
Internatioal
Military
NextDay
Other
StorePickup
TwoDayService
ThreeDayService
customer_created_date Customer created date date (yyyy-mm-dd)

When using a non-tokenized scenario (e.g. Google Pay on a non-Android device), provide these attributes to determine browser fingerprint information used in 3DS processing:

Parameter Description Type
customer_info[client_time_zone] Client time zone string
customer_info[client_javascript_enabled] Client javascript enabled boolean
customer_info[client_screen_width] Client screen width integer
customer_info[client_screen_height] Client screen height integer
customer_info[client_color_depth] Client color depth integer
customer_info[client_java_enabled] Client java enabled boolean
customer_info[client_forwarded_ip] Client forwarded IP string
customer_info[client_user_agent] Client user agent string
customer_info[client_accept] Client accept string
customer_info[client_accept_language] Client accept language string
customer_info[client_ip] Client IP string
Parameter Description Type
applePayRequestData[validationUrl] The validation URL that is passed from requestSession ApplePayValidateMerchantEvent.validationURL. Mandatory for requests with source APPLE_PAY_JS_API. string
applePayRequestData[domain] The domain from which you are initializing the request, which requires to be verified. Otherwise, the request will use the default domain specified in the terminal. string
applePayRequestData[source]

The source of the request. Supported values:

  • APPLE_PAY_JS_API (default) - request from WEB SDK API
  • PASSKIT - request from Mobile SDK API
 string
validationUrl *Legacy - The validation URL that is passed from requestSession ApplePayValidateMerchantEvent.validationURL. string
domain *Legacy - The domain from which you are initializing the request, which requires to be verified. Otherwise, the request will use the default domain specified in the terminal. string

*Legacy - only when related terminal is marked with the legacy flag in the gateway configuration.

  • If disabled, merchant has to send complete payment request information while creating an ApplePay session and reference the created `paymentId` when authorising the payment. This allows us to track every payment attempt from the very beginning and quickly identify issues related to ApplePay initialization. The ApplePay parameters from the session request are wrapped into a provider class (`applePayRequestData[validationUrl]`, `applePayRequestData[domain]`) to support different types of wallet in the future.
  • If enabled, the payment is registered and logged in our system during the second step of the wallet flow (authorize), so the second request contains all payment attributes. The session request keeps only necessary information about `validationUrl` and `domain` (without wrapping) to set up the merchant session on frontend.

All GooglePay configuration and setup are handled on the frontend. Calling API/cardWallet/session is a mandatory step in the flow to initialize the transaction on the gateway, but no extra provider-specific parameters are required for Google Pay in this request.


 <APIResponse version="20251105">
    <Header>
        <Date>2025-12-12T12:22:44+00:00</Date>
        <Path>API/cardWallet/session</Path>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage/>
    </Header>
    <Body>
        <Result>Success</Result>
        <WalletData>
            <Session>![CDATA[
            {
                "epochTimestamp": 1519310874452,
                "expiresAt": 1519318074452,
                "merchantSessionIdentifier": "SSH9C72...F0F94927C24",
                "nonce": "b780c456",
                "merchantIdentifier": "7E2A...883B7491568F",
                "domainName": "devgateway.devaltapaysecure.dk",
                "displayName": "ApplePay Test",
                "signature": "308006092a8...feec63000000000000"
            }]]
        </Session>
        </WalletData>
        <Transactions>
            <Transaction>
                <TransactionId>82</TransactionId>
                <PaymentId>94f5fb41-1d8a-405f-b2ca-1f4b4fd08680</PaymentId>
                <AuthType>payment</AuthType>
                <CardStatus>NoCreditCard</CardStatus>
                <CreditCardToken/>
                <CreditCardMaskedPan/>
                <IsTokenized>false</IsTokenized>
                <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
                <LiableForChargeback>Merchant</LiableForChargeback>
                <CVVCheckResult>Not_Applicable</CVVCheckResult>
                <BlacklistToken/>
                <ShopOrderId>12-5-5886087</ShopOrderId>
                <Shop>AltaPay Checkout Test Shop</Shop>
                <Terminal>ApplePay Checkout Test Terminal</Terminal>
                <TransactionStatus>credit_card_wallet_initialized</TransactionStatus>
                <ReasonCode>NONE</ReasonCode>
                <MerchantCurrency>978</MerchantCurrency>
                <MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
                <CardHolderCurrency>978</CardHolderCurrency>
                <CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
                <ReservedAmount>0.00</ReservedAmount>
                <CapturedAmount>0.00</CapturedAmount>
                <RefundedAmount>0.00</RefundedAmount>
                <CreditedAmount>0.00</CreditedAmount>
                <RecurringDefaultAmount>0.00</RecurringDefaultAmount>
                <SurchargeAmount>0.00</SurchargeAmount>
                <CreatedDate>2025-12-12 12:22:42</CreatedDate>
                <UpdatedDate>2025-12-12 12:22:44</UpdatedDate>
                <PaymentNature>CreditCardWallet</PaymentNature>
                <PaymentSource>eCommerce</PaymentSource>
                <PaymentSchemeName>CreditCard</PaymentSchemeName>
                <AuthorisationExpiryDate/>
                <AuthorisationCode>123456</AuthorisationCode>
                <PaymentNatureService name="ApplePayWalletAcquirer">
                    <SupportsRefunds>true</SupportsRefunds>
                    <SupportsRelease>false</SupportsRelease>
                    <SupportsMultipleCaptures>false</SupportsMultipleCaptures>
                    <SupportsMultipleRefunds>false</SupportsMultipleRefunds>
                </PaymentNatureService>
                <ChargebackEvents/>
                <PaymentInfos>
                    <PaymentInfo name="checkout_payment_id">
                        <![CDATA[10f41016-8236-41aa-8799-91f055e5d129]]>
                    </PaymentInfo>
                    <PaymentInfo name="checkout_session_id">
                        <![CDATA[18004c1e-bfd3-473b-9614-7b86eec54f4f]]>
                    </PaymentInfo>
                </PaymentInfos>
                <CustomerInfo>
                    <UserAgent>JavaSDK/20150217</UserAgent>
                    <IpAddress/>
                    <Email>
                        <![CDATA[test@example.com]]>
                    </Email>
                    <Username/>
                    <AccountIdentifier/>
                    <Firstname>
                        <![CDATA[John]]>
                    </Firstname>
                    <Lastname>
                        <![CDATA[Doe]]>
                    </Lastname>
                    <CardHolderName/>
                    <CustomerPhone>+4584758830</CustomerPhone>
                    <OrganisationNumber/>
                    <CountryOfOrigin>
                        <Country>DK</Country>
                        <Source>BillingAddress</Source>
                    </CountryOfOrigin>
                    <BillingAddress>
                        <Firstname>
                            <![CDATA[John]]>
                        </Firstname>
                        <Lastname>
                            <![CDATA[Doe]]>
                        </Lastname>
                        <Address>
                            <![CDATA[Gyngemose Parkvej 50]]>
                        </Address>
                        <City>
                            <![CDATA[Soeborg]]>
                        </City>
                        <Region>
                            <![CDATA[REG]]>
                        </Region>
                        <Country>
                            <![CDATA[DK]]>
                        </Country>
                        <PostalCode>
                            <![CDATA[2860]]>
                        </PostalCode>
                    </BillingAddress>
                </CustomerInfo>
                <RecipientInfo>
                    <UserAgent>JavaSDK/20150217</UserAgent>
                    <IpAddress/>
                    <Email/>
                    <Username/>
                    <AccountIdentifier/>
                    <Firstname/>
                    <Lastname/>
                    <CardHolderName/>
                    <CustomerPhone/>
                    <OrganisationNumber/>
                    <CountryOfOrigin>
                        <Country/>
                        <Source>NotSet</Source>
                    </CountryOfOrigin>
                </RecipientInfo>
                <ReconciliationIdentifiers/>
            </Transaction>
        </Transactions>
    </Body>
</APIResponse>