Server to Server Vault tokenization

Server to Server tokenization with Hyperswitch Vault Service for PCI compliant merchants

Secure, Direct Card Tokenization from Your Server

Tokenize payment cards directly from your servers to Hyperswitch's Vault Service, bypassing client-side tokenization. This server-to-server approach provides enhanced security and flexibility, ideal for PCI-compliant businesses managing payment methods programmatically.

Key Features

Full Token Management – Create, retrieve, update, and delete payment tokens directly from your server.
PSP and Network Tokenization – Generate both PSP tokens and network tokens through a single API.
Secure Storage – Store tokens safely in Hyperswitch’s Vault.
Reduced Frontend Complexity – Shift tokenization processes to the backend, minimizing frontend dependencies.

Prerequisites

To implement server-to-server tokenization, you need:

PCI DSS compliance to handle card data securely: Make sure you have necessary PCI compliance to handle raw card data directly
Secure API authentication to protect transactions: Generate your Hyperswitch API key from Developers --> API Keys section on your Hyperswitch dashboard
Robust error handling for tokenization failures: Implement necessary handling for failure cases

How It Works

Collect Card Details – Your server collects card details (requires PCI compliance).
Send a Tokenization Request – Make a POST request to /payment_methods with the card details.
Token Creation & Validation – Hyperswitch validates the request and generates a secure token in the vault.
PSP & Network Tokenization (Optional) – If configured through your Hyperswitch dashboard, we also generate PSP and/or network tokens when you pass relevant parameters as mentioned below
Receive Payment Method ID – You get a pm_id, which can be used for future payments.

API Requests for Server to Server Tokenization

1. Create a Customer

Endpoint: POST /customers
Purpose: Create a customer to enable storing their payment methods

curl --location 'http://sandbox.hyperswitch.io/v2/customers' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api_key>' \
--data-raw '{   
    "merchant_reference_id": "customer_1742551597",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "999999999",
    "phone_country_code": "+65",
    "description": "First customer",
    "default_billing_address": {
        "line1": "1467",
        "line2": "Harrison Street",
        "line3": "Harrison Street",
        "city": "San Fransico",
        "state": "California",
        "zip": "94122",
        "country": "US",
        "first_name": "joseph",
        "last_name": "Doe"
    },
    "default_shipping_address": {
        "line1": "1467",
        "line2": "Harrison Street",
        "line3": "Harrison Street",
        "city": "San Fransico",
        "state": "California",
        "zip": "94122",
        "country": "US",
        "first_name": "joseph",
        "last_name": "Doe"
    },
    "metadata": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}'

2. Create a Payment Method Token

Endpoint: POST /payment_methods
Purpose: Generate a token for a card

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "credit",
  "metadata": {},
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
"card": {
   "card_number": "4111111145551142",
   "card_exp_month": "10",
   "card_exp_year": "25",
   "card_holder_name": "John Doe",
   "nick_name": "John Doe",
   "card_issuing_country": "AF",
   "card_network": "Visa",
   "card_issuer": "<string>",
   "card_type": "credit",
   "card_cvc": "242"
}
  },
  "billing": {
"address": {
   "city": "New York",
   "country": "AF",
   "line1": "123, King Street",
   "line2": "Powelson Avenue",
   "line3": "Bridgewater",
   "zip": "08807",
   "state": "New York",
   "first_name": "John",
   "last_name": "Doe"
},
"phone": {
   "number": "9123456789",
   "country_code": "+1"
},
"email": "[email protected]"
  }
}'

a. Creating a Payment Method Token along with PSP Tokens

Use the same endpoint to generate PSP tokens for a card by passing the following parameters:

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "metadata": {},
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
	"card": {
  	"card_number": "4111111145551142",
  	"card_exp_month": "10",
  	"card_exp_year": "25",
  	"card_holder_name": "John Doe",
  	"nick_name": "John Doe",
  	"card_issuing_country": "AF",
  	"card_network": "Visa",
  	"card_issuer": "<string>",
  	"card_type": "credit",
  	"card_cvc": "242"
	}
  },
  "billing": {
	"address": {
  	"city": "New York",
  	"country": "AF",
  	"line1": "123, King Street",
  	"line2": "Powelson Avenue",
  	"line3": "Bridgewater",
  	"zip": "08807",
  	"state": "New York",
  	"first_name": "John",
  	"last_name": "Doe"
	},
	"phone": {
  	"number": "9123456789",
  	"country_code": "+1"
	},
	"email": "[email protected]"
  },
  "psp_tokenization": {
	"tokenization_type": "single_use",
	"connector_id": "<string>"
  }
}'

b. Creating a Payment Method Token along with Network Tokens

Use the same endpoint to generate network tokens for a card by passing the following parameters:

curl --location 'https://sandbox.hyperswitch.io/v2/payment-methods' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "metadata": {},
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "payment_method_data": {
	"card": {
  	"card_number": "4111111145551142",
  	"card_exp_month": "10",
  	"card_exp_year": "25",
  	"card_holder_name": "John Doe",
  	"nick_name": "John Doe",
  	"card_issuing_country": "AF",
  	"card_network": "Visa",
  	"card_issuer": "<string>",
  	"card_type": "credit",
  	"card_cvc": "242"
	}
  },
  "billing": {
	"address": {
  	"city": "New York",
  	"country": "AF",
  	"line1": "123, King Street",
  	"line2": "Powelson Avenue",
  	"line3": "Bridgewater",
  	"zip": "08807",
  	"state": "New York",
  	"first_name": "John",
  	"last_name": "Doe"
	},
	"phone": {
  	"number": "9123456789",
  	"country_code": "+1"
	},
	"email": "<string>"
  },
  "network_tokenization": {
	"enable": "Enable"
  }
}'

2. Retrieve a Payment Method Token

Endpoint: GET /payment_methods/:pm_id
Purpose: Fetch details of an existing token.

curl --location --globoff 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>'

3. Update a Payment Method Token

Endpoint: PATCH /payment_methods/:pm_id/update_saved_payment_method
Purpose: Modify token details.

curl --location --globoff --request PATCH 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}/update-saved-payment-method' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>' \
--data '{
  "payment_method_data": {
	"card": {
  	"card_holder_name": "John Doe",
  	"nick_name": "John Doe"
	}
  },
  "connector_token_details": {
	"token": "pm_9UhMqBMEOooRIvJFFdeW",
	"connector_token_request_reference_id": "<string>"
  }
}'

4. Delete a Payment Method Token

Endpoint: DELETE /payment_methods/:pm_id
Purpose: Remove a token from the vault.

curl --location --globoff --request DELETE 'https://sandbox.hyperswitch.io/v2/payment-methods/{id}' \
--header 'x-profile-id: <profile-id>' \
--header 'api-key: <api-key>'

Last updated 4 months ago

Was this helpful?