Network Tokenization API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

Network Tokenization provides enhanced security and improved authorization rates by replacing sensitive card data with network-issued tokens. These tokens are uniquely tied to specific merchants and include dynamic cryptograms for each transaction, offering superior protection against fraud while maintaining seamless payment experiences.

Network Tokenization is only available for PCI-certified merchants implementing PCI-certified custom integration.

Prerequisites

Before implementing external network tokenization with Amazon Payment Services, merchants must complete the following prerequisites:

Account Setup Requirements

1. Service Activation: Ensure that external network tokenization is activated on your merchant account.

2. Token Authority Integration: Complete integration with the external token authority service provided by the card scheme (Visa, Mastercard, etc.).

3. PAN Provisioning: Provision the Primary Account Numbers (PANs) to obtain the corresponding network tokens from the card schemes.

4. Cryptogram Generation: Implement capability to generate cryptograms for the network tokens prior to sending them to Amazon Payment Services.

5. Webhook Configuration: Set up a notification webhook to receive updates from the schemes regarding any changes to card or token statuses.

Network tokenization requires additional integration with card scheme token authorities. Contact your Amazon Payment Services integration team for setup assistance.

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

https://paymentservices.payfort.com/FortAPI/paymentApi

Request Format

• Method: POST
• Content-Type: application/json
• Submission: Server-to-server HTTPS POST

Request Parameters

Use the same parameters as PCI-certified custom integration with the addition of the network_token object:

Network Token Object

Parameter
token   String Max: 19 Required Network token issued by the card scheme authority. Example. 4000000000001234
token_expiry_date   String Max: 4 Required Network token expiry date in YYMM format. Example. 2512
token_cryptogram   String Max: 40 Required Base64-encoded cryptogram generated by the card network for this specific transaction. Must be unique for each transaction. Example. AgAAAAAAAIR8CQrXcIhbQAAAAAA=

The token_cryptogram is a one-time-use security code generated by the card network (Visa, Mastercard) when using a network token for a transaction. It must be unique for each transaction even with the same network token. Maximum length is approximately 28-40 characters when base64-encoded.

Network Tokenization Sample Request

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "ORD-2024-001",
  "amount": "25000",
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "recurring_mode": "UNSCHEDULED",
  "agreement_id": "AGR123",
  "card_number": "4005550000000001",
  "expiry_date": "2512",
  "card_security_code": "123",
  "network_token": {
    "token": "4000000000001234",
    "token_expiry_date": "2512",
    "token_cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
  },
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

import requests
import json

def process_cit_network_token():
    api_url = "https://sbpaymentservices.payfort.com/FortAPI/paymentApi"
    
    # CIT payment with network tokenization
    params = {
        'command': 'PURCHASE',
        'access_code': 'zx0IPmPy5jp1vAz8Kpg7',
        'merchant_identifier': 'CycHZxVj',
        'merchant_reference': 'ORD-2024-001',
        'amount': '25000',  # AED 250.00
        'currency': 'AED',
        'language': 'en',
        'customer_email': 'customer@example.com',
        'recurring_mode': 'UNSCHEDULED',
        'agreement_id': 'AGR123',
        'card_number': '4005550000000001',
        'expiry_date': '2512',
        'card_security_code': '123',
        'network_token': {
            'token': '4000000000001234',
            'token_expiry_date': '2512',
            'token_cryptogram': 'AgAAAAAAAIR8CQrXcIhbQAAAAAA='
        },
        'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
    }
    
    try:
        response = requests.post(
            api_url,
            json=params,
            headers={'Content-Type': 'application/json'},
            timeout=30
        )
        response.raise_for_status()
        result = response.json()
        
        if result.get('response_code') == '14000':
            print("CIT network tokenization payment successful")
            # Store network token for future MIT transactions
            return result
        else:
            print(f"Payment failed: {result.get('response_message', 'Unknown error')}")
            return result
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {str(e)}")
        return {'success': False, 'error': str(e)}

# Usage example
cit_result = process_cit_network_token()

<?php

function processCitNetworkToken() {
    $apiUrl = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
    
    // CIT payment with network tokenization
    $params = [
        'command' => 'PURCHASE',
        'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
        'merchant_identifier' => 'CycHZxVj',
        'merchant_reference' => 'ORD-2024-001',
        'amount' => '25000', // AED 250.00
        'currency' => 'AED',
        'language' => 'en',
        'customer_email' => 'customer@example.com',
        'recurring_mode' => 'UNSCHEDULED',
        'agreement_id' => 'AGR123',
        'card_number' => '4005550000000001',
        'expiry_date' => '2512',
        'card_security_code' => '123',
        'network_token' => [
            'token' => '4000000000001234',
            'token_expiry_date' => '2512',
            'token_cryptogram' => 'AgAAAAAAAIR8CQrXcIhbQAAAAAA='
        ],
        'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        $result = json_decode($response, true);
        if ($result['response_code'] === '14000') {
            echo "CIT network tokenization payment successful\n";
            // Store network token for future MIT transactions
            return $result;
        } else {
            echo "Payment failed: " . ($result['response_message'] ?? 'Unknown error') . "\n";
            return $result;
        }
    } else {
        echo "HTTP Error: " . $httpCode . "\n";
        return false;
    }
}

// Usage
$citResult = processCitNetworkToken();
?>

# CIT payment with network tokenization using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "command": "PURCHASE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "ORD-2024-001",
    "amount": "25000",
    "currency": "AED",
    "language": "en",
    "customer_email": "customer@example.com",
    "recurring_mode": "UNSCHEDULED",
    "agreement_id": "AGR123",
    "card_number": "4005550000000001",
    "expiry_date": "2512",
    "card_security_code": "123",
    "network_token": {
      "token": "4000000000001234",
      "token_expiry_date": "2512",
      "token_cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
    },
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

Sample Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "ORD-2024-001",
  "amount": "25000",
  "currency": "AED",
  "language": "en",
  "customer_email": "customer@example.com",
  "fort_id": "149295435400084008",
  "payment_option": "VISA",
  "response_message": "Success",
  "response_code": "14000",
  "status": "14",
  "network_token": {
    "token": "4000000000001234",
    "token_expiry_date": "2512",
    "token_cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
  },
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

Response Parameters

Network tokenization returns the same response parameters as PCI-certified custom integration with the additional network_token parameter object containing the tokenization details used in the transaction.

Additional Response Parameters

Parameter
network_token   Object Network token object containing the tokenization details used in the transaction. Example. See network_token object below
token   String Max: 19 Network token that was used in the transaction. Example. 4000000000001234
token_expiry_date   String Max: 4 Network token expiry date in YYMM format. Example. 2512
token_cryptogram   String Max: 40 Base64-encoded cryptogram that was used for this transaction. Example. AgAAAAAAAIR8CQrXcIhbQAAAAAA=

Testing The Integration

Use the sandbox environment for development and testing:

• Payment API URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

When ready to move to production, follow our Go-Live checklist for complete production readiness guidelines.

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.