Save Card API (Tokenization)

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

The Save Card service enables secure tokenization of customer payment card details, allowing merchants to process payments without handling sensitive card data directly. This service reduces PCI compliance requirements while providing customers with convenient one-click payment experiences and enabling recurring payment processing.

Read more about tokenization in our save card guide.

Tokenization Integration Options

Choose the integration method that best fits your business requirements and technical capabilities:

Hosted Checkout

Tokenization through secure Amazon Payment Services hosted checkout pages with minimal development effort.

Custom Integration

Full control over tokenization process with custom UI and advanced token management features.

Mobile Integration

Native mobile SDK integration for seamless in-app tokenization experiences.

Payment Links

Generate tokenization links for customers to save cards through secure web interfaces.

Hosted Checkout

Hosted checkout automatically handles card tokenization when the save card service is activated on your merchant account. Customers simply need to check the "Remember Me" option that appears automatically on the payment form. No additional development is required.

Custom Integration

When save card service is activated on your merchant account, custom integration automatically saves cards by default during payment processing. To prevent saving for specific transactions, include remember_me=NO in your payment parameters.

Mobile Integration

When save card service is activated on your merchant account, the Mobile SDK automatically displays a "Remember Me" checkbox on the payment form. Customers simply check this option to save their card details. No additional development is required.

Payment Links

When save card service is activated on your merchant account, Payment Links automatically display a "Remember Me" checkbox on the payment page. Customers simply check this option to save their card details. No additional development is required.

Update Saved Cards/Tokens

Once cards are saved through any of the integration methods above, you can update the saved card/token details, status, or rename tokens using the Update Token service. This service enables comprehensive token lifecycle management for all integration types.

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

Parameter
service_command   String Max: 20 Required Service operation command for token updates. Value: UPDATE_TOKEN Example. UPDATE_TOKEN
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings → Security Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens (-), underscores (_), and periods (.) allowed. Example. XYZ9239-yu898
language   String Max: 2 Required Response language for error messages and transaction descriptions. Values: en, ar Example. en
token_name   String Max: 100 Required Previously saved payment token for returning customers or generated token for future payments. Example. Op9Vmp
signature   String Max: 200 Required SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
card_holder_name   String Max: 50 Optional Name on the payment card used. Example. John Smith
currency   String Max: 3 Optional Three-letter ISO 4217 currency code. Example. AED
token_status   String Max: 8 Optional Updated status for the token. Values: ACTIVE, INACTIVE Example. ACTIVE
new_token_name   String Max: 100 Optional New name to replace the existing token name. Example. NewToken123

Check signature calculation section to learn how to calculate the signature.

Response Parameters

Parameter
service_command   String Max: 20 Service operation command from the request. Value: UPDATE_TOKEN Example. UPDATE_TOKEN
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   String Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
language   String Max: 2 Language used for the response. Example. en
token_name   String Max: 100 Previously saved payment token for returning customers or generated token for future payments. Example. Op9Vmp
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
expiry_date   String Max: 4 Masked card expiry date (MMYY format). Example. 2105
card_number   String Max: 19 Masked card number with only first 6 and last 4 digits visible. Example. 400555*****0001
card_holder_name   String Max: 50 Name on the payment card used. Example. John Smith
currency   String Max: 3 Currency code used for the transaction. Example. AED
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   Integer Max: 5 Numeric response code indicating transaction result. Example. 58000
token_status   String Max: 8 Current status of the token after update. Values: ACTIVE, INACTIVE Example. ACTIVE
creation_date   String Max: 30 Token creation date in UTC format. Example. 2017-03-13T10:09:19+02:00
card_brand   String Max: 10 Card brand associated with the token. Values: MASTERCARD, VISA, AMEX, MADA Example. VISA
card_bin   String Max: 8 First 6-8 digits of the card number (BIN - Bank Identification Number). Example. 478773
status   Integer Max: 2 Two-digit status code indicating transaction state. Example. 20

Token Update Request

{
  "service_command": "UPDATE_TOKEN",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "TOKEN-UPDATE-2024-001",
  "language": "en",
  "token_name": "Op9Vmp",
  "token_status": "ACTIVE",
  "card_holder_name": "John Smith Updated",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

import requests
import json

def update_saved_token():
    update_url = "https://sbpaymentservices.payfort.com/FortAPI/paymentApi"
    
    params = {
        'service_command': 'UPDATE_TOKEN',
        'access_code': 'zx0IPmPy5jp1vAz',
        'merchant_identifier': 'CycHZxVj',
        'merchant_reference': 'TOKEN-UPDATE-2024-001',
        'language': 'en',
        'token_name': 'Op9Vmp',
        'token_status': 'ACTIVE',
        'card_holder_name': 'John Smith Updated',
        'signature': '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
    }
    
    try:
        response = requests.post(
            update_url,
            json=params,
            headers={'Content-Type': 'application/json'},
            timeout=30
        )
        response.raise_for_status()
        result = response.json()
        
        if result.get('response_code') == '58000':
            print("Token updated successfully")
            return result
        else:
            print(f"Update 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
update_result = update_saved_token()

<?php

function updateSavedToken() {
    $updateUrl = 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi';
    
    $params = [
        'service_command' => 'UPDATE_TOKEN',
        'access_code' => 'zx0IPmPy5jp1vAz',
        'merchant_identifier' => 'CycHZxVj',
        'merchant_reference' => 'TOKEN-UPDATE-2024-001',
        'language' => 'en',
        'token_name' => 'Op9Vmp',
        'token_status' => 'ACTIVE',
        'card_holder_name' => 'John Smith Updated',
        'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $updateUrl);
    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'] === '58000') {
            echo "Token updated successfully\n";
            return $result;
        } else {
            echo "Update failed: " . ($result['response_message'] ?? 'Unknown error') . "\n";
            return $result;
        }
    } else {
        echo "HTTP Error: " . $httpCode . "\n";
        return false;
    }
}

// Usage
$updateResult = updateSavedToken();
?>

# Update saved token using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "service_command": "UPDATE_TOKEN",
    "access_code": "zx0IPmPy5jp1vAz",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "TOKEN-UPDATE-2024-001",
    "language": "en",
    "token_name": "Op9Vmp",
    "token_status": "ACTIVE",
    "card_holder_name": "John Smith Updated",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

Sample Response

{
  "service_command": "UPDATE_TOKEN",
  "access_code": "zx0IPmPy5jp1vAz",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "TOKEN-UPDATE-2024-001",
  "language": "en",
  "token_name": "Op9Vmp",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "expiry_date": "2105",
  "card_number": "400555*****0001",
  "card_holder_name": "John Smith Updated",
  "currency": "AED",
  "response_message": "Success",
  "response_code": "58000",
  "token_status": "ACTIVE",
  "creation_date": "2017-03-13T10:09:19+02:00",
  "card_brand": "VISA",
  "card_bin": "400555",
  "status": "58"
}

Response Codes

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