NetValve Tokens and Usage

Tokens in payment processing are secure, non-sensitive representations of sensitive financial information such as credit card numbers or bank account details. Instead of storing or transmitting the actual card or bank details, a token is used—this enhances security and helps with compliance (such as PCI DSS).

Token Description

A token is a randomly generated string or number that stands in for the real data.

It is created by the payment gateway when you send payment details — either from your website, app, or POS system.

The token is linked to the sensitive data on the gateway’s secure servers and can only be used by authorized systems.

Usage of Tokens

Payment Transactions: Use the token to process payments without ever handling the actual card information again.
Recurring Payments/Subscriptions: Store the token for recurring billing. The customer’s info remains safe; you use the token for future charges.
Reduced PCI Scope: Your business doesn’t have to store sensitive data; only tokens, which are useless if stolen, reducing your compliance burden.

You create a token that represents your payment data (such as card details) securely, and then use that token to make payments or perform transactions without repeatedly exposing sensitive information.

Here’s a typical flow for token creation and usage:

Option 1: Token Creation (Standalone) With Card Verification

This option allows you to create the token and validates the card by performing 0$ authorization with the issuing bank.

Request

Example Request
curl --location 'https://payment-api.uat.sandbox-netvalve.com/createToken' \
--header 'Content-Type: application/json' \
--header 'netvalve-client-id: AAAA-BBB-CCCCC-DDDD-e9adsad6d7c705' \
--header 'netvalve-api-key: XXXXXXXXXX' \
--data '{
 "cardExpireMonth": "12",
 "cardExpireYear": "2030",
 "cardSecurityCode": "123",
 "cardHolderName": "John Doe",
 "cardNumber": "4012000098765439",
 "currency": "USD",
 "netvalveMidId": "AAAA-YYYYY-4613-b067-29320f131686",
 "verify":true
}'

Response

Example Response
{
    "traceID": "2a7efd6b-8769-418c-bddf-6e6e64877a6a",
    "responseTimestamp": "2025-08-28T13:48:33.380+00:00",
    "transactionID": 39725,
    "responseCode": "GTW_1000",
    "responseMessage": "Transaction Approved/ Request Successful.",
    "responseCodeType": "APPROVED",
    "paymentMethod": "CARD",
    "cardNumber": "601100******6909",
    "cardType": "DISCOVER",
    "bankTransactionId": "524013758071",
    "authCode": "DSC986",
    "midId": aaa,
    "netvalveMidId": "AAAA-YYYYY-4613-b067-29320f131686",
    "cardExpiryMonth": "12",
    "cardExpiryYear": "2025",
    "paymentToken": "23ee9bf0-0270-4752-8ced-a47a8ceeccc",
    "paymentTokenType": "GATEWAY_TOKEN",
    "transactionType": "AUTHORIZATION"
}

Option 2: Token Creation (Standalone) Without Card Verification

This option allows you to create the token with basic card validation but card number will not be verified with the card issuer.

Request

Example Request
curl --location 'https://payment-api.uat.sandbox-netvalve.com/createToken' \
--header 'Content-Type: application/json' \
--header 'netvalve-client-id: xxxxx-yyyy-460e-a50a-e9asdadasd' \
--header 'netvalve-api-key: adasdadasdads' \
--data '{
 "cardExpireMonth": "12",
 "cardExpireYear": "2030",
 "cardSecurityCode": "123",
 "cardHolderName": "John Doe",
 "cardNumber": "4012000098765439",
 "clientId": 1034,
 "currency": "USD",
 "netvalveMidId": "cccccddd-f955-4e29-a2c7-aaaaaa",
 "verify":false
}'

Response

Example Response
{
    "traceID": "5640a739-0cab-4415-be25-e500e2ad3909",
    "responseTimestamp": "2025-11-18T09:23:09.292+00:00",
    "responseCode": "GTW_1000",
    "paymentToken": "f537d00b-877f-4504-a8ae-f66e8f509609",
    "paymentTokenType": "GATEWAY_TOKEN"
}

Option 3: Token Creation as part of Auth/Sale

This option allows you to create the tokens as part of the Auth/Sale transactions.

Endpoint: paymentApiUrl/sale

Request

Example Request Body
{
    "amount": 12.00,
    "cardExpireMonth": "12",
    "cardExpireYear": "2030",
    "cardHolderName": "John Doe",
    "cardSecurityCode": "123",
    "cardNumber": "4012000098765439",
    "clientOrderId": "YD_{{clientOrderId}}",
    "currency": "USD",
    "customerAddress": "123 Main St",
    "customerCity": "New York",
    "customerCountryCode": "US",
    "customerEmail": "docs@netvalve.com",
    "customerIp": "203.0.113.1",
    "customerName": "John",
    "customerLastName": "Doe",
    "customerPhone": "+12025551234",
    "customerState": "NY",
    "customerZipCode": "10001",
    "netvalveMidId": "{{netvalveMidId}}"
}

