Initialize wallet payment (Apple Pay / Google Pay)

This method creates a payment operation and returns the wallet-specific configuration needed by the frontend to display the Apple Pay or Google Pay payment sheet.

The wallet type is specified via the payment_method.type field in the request body:

• Apple Pay (APPLE_PAY): Returns apple_pay_config with parameters for new ApplePaySession().
• Google Pay (GOOGLE_PAY): Returns google_pay_config with gateway tokenization parameters for loadPaymentData().

The returned id must be used in subsequent session and payment calls.

• URL syntax: /api/v2/merchant/payment/wallet
• Method: POST

Requirements

Apple Pay

• Apple Pay must be enabled on the merchant's API feature
• ROLE_API_PAYMENT permission must be granted
• For pre-authorization: ROLE_PREAUTH permission is required
• The frontend must run in Safari on a device with Apple Pay configured
• The domain serving the Apple Pay button must be registered with Apple

Google Pay

• Google Pay must be enabled on the merchant's API feature
• ROLE_API_PAYMENT permission must be granted
• For pre-authorization: ROLE_PREAUTH permission is required
• The frontend must load the Google Pay JS library (https://pay.google.com/gp/p/js/pay.js)
• For production: your own Google Pay & Wallet Console merchant ID, with the serving domain(s) registered against it, must be configured with SysPay — otherwise the shared SysPay default is returned, which is only valid on SysPay-hosted domains. See Google Pay Console onboarding.

Request parameters

Name	Type	Details	Mandatory	Description
payment_method	object		Y	Wallet payment method. See section below.
amount	string	Amount in cents	Y	The payment amount in cents (e.g. "1999" = 19.99).
currency	string	EUR, USD, GBP, CHF	Y	ISO 4217 currency code.
reference	string	UNIQUE	Y	Your own unique merchant payment reference.
description	string	Max length 300	N	Payment description.
preauth	boolean		N	Set to true for pre-authorization (capture later). Defaults to false.
mandate	boolean		N	Must be false or omitted. Wallet Pay S2S does not support billing agreement mandates. Sending true returns error code 10007.
ems_url	string	URI	N	EMS notification callback URL.
customer	object	Customer	Y	The customer's details. See required fields below.

payment_method parameter

Name	Type	Details	Mandatory	Description
type	string	APPLE_PAY or GOOGLE_PAY	Y	The wallet type to initialize.

customer parameter

Unlike other endpoints where most customer fields are optional, Wallet Pay (Apple Pay / Google Pay) requires a fully identified customer. The following fields are mandatory for wallet payments; a missing field returns error code 10006 ("Missing required parameter") keyed to the specific field (e.g. customer.firstname):

Name	Type	Details	Mandatory	Description
firstname	string	Max length 100	Y	Customer's first name.
lastname	string	Max length 100	Y	Customer's last name.
email	string	Valid email	Y	Customer's email address.
ip	string	Public IPv4/IPv6	Y	Customer's IP address.
billing_address	object		Y	Customer's billing address. address1, postal_code, city and country are required within it.

All other Customer fields remain optional.

Example request — Apple Pay

{
  "payment_method": {
    "type": "APPLE_PAY"
  },
  "amount": "1999",
  "currency": "EUR",
  "reference": "order-20260223-001",
  "description": "Order #001",
  "preauth": false,
  "ems_url": "https://merchant.example.com/notify",
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@example.com",
    "ip": "203.0.113.42",
    "language": "en",
    "billing_address": {
      "address1": "123 Main St",
      "city": "Paris",
      "postal_code": "75001",
      "country": "FR"
    }
  }
}

Example request — Google Pay

{
  "payment_method": {
    "type": "GOOGLE_PAY"
  },
  "amount": "1999",
  "currency": "EUR",
  "reference": "order-20260223-002",
  "description": "Order #002",
  "preauth": false,
  "customer": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@example.com",
    "ip": "203.0.113.42",
    "language": "en",
    "billing_address": {
      "address1": "123 Main St",
      "city": "Paris",
      "postal_code": "75001",
      "country": "FR"
    }
  }
}

Response parameters

The response contains a wallet_pay_init object with the following fields:

Name	Type	Mandatory	Description
id	integer	Y	Operation ID — use this for session and payment calls.
status	string	Y	Operation status. Always OPEN after init.
payment_method	string	Y	Wallet type (APPLE_PAY or GOOGLE_PAY).
apple_pay_config	object	N	Apple Pay configuration. Only present for APPLE_PAY. See below.
google_pay_config	object	N	Google Pay configuration. Only present for GOOGLE_PAY. See below.

apple_pay_config object

Name	Type	Description
merchant_id	string	Apple Pay merchant identifier.
country_code	string	2-letter country code for the Apple Pay merchant.
label	string	Merchant display name shown on the Apple Pay payment sheet.
supported_networks	array	Supported card networks (e.g. visa, masterCard, amex).
merchant_capabilities	array	Merchant capabilities (e.g. supports3DS).

google_pay_config object

Name	Type	Description
gateway	string	Payment gateway identifier for tokenization.
gateway_merchant_id	string	Gateway merchant ID for tokenization.
merchant_id	string	Google Pay merchant ID (BCR2DN…), used in merchantInfo.merchantId. Returns your own Google Pay & Wallet Console merchant ID when configured with SysPay; otherwise falls back to the shared SysPay default, which is only valid on SysPay-hosted domains. Not domain-validated in TEST.
merchant_name	string	Merchant display name shown on the Google Pay payment sheet.
environment	string	Google Pay environment (TEST or PRODUCTION). Use this value when creating the PaymentsClient.
country_code	string	2-letter ISO 3166-1 country code. Used in transactionInfo.countryCode.

Example response — Apple Pay

{
  "wallet_pay_init": {
    "id": 370529,
    "status": "OPEN",
    "payment_method": "APPLE_PAY",
    "apple_pay_config": {
      "merchant_id": "merchant.com.syspay.staging",
      "country_code": "FR",
      "label": "My Store",
      "supported_networks": [
        "visa",
        "masterCard",
        "amex"
      ],
      "merchant_capabilities": [
        "supports3DS"
      ]
    }
  }
}

Example response — Google Pay

{
  "wallet_pay_init": {
    "id": 370530,
    "status": "OPEN",
    "payment_method": "GOOGLE_PAY",
    "google_pay_config": {
      "gateway": "syspay",
      "gateway_merchant_id": "SYSPA978",
      "merchant_id": "BCR2DN4T7654321",
      "merchant_name": "My Store",
      "environment": "PRODUCTION",
      "country_code": "FR"
    }
  }
}