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-reference returned by Request cryptogram in reference mode.
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

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.

Headers

x-cryptogram-reference

string<uuid>

required

The cryptogram_reference UUID returned by Request cryptogram in reference mode. Single-use and short-lived.

x-destination-url

string<uri>

required

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"

x-own-header-name

string

Name of a header to set on the forwarded request. Guardian strips the credential your call authenticates with (for example x-api-key) before forwarding; use this pair to send the destination's own credential instead. Only takes effect together with x-own-header-value.

Example:

"x-api-key"

x-own-header-value

string

Value for the header named by x-own-header-name, set on the forwarded request — typically your credential for the destination.

Example:

"sk_live_51Hxxxx"

Path Parameters

string<uuid>

required

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

Getting Started

Tokens

Metadata

Admin

Forward cryptogram

Authorizations

Headers

Path Parameters

Body

Response