Network Tokens
Forward payment-data
This endpoint enables platform merchants to leverage payment-data bundles in their acquirer integration.
The request is forwarded to the configured destination URL of your merchant settings.
Commerce requires certain HTTP headers for this feature. These headers are reserved and cannot be used by the caller:
| Header | Required? | Description |
|---|---|---|
x-api-key | Yes | Authentication of the request. |
x-hellgate-version | No | Define the API version to use for the request. |
Refer to the general documentation about forwarding senstive data for more information.
POST
/
payment-data
/
{id}
/
forward
Forward payment-data
curl --request POST \
--url https://sandbox.hellgate.io/payment-data/{id}/forward \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"reference": "MAGIC DUST XYZ",
"amount": {
"value": "{{ amount }}",
"currency": "{{ currency_code }}"
},
"paymentMethod": {
"type": "networkToken",
"expiryMonth": "{{ expiration_month }}",
"expiryYear": "{{ expiration_year }}",
"holderName": "{{ cardholder_name }}",
"number": "{{ network_token }}"
},
"mpiData": {
"tokenAuthenticationVerificatioNValue": "{{ cryptogram }}",
"eci": "{{ eci }}"
},
"recurringProcessingModel": "CardOnFile",
"shopperInteraction": "Ecommerce"
}
'import requests
url = "https://sandbox.hellgate.io/payment-data/{id}/forward"
payload = {
"reference": "MAGIC DUST XYZ",
"amount": {
"value": "{{ amount }}",
"currency": "{{ currency_code }}"
},
"paymentMethod": {
"type": "networkToken",
"expiryMonth": "{{ expiration_month }}",
"expiryYear": "{{ expiration_year }}",
"holderName": "{{ cardholder_name }}",
"number": "{{ network_token }}"
},
"mpiData": {
"tokenAuthenticationVerificatioNValue": "{{ cryptogram }}",
"eci": "{{ eci }}"
},
"recurringProcessingModel": "CardOnFile",
"shopperInteraction": "Ecommerce"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference: 'MAGIC DUST XYZ',
amount: {value: '{{ amount }}', currency: '{{ currency_code }}'},
paymentMethod: {
type: 'networkToken',
expiryMonth: '{{ expiration_month }}',
expiryYear: '{{ expiration_year }}',
holderName: '{{ cardholder_name }}',
number: '{{ network_token }}'
},
mpiData: {tokenAuthenticationVerificatioNValue: '{{ cryptogram }}', eci: '{{ eci }}'},
recurringProcessingModel: 'CardOnFile',
shopperInteraction: 'Ecommerce'
})
};
fetch('https://sandbox.hellgate.io/payment-data/{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://sandbox.hellgate.io/payment-data/{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([
'reference' => 'MAGIC DUST XYZ',
'amount' => [
'value' => '{{ amount }}',
'currency' => '{{ currency_code }}'
],
'paymentMethod' => [
'type' => 'networkToken',
'expiryMonth' => '{{ expiration_month }}',
'expiryYear' => '{{ expiration_year }}',
'holderName' => '{{ cardholder_name }}',
'number' => '{{ network_token }}'
],
'mpiData' => [
'tokenAuthenticationVerificatioNValue' => '{{ cryptogram }}',
'eci' => '{{ eci }}'
],
'recurringProcessingModel' => 'CardOnFile',
'shopperInteraction' => 'Ecommerce'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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://sandbox.hellgate.io/payment-data/{id}/forward"
payload := strings.NewReader("{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://sandbox.hellgate.io/payment-data/{id}/forward")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hellgate.io/payment-data/{id}/forward")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\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": 407,
"message": "Proxy authentication required",
"classifier": "PROXY_AUTHENTICATION_REQUIRED"
}{
"code": 502,
"message": "Bad gateway",
"classifier": "BAD_GATEWAY"
}{
"code": 503,
"message": "Service unavailable",
"classifier": "SERVICE_UNAVAILABLE"
}{
"code": 504,
"message": "Gateway timeout",
"classifier": "GATEWAY_TIMEOUT"
}Gated Feature
Authorizations
Path Parameters
The ID of the payment-data bundle
Body
application/jsonapplication/x-www-form-urlencoded
The payload the caller wants to forward to the third party provider.
To securely handle and inject sensitive token data, predefined templates can be used. These templates help structure and standardize the data injection process while ensuring compliance with security and regulatory requirements.
| Placeholder | Type | Description |
|---|---|---|
{{ network_token }} | string | The Token-Pan (TPAN) of the network token. |
{{ cardholder_name }} | string | The name of the cardholder. |
{{ expiration_year }} | number | Four digit year of the expiration date. |
{{ expiration_month }} | number | Two digit month of the expiration date. |
{{ cryptogram }} | string | The token authentication verification value TAVV. |
{{ dynamic_cvv }} | string | The dynamic CVV, when present instead of a TAVV. |
{{ eci }} | string | The ECI associated with the payment-data bundle. |
{{ amount }} | number | The authenticated amount given in minor units. |
{{ currency_code }} | string | The currency code of the authenticated amount. |
Placeholder of type number can be unwrapped from the standard string representation.
Response
Success response
The response from the third party provider.
⌘I
Forward payment-data
curl --request POST \
--url https://sandbox.hellgate.io/payment-data/{id}/forward \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"reference": "MAGIC DUST XYZ",
"amount": {
"value": "{{ amount }}",
"currency": "{{ currency_code }}"
},
"paymentMethod": {
"type": "networkToken",
"expiryMonth": "{{ expiration_month }}",
"expiryYear": "{{ expiration_year }}",
"holderName": "{{ cardholder_name }}",
"number": "{{ network_token }}"
},
"mpiData": {
"tokenAuthenticationVerificatioNValue": "{{ cryptogram }}",
"eci": "{{ eci }}"
},
"recurringProcessingModel": "CardOnFile",
"shopperInteraction": "Ecommerce"
}
'import requests
url = "https://sandbox.hellgate.io/payment-data/{id}/forward"
payload = {
"reference": "MAGIC DUST XYZ",
"amount": {
"value": "{{ amount }}",
"currency": "{{ currency_code }}"
},
"paymentMethod": {
"type": "networkToken",
"expiryMonth": "{{ expiration_month }}",
"expiryYear": "{{ expiration_year }}",
"holderName": "{{ cardholder_name }}",
"number": "{{ network_token }}"
},
"mpiData": {
"tokenAuthenticationVerificatioNValue": "{{ cryptogram }}",
"eci": "{{ eci }}"
},
"recurringProcessingModel": "CardOnFile",
"shopperInteraction": "Ecommerce"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference: 'MAGIC DUST XYZ',
amount: {value: '{{ amount }}', currency: '{{ currency_code }}'},
paymentMethod: {
type: 'networkToken',
expiryMonth: '{{ expiration_month }}',
expiryYear: '{{ expiration_year }}',
holderName: '{{ cardholder_name }}',
number: '{{ network_token }}'
},
mpiData: {tokenAuthenticationVerificatioNValue: '{{ cryptogram }}', eci: '{{ eci }}'},
recurringProcessingModel: 'CardOnFile',
shopperInteraction: 'Ecommerce'
})
};
fetch('https://sandbox.hellgate.io/payment-data/{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://sandbox.hellgate.io/payment-data/{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([
'reference' => 'MAGIC DUST XYZ',
'amount' => [
'value' => '{{ amount }}',
'currency' => '{{ currency_code }}'
],
'paymentMethod' => [
'type' => 'networkToken',
'expiryMonth' => '{{ expiration_month }}',
'expiryYear' => '{{ expiration_year }}',
'holderName' => '{{ cardholder_name }}',
'number' => '{{ network_token }}'
],
'mpiData' => [
'tokenAuthenticationVerificatioNValue' => '{{ cryptogram }}',
'eci' => '{{ eci }}'
],
'recurringProcessingModel' => 'CardOnFile',
'shopperInteraction' => 'Ecommerce'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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://sandbox.hellgate.io/payment-data/{id}/forward"
payload := strings.NewReader("{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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://sandbox.hellgate.io/payment-data/{id}/forward")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hellgate.io/payment-data/{id}/forward")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference\": \"MAGIC DUST XYZ\",\n \"amount\": {\n \"value\": \"{{ amount }}\",\n \"currency\": \"{{ currency_code }}\"\n },\n \"paymentMethod\": {\n \"type\": \"networkToken\",\n \"expiryMonth\": \"{{ expiration_month }}\",\n \"expiryYear\": \"{{ expiration_year }}\",\n \"holderName\": \"{{ cardholder_name }}\",\n \"number\": \"{{ network_token }}\"\n },\n \"mpiData\": {\n \"tokenAuthenticationVerificatioNValue\": \"{{ cryptogram }}\",\n \"eci\": \"{{ eci }}\"\n },\n \"recurringProcessingModel\": \"CardOnFile\",\n \"shopperInteraction\": \"Ecommerce\"\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": 407,
"message": "Proxy authentication required",
"classifier": "PROXY_AUTHENTICATION_REQUIRED"
}{
"code": 502,
"message": "Bad gateway",
"classifier": "BAD_GATEWAY"
}{
"code": 503,
"message": "Service unavailable",
"classifier": "SERVICE_UNAVAILABLE"
}{
"code": 504,
"message": "Gateway timeout",
"classifier": "GATEWAY_TIMEOUT"
}