Response

Example Response
{
    "traceID": "49e90eb9-55f8-497c-b4b2-eb8574deb204",
    "responseTimestamp": "2025-11-18T09:26:25.898+00:00",
    "transactionID": 64023,
    "responseCode": "GTW_1000",
    "responseMessage": "Transaction Approved/ Request Successful.",
    "responseCodeType": "APPROVED",
    "paymentMethod": "CARD",
    "cardNumber": "401200******5439",
    "cardType": "VISA",
    "bankTransactionId": "532209502238",
    "authCode": "TAS757",
    "midId": AAAA,
    "netvalveMidId": "aaaaaa-69f2-4e2e-b75e-aaaaaa",
    "cardExpiryMonth": "12",
    "cardExpiryYear": "2025",
    "paymentToken": "38a5f789-7ca8-45c4-bc9f-1114d2d706b",
    "paymentTokenType": "GATEWAY_TOKEN",
    "transactionType": "SALE"
}

Comparison

Method	Card Verification	Typical Usage	Response Token Type
Standalone Token Create (verify:true)	Yes	First-time tokenization	GATEWAY_TOKEN
Standalone Token Create (verify:false)	No	Fast/tokenize-only	GATEWAY_TOKEN
Part of Auth/Sale	Yes	Immediate charge + token	GATEWAY_TOKEN

Token Usage

Payment Using a Token

When you want to process a payment, you can send the token (instead of raw card data) to NetValve payment endpoint.
NetValve validates the token and processes the transaction against the underlying card/bank account.

Customer Initiated Transaction with Token

Endpoint: paymentApiUrl/sale

Example Request Body
{
    "amount": 1.00,
    "clientOrderId": "WR_{{clientOrderId}}",  // Your order id
    "cardHolderName": "John Doe",   // Card holder name
    "customerName": "John",
    "customerLastName": "Doe",
    "currency": "EUR",
    "cardSecurityCode": 999,    // Card CVV
    "netvalveMidId": "d9246149-e9b9-4e9a-8e96-9c733878f339",
    "additionalData": {
        "requestTransactionType": "ECOMMERCE",
        "schemeTransactionLinkIdentifier": "mastercard-tlid-if-available"
    },
    "paymentType": "TOKEN",
    "paymentToken": "13104873-646d-459c-aa63-d9bc6d4ad697"
}

For Mastercard card-on-file transactions, include additionalData.schemeTransactionLinkIdentifier when your system already has the Mastercard Transaction Link Identifier (TLID). NetValve also links a returned Mastercard TLID with the tokenized card when the processor provides it, so it can be reused for later CIT/MIT requests when available.

Do not send CIT or MIT in credentialOnFileTransaction

additionalData.credentialOnFileTransaction is not a CIT/MIT flag. It holds the Network Transaction ID of the original customer-initiated transaction and is only used when linking a merchant-initiated (MIT) payment to that earlier transaction. Passing a literal value such as CIT is forwarded to the processor as the transaction reference and causes the payment to be declined.

For a customer-initiated payment with a token, omit the field entirely. For merchant-initiated payments NetValve looks up the original Network Transaction ID from the card's earlier transactions automatically. Only send credentialOnFileTransaction when the original transaction was processed outside NetValve and you hold its Network Transaction ID. To flag CIT vs MIT, use requestTransactionType, recurringScheduleType and recurrenceMode as described in CIT and MIT Transactions.

Bank/Processor Tokens

Merchants can also opt for using bank/processor tokens. In this option the bank/processor stores the card securely and shares a transaction ID or token for processing.

In this model, NetValve will be storing the details internally and the merchant will be using the Rebill API to process recurring/subscription payments:

Step 1: Auth/Sale to create the bank token.

For rebill, call the Rebill API with the amount.

Tokens Advantages

Enhanced security: Sensitive card info is never transmitted after the first tokenization.
Compliance: Easier to comply with PCI DSS and other security standards.
User Experience: Faster repeat payments—user doesn’t need to re-enter details.

CIT and MIT Framework

Visa and Mastercard has CIT/MIT framework which is required for recurring or subscription transactions.

Refer to the Customer Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT) document.

Token Description​

Usage of Tokens​

Option 1: Token Creation (Standalone) With Card Verification​

Option 2: Token Creation (Standalone) Without Card Verification​

Option 3: Token Creation as part of Auth/Sale​

Comparison​

Token Usage​

Payment Using a Token​

Customer Initiated Transaction with Token​

Bank/Processor Tokens​

Tokens Advantages​

CIT and MIT Framework​

Token Description

Usage of Tokens

Option 1: Token Creation (Standalone) With Card Verification

Option 2: Token Creation (Standalone) Without Card Verification

Option 3: Token Creation as part of Auth/Sale

Comparison

Token Usage

Payment Using a Token

Customer Initiated Transaction with Token

Bank/Processor Tokens

Tokens Advantages

CIT and MIT Framework