Network Tokens
Forward cryptogram
Forward a request to a certified third-party provider with cryptogram data injected server-side, so it never touches your systems. This lets SAQ-A merchants use network tokens without ever handling a raw cryptogram, and mirrors Forward card data.
- Resolves the single-use
x-cryptogram-referencereturned by Request cryptogram inreferencemode. - Injects the cryptogram and other PCI-scoped fields (token PAN, expiry, ECI, and more) into your request body via placeholders.
- Forwards the result to the
x-destination-url.
See Network Tokens for the full placeholder list.
POST
/
api
/
network
/
tokens
/
{id}
/
forward
Forward cryptogram
curl --request POST \
--url https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-cryptogram-reference: <x-cryptogram-reference>' \
--header 'x-destination-url: <x-destination-url>' \
--data '
{
"paymentMethod": {
"type": "networkToken",
"number": "{{ number }}",
"expiryMonth": "{{ expiry_month | unwrap }}",
"expiryYear": "{{ expiry_year | unwrap }}"
},
"mpiData": {
"authenticationResponse": "Y",
"cavv": "{{ cryptogram }}",
"eci": "{{ eci }}"
}
}
'import requests
url = "https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward"
payload = {
"paymentMethod": {
"type": "networkToken",
"number": "{{ number }}",
"expiryMonth": "{{ expiry_month | unwrap }}",
"expiryYear": "{{ expiry_year | unwrap }}"
},
"mpiData": {
"authenticationResponse": "Y",
"cavv": "{{ cryptogram }}",
"eci": "{{ eci }}"
}
}
headers = {
"x-cryptogram-reference": "<x-cryptogram-reference>",
"x-destination-url": "<x-destination-url>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-cryptogram-reference': '<x-cryptogram-reference>',
'x-destination-url': '<x-destination-url>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
paymentMethod: {
type: 'networkToken',
number: '{{ number }}',
expiryMonth: '{{ expiry_month | unwrap }}',
expiryYear: '{{ expiry_year | unwrap }}'
},
mpiData: {authenticationResponse: 'Y', cavv: '{{ cryptogram }}', eci: '{{ eci }}'}
})
};
fetch('https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward', 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/network/tokens/{id}/forward",
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([
'paymentMethod' => [
'type' => 'networkToken',
'number' => '{{ number }}',
'expiryMonth' => '{{ expiry_month | unwrap }}',
'expiryYear' => '{{ expiry_year | unwrap }}'
],
'mpiData' => [
'authenticationResponse' => 'Y',
'cavv' => '{{ cryptogram }}',
'eci' => '{{ eci }}'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-cryptogram-reference: <x-cryptogram-reference>",
"x-destination-url: <x-destination-url>"
],
]);
$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/network/tokens/{id}/forward"
payload := strings.NewReader("{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-cryptogram-reference", "<x-cryptogram-reference>")
req.Header.Add("x-destination-url", "<x-destination-url>")
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/network/tokens/{id}/forward")
.header("x-cryptogram-reference", "<x-cryptogram-reference>")
.header("x-destination-url", "<x-destination-url>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-cryptogram-reference"] = '<x-cryptogram-reference>'
request["x-destination-url"] = '<x-destination-url>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}"
response = http.request(request)
puts response.read_body{}{
"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": 404,
"message": "The requested resource was not found.",
"classifier": "NOT_FOUND"
}{
"code": 502,
"message": "Bad gateway",
"classifier": "BAD_GATEWAY"
}{
"code": 503,
"message": "Service unavailable",
"classifier": "SERVICE_UNAVAILABLE"
}{
"code": 504,
"message": "Gateway timeout",
"classifier": "GATEWAY_TIMEOUT"
}Authorizations
bearerAuthAPIKey
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.
Headers
The cryptogram_reference UUID returned by Request cryptogram in reference mode. Single-use and short-lived.
The target URL to which the request shall be forwarded. Guardian forwards calls only to whitelisted destination URLs (major payment providers are included by default). Contact support to whitelist a custom URL.
Example:
"https://api.psp.example.com/payments"
Path Parameters
The ID of the network token.
Body
application/json
The payload to forward to the third-party provider.
Use placeholders to inject sensitive, cryptogram-derived data on the fly. Available placeholders include
{{ cryptogram }}, {{ dynamic_cvv }}, {{ eci }}, {{ expiry_month }}, {{ expiry_year }}, {{ number }}
(the network token number / TPAN), {{ type }}, {{ scheme_reference }}, {{ network_token_id }}, and {{ network_token_type }}.
Append | unwrap to emit a value as its native type instead of a string, e.g. {{ expiry_month | unwrap }}.
See Network Tokens for the full placeholder list.
Response
Success response
The response from the third-party provider.
⌘I
Forward cryptogram
curl --request POST \
--url https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-cryptogram-reference: <x-cryptogram-reference>' \
--header 'x-destination-url: <x-destination-url>' \
--data '
{
"paymentMethod": {
"type": "networkToken",
"number": "{{ number }}",
"expiryMonth": "{{ expiry_month | unwrap }}",
"expiryYear": "{{ expiry_year | unwrap }}"
},
"mpiData": {
"authenticationResponse": "Y",
"cavv": "{{ cryptogram }}",
"eci": "{{ eci }}"
}
}
'import requests
url = "https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward"
payload = {
"paymentMethod": {
"type": "networkToken",
"number": "{{ number }}",
"expiryMonth": "{{ expiry_month | unwrap }}",
"expiryYear": "{{ expiry_year | unwrap }}"
},
"mpiData": {
"authenticationResponse": "Y",
"cavv": "{{ cryptogram }}",
"eci": "{{ eci }}"
}
}
headers = {
"x-cryptogram-reference": "<x-cryptogram-reference>",
"x-destination-url": "<x-destination-url>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-cryptogram-reference': '<x-cryptogram-reference>',
'x-destination-url': '<x-destination-url>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
paymentMethod: {
type: 'networkToken',
number: '{{ number }}',
expiryMonth: '{{ expiry_month | unwrap }}',
expiryYear: '{{ expiry_year | unwrap }}'
},
mpiData: {authenticationResponse: 'Y', cavv: '{{ cryptogram }}', eci: '{{ eci }}'}
})
};
fetch('https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward', 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/network/tokens/{id}/forward",
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([
'paymentMethod' => [
'type' => 'networkToken',
'number' => '{{ number }}',
'expiryMonth' => '{{ expiry_month | unwrap }}',
'expiryYear' => '{{ expiry_year | unwrap }}'
],
'mpiData' => [
'authenticationResponse' => 'Y',
'cavv' => '{{ cryptogram }}',
'eci' => '{{ eci }}'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-cryptogram-reference: <x-cryptogram-reference>",
"x-destination-url: <x-destination-url>"
],
]);
$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/network/tokens/{id}/forward"
payload := strings.NewReader("{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-cryptogram-reference", "<x-cryptogram-reference>")
req.Header.Add("x-destination-url", "<x-destination-url>")
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/network/tokens/{id}/forward")
.header("x-cryptogram-reference", "<x-cryptogram-reference>")
.header("x-destination-url", "<x-destination-url>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{instance}.{env}.on-hellgate.cloud/api/network/tokens/{id}/forward")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-cryptogram-reference"] = '<x-cryptogram-reference>'
request["x-destination-url"] = '<x-destination-url>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"number\": \"{{ number }}\",\n \"expiryMonth\": \"{{ expiry_month | unwrap }}\",\n \"expiryYear\": \"{{ expiry_year | unwrap }}\"\n },\n \"mpiData\": {\n \"authenticationResponse\": \"Y\",\n \"cavv\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n }\n}"
response = http.request(request)
puts response.read_body{}{
"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": 404,
"message": "The requested resource was not found.",
"classifier": "NOT_FOUND"
}{
"code": 502,
"message": "Bad gateway",
"classifier": "BAD_GATEWAY"
}{
"code": 503,
"message": "Service unavailable",
"classifier": "SERVICE_UNAVAILABLE"
}{
"code": 504,
"message": "Gateway timeout",
"classifier": "GATEWAY_TIMEOUT"
}