Wallet Tokens

Tokenize Apple Pay

Turn an Apple Pay payment into a stored wallet token. Pass the PKPaymentToken paymentData envelope exactly as the Apple Pay JS API returns it, as the payment_data field. Guardian verifies the EC_v1 signature against Apple’s trusted certificates and decrypts the payload server-side with your active payment processing certificate, so the decrypted card data never touches your systems.

An Apple Pay payment always yields a device-bound token: a device PAN (DPAN) with a single-use cryptogram and ECI. The underlying funding PAN is never extracted, stored, or returned, so an Apple Pay token cannot be promoted to a network token.

Tokenization is idempotent on the encrypted payload: resubmitting the same envelope returns the existing wallet token. If that payload’s token was already deleted, the request returns 409 with the classifier APPLE_PAY_TOKEN_DELETED. Rejected envelopes return 422 with a classifier naming the cause: APPLE_PAY_SIGNATURE_INVALID, APPLE_PAY_UNKNOWN_CERTIFICATE, APPLE_PAY_TOKEN_EXPIRED, or APPLE_PAY_MALFORMED_TOKEN (Guardian’s generic missing-field classifier, shared by the other Apple Pay endpoints). If no active payment processing certificate exists, the request returns 500 with the classifier APPLE_PAY_NO_ACTIVE_CERTIFICATE.

See Apple Pay for prerequisites and the full flow.

POST

api

wallet

apple-pay

tokenize

Tokenize Apple Pay

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/tokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_data": {
    "version": "EC_v1",
    "data": "3+f5jVXhLf8T...",
    "signature": "MEUCIQD...",
    "header": {
      "ephemeralPublicKey": "MFkwEwYHKoZ...",
      "publicKeyHash": "OrWgjRGkqEWlx...",
      "transactionId": "c1caf5ae5f..."
    }
  }
}
'

import requests

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

payload = { "payment_data": {
        "version": "EC_v1",
        "data": "3+f5jVXhLf8T...",
        "signature": "MEUCIQD...",
        "header": {
            "ephemeralPublicKey": "MFkwEwYHKoZ...",
            "publicKeyHash": "OrWgjRGkqEWlx...",
            "transactionId": "c1caf5ae5f..."
        }
    } }
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({
    payment_data: {
      version: 'EC_v1',
      data: '3+f5jVXhLf8T...',
      signature: 'MEUCIQD...',
      header: {
        ephemeralPublicKey: 'MFkwEwYHKoZ...',
        publicKeyHash: 'OrWgjRGkqEWlx...',
        transactionId: 'c1caf5ae5f...'
      }
    }
  })
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/tokenize', 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/tokenize",
  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([
    'payment_data' => [
        'version' => 'EC_v1',
        'data' => '3+f5jVXhLf8T...',
        'signature' => 'MEUCIQD...',
        'header' => [
                'ephemeralPublicKey' => 'MFkwEwYHKoZ...',
                'publicKeyHash' => 'OrWgjRGkqEWlx...',
                'transactionId' => 'c1caf5ae5f...'
        ]
    ]
  ]),
  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/tokenize"

	payload := strings.NewReader("{\n  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\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/tokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\n}"

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

{
  "id": "0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expiry_month": 12,
    "expiry_year": 2028
  }
}

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

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

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

payment_data

object

required

The Apple Pay EC_v1 paymentData envelope, passed through verbatim as returned by the Apple Pay JS API.

Show child attributes

Response

Success response

string<uuid>

required

The ID of the stored wallet token.

card

object

required

Show child attributes

⌘I

Tokenize Apple Pay

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/tokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_data": {
    "version": "EC_v1",
    "data": "3+f5jVXhLf8T...",
    "signature": "MEUCIQD...",
    "header": {
      "ephemeralPublicKey": "MFkwEwYHKoZ...",
      "publicKeyHash": "OrWgjRGkqEWlx...",
      "transactionId": "c1caf5ae5f..."
    }
  }
}
'

import requests

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

payload = { "payment_data": {
        "version": "EC_v1",
        "data": "3+f5jVXhLf8T...",
        "signature": "MEUCIQD...",
        "header": {
            "ephemeralPublicKey": "MFkwEwYHKoZ...",
            "publicKeyHash": "OrWgjRGkqEWlx...",
            "transactionId": "c1caf5ae5f..."
        }
    } }
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({
    payment_data: {
      version: 'EC_v1',
      data: '3+f5jVXhLf8T...',
      signature: 'MEUCIQD...',
      header: {
        ephemeralPublicKey: 'MFkwEwYHKoZ...',
        publicKeyHash: 'OrWgjRGkqEWlx...',
        transactionId: 'c1caf5ae5f...'
      }
    }
  })
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/wallet/apple-pay/tokenize', 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/tokenize",
  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([
    'payment_data' => [
        'version' => 'EC_v1',
        'data' => '3+f5jVXhLf8T...',
        'signature' => 'MEUCIQD...',
        'header' => [
                'ephemeralPublicKey' => 'MFkwEwYHKoZ...',
                'publicKeyHash' => 'OrWgjRGkqEWlx...',
                'transactionId' => 'c1caf5ae5f...'
        ]
    ]
  ]),
  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/tokenize"

	payload := strings.NewReader("{\n  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\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/tokenize")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"payment_data\": {\n    \"version\": \"EC_v1\",\n    \"data\": \"3+f5jVXhLf8T...\",\n    \"signature\": \"MEUCIQD...\",\n    \"header\": {\n      \"ephemeralPublicKey\": \"MFkwEwYHKoZ...\",\n      \"publicKeyHash\": \"OrWgjRGkqEWlx...\",\n      \"transactionId\": \"c1caf5ae5f...\"\n    }\n  }\n}"

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

{
  "id": "0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "expiry_month": 12,
    "expiry_year": 2028
  }
}

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

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

Getting Started

Tokens

Metadata

Admin

Tokenize Apple Pay

Authorizations

Body

Response