Wallet Tokens

Validate Apple Pay session

Complete Apple Pay’s onvalidatemerchant exchange. When the customer opens the Apple Pay sheet in a browser, Apple fires onvalidatemerchant; your backend forwards the request here. Guardian performs the mTLS handshake with Apple using your merchant identity certificate and returns Apple’s merchant session object verbatim, which you pass to session.completeMerchantValidation(...) in the browser.

The domain_name must be a verified Apple Pay domain. Guardian reads your merchant identifier and display name from the Apple Pay settings; until those are uploaded the request returns 400 with the classifier APPLE_PAY_NOT_CONFIGURED. A request for an unregistered or unverified domain returns 422 with the classifier APPLE_PAY_DOMAIN_NOT_VERIFIED. If Apple rejects the validation, Guardian returns 502 with APPLE_PAY_SESSION_ERROR; if no active merchant identity certificate exists, the request returns 500 with APPLE_PAY_NO_ACTIVE_CERTIFICATE.

POST

api

wallet

apple-pay

sessions

Validate Apple Pay session

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain_name": "pay.example.com"
}
'

import requests

url = "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions"

payload = { "domain_name": "pay.example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain_name: 'pay.example.com'})
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'domain_name' => 'pay.example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions"

	payload := strings.NewReader("{\n  \"domain_name\": \"pay.example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain_name\": \"pay.example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"domain_name\": \"pay.example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "epochTimestamp": 1769851200000,
  "expiresAt": 1769853000000,
  "merchantSessionIdentifier": "SSH0A1B2C3D4E5F60718293A4B5C6D7E8F",
  "nonce": "0a1b2c3d",
  "merchantIdentifier": "merchant.com.example",
  "displayName": "Example Store",
  "initiative": "web",
  "initiativeContext": "pay.example.com",
  "signature": "308006092a864886f70d010702a0803080020101310f...",
  "operationalAnalyticsIdentifier": "Example Store:merchant.com.example",
  "retries": 0
}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

{
  "code": 500,
  "message": "The Apple Pay token could not be processed due to a server-side configuration issue.",
  "classifier": "APPLE_PAY_NO_ACTIVE_CERTIFICATE"
}

{
  "code": 502,
  "message": "Bad gateway",
  "classifier": "BAD_GATEWAY"
}

Authorizations

Authorization

string

header

required

JWT bearer token obtained via the OAuth2 client-credentials grant from the platform Authentication API. The token's scopes gate the endpoints it may call, and its audience names the Guardian instance. This is the standard way to authenticate to Guardian.

Body

application/json

domain_name

string

required

The fully-qualified merchant domain to validate. Must be verified.

Example:

"pay.example.com"

Response

Apple Pay merchant session, returned verbatim from Apple.

Apple Pay merchant session JSON, returned verbatim from Apple. Treat it as opaque — pass it straight to session.completeMerchantValidation(...) without parsing or modifying it. The fields shown are illustrative; Apple controls the payload and may change it.

⌘I

Validate Apple Pay session

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain_name": "pay.example.com"
}
'

import requests

url = "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions"

payload = { "domain_name": "pay.example.com" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain_name: 'pay.example.com'})
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'domain_name' => 'pay.example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions"

	payload := strings.NewReader("{\n  \"domain_name\": \"pay.example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain_name\": \"pay.example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"domain_name\": \"pay.example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "epochTimestamp": 1769851200000,
  "expiresAt": 1769853000000,
  "merchantSessionIdentifier": "SSH0A1B2C3D4E5F60718293A4B5C6D7E8F",
  "nonce": "0a1b2c3d",
  "merchantIdentifier": "merchant.com.example",
  "displayName": "Example Store",
  "initiative": "web",
  "initiativeContext": "pay.example.com",
  "signature": "308006092a864886f70d010702a0803080020101310f...",
  "operationalAnalyticsIdentifier": "Example Store:merchant.com.example",
  "retries": 0
}

{
  "code": 400,
  "message": "The request could not be handle due to invalid data",
  "classifier": "BAD_REQUEST"
}

{
  "code": 401,
  "message": "No valid means of authentication was provided",
  "classifier": "UNAUTHORIZED"
}

{
  "code": 403,
  "message": "Not allowed to access this resource or feature",
  "classifier": "FORBIDDEN"
}

{
  "code": 422,
  "classifier": "VALIDATION_ERROR",
  "message": "Validation error",
  "validation_errors": [
    {
      "path": "json-path",
      "message": "human readable error message"
    }
  ]
}

{
  "code": 500,
  "message": "The Apple Pay token could not be processed due to a server-side configuration issue.",
  "classifier": "APPLE_PAY_NO_ACTIVE_CERTIFICATE"
}

{
  "code": 502,
  "message": "Bad gateway",
  "classifier": "BAD_GATEWAY"
}

Getting Started

Tokens

Metadata

Admin

Validate Apple Pay session

Authorizations

Body

Response