Apple Pay Settings

Update settings

Upload your Apple identity so Guardian can generate CSRs, serve the domain-association file, and validate merchant sessions. Provide your merchant_identifier, a display_name, the byte-exact domain_association_content Apple issued, and the csr_common_name to embed in generated CSRs.

The upload is a partial update: fields you omit keep their current values, and no field is individually required. All four must be set before the dependent flows work.

Available only on self_managed instances. On Starfish-operated (sf_operated) instances the Apple identity and certificates are managed by Starfish, and this endpoint returns 409 with the classifier APPLE_PAY_CERT_MANAGEMENT_UNAVAILABLE.

PUT

api

wallet

apple-pay

settings

Update settings

curl --request PUT \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchant_identifier": "merchant.com.example",
  "display_name": "Example Store",
  "domain_association_content": "7B227073704964223A2242463632...",
  "csr_common_name": "Example Store"
}
'

import requests

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

payload = {
    "merchant_identifier": "merchant.com.example",
    "display_name": "Example Store",
    "domain_association_content": "7B227073704964223A2242463632...",
    "csr_common_name": "Example Store"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchant_identifier: 'merchant.com.example',
    display_name: 'Example Store',
    domain_association_content: '7B227073704964223A2242463632...',
    csr_common_name: 'Example Store'
  })
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings', 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/settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'merchant_identifier' => 'merchant.com.example',
    'display_name' => 'Example Store',
    'domain_association_content' => '7B227073704964223A2242463632...',
    'csr_common_name' => 'Example Store'
  ]),
  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/settings"

	payload := strings.NewReader("{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}"

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

{
  "merchant_identifier": "merchant.com.example",
  "display_name": "Example Store",
  "domain_association_content": "7B227073704964223A2242463632...",
  "csr_common_name": "Example Store",
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-02-01T09:00:00Z"
}

{
  "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": 409,
  "message": "Conflict",
  "classifier": "CONFLICT"
}

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

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

The Apple identity Guardian uses on a self_managed instance. Every field is optional per request; omitted fields keep their current values.

merchant_identifier

string

Your Apple Pay merchant identifier.

Example:

"merchant.com.example"

display_name

string

The merchant display name shown in the Apple Pay sheet.

Example:

"Example Store"

domain_association_content

string

The byte-exact body of the Apple-issued domain-association file, served verbatim at /.well-known/apple-developer-merchantid-domain-association.txt.

Example:

"7B227073704964223A2242463632..."

csr_common_name

string

The common name (CN) to embed in the certificate signing requests Guardian generates.

Example:

"Example Store"

Response

Success response

mode

enum<string>

required

The operating mode of this instance. self_managed means you upload and manage your own Apple identity and certificates; sf_operated means Starfish operates the Apple Developer relationship and mounts the identity and certificates.

Available options:

self_managed,

sf_operated

merchant_identifier

string | null

Example:

"merchant.com.example"

display_name

string | null

Example:

"Example Store"

domain_association_content

string | null

The body of the domain-association file served at /.well-known/apple-developer-merchantid-domain-association.txt.

Example:

"7B227073704964223A2242463632..."

csr_common_name

string | null

Example:

"Example Store"

created_at

string<date-time> | null

Example:

"2026-02-01T09:00:00Z"

updated_at

string<date-time> | null

Example:

"2026-02-01T09:00:00Z"

⌘I

Update settings

curl --request PUT \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchant_identifier": "merchant.com.example",
  "display_name": "Example Store",
  "domain_association_content": "7B227073704964223A2242463632...",
  "csr_common_name": "Example Store"
}
'

import requests

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

payload = {
    "merchant_identifier": "merchant.com.example",
    "display_name": "Example Store",
    "domain_association_content": "7B227073704964223A2242463632...",
    "csr_common_name": "Example Store"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchant_identifier: 'merchant.com.example',
    display_name: 'Example Store',
    domain_association_content: '7B227073704964223A2242463632...',
    csr_common_name: 'Example Store'
  })
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings', 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/settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'merchant_identifier' => 'merchant.com.example',
    'display_name' => 'Example Store',
    'domain_association_content' => '7B227073704964223A2242463632...',
    'csr_common_name' => 'Example Store'
  ]),
  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/settings"

	payload := strings.NewReader("{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/settings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant_identifier\": \"merchant.com.example\",\n  \"display_name\": \"Example Store\",\n  \"domain_association_content\": \"7B227073704964223A2242463632...\",\n  \"csr_common_name\": \"Example Store\"\n}"

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

{
  "merchant_identifier": "merchant.com.example",
  "display_name": "Example Store",
  "domain_association_content": "7B227073704964223A2242463632...",
  "csr_common_name": "Example Store",
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-02-01T09:00:00Z"
}

{
  "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": 409,
  "message": "Conflict",
  "classifier": "CONFLICT"
}

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

Getting Started

Tokens

Metadata

Admin

Update settings

Authorizations

Body

Response