Network tokens are digital representations of credit card numbers issued by payment networks like Visa and Mastercard.

They replace actual card data during transactions, enhancing security by reducing exposure to fraud and reducing the merchant’s PCI scope. An additional benefit is that card schemes update tokens automatically if the card is expired, lost, or replaced. It means that network tokens can improve approval rates!

PPRO supports two ways to utilize Network Tokens:

Merchant Managed: You provide the CARD_NETWORK_TOKEN and the cryptogram in the payment request.
PPRO Managed: PPRO automatically handles the enrollment, storage, and lifecycle management of network tokens. You simply provide raw card data or a PPRO Vaulted instrument, and we handle the rest.

Supported countries:

Argentina	Brazil	Chile	Colombia	Mexico	Peru
Not Supported	Supported	Supported	Supported	Not Supported	Supported

A. Merchant Managed Network Tokens:

Step 1: The merchant tokenises the card using a third-party provider or directly with the card schemes.
Step 2: Make an initial network token payment, including the cryptogram (mandatory) and flagging that this is a Customer-Initiated Transaction (CIT).
Step 3: Make a subsequent payment using PPRO’s instrument or the network token, where the cryptogram is now optional, flagging the transaction as Merchant-Initiated Transaction (MIT).

Request fields:

Property	Requirement	Type	Description
instrument.details.brand	Mandatory	String	Valid options: VISA, MASTER
instrument.details.holderName	Mandatory	String	Card holder's full name
instrument.details.expiryMonth	Mandatory	int32	1-2 digit integer number representing the Network Token expiration month (e.g. 1,..., 4,..., 12)
instrument.details.expiryYear	Mandatory	int32	4 digit integer number representing the Network Token expiration year (e.g. 2032)
instrument.details.tokenNumber	Mandatory	String	Network Token Number
instrument.details.cryptogram	Conditional	String (Base64)	The unique cryptogram generated by the issuer for the network token in use in the transaction. Mandatory for CIT, optional for MIT.
instrument.details.eci	Optional	String	The electronic commerce indicator from the card issuer
authorizations.schemeAuthorizationReference	Conditional	String	Received on the initial transaction. Mandatory for subsequent transactions.

Making an initial network token payment (CIT) with external network token

A one-time payment, the initial payment of a subscription, or the first payment in an unscheduled agreement using network tokens must be sent along with the card on file parameters initiator = "CONSUMER" and scheduleType = "RECURRING" or "UNSCHEDULED".

The token's cryptogram in this case is mandatory.

In the response, you'll receive the Network Transaction Identifier (NTI), that should be sent in subsequent transactions through authorizations.schemeAuthorizationReference. It means that this field must be stored by the merchant.

Example: CIT request with external network token

curl --location 'https://api.sandbox.eu.ppro.com/v1/payment-charges' \
--header 'Content-Type: application/json' \
--header 'Merchant-Id: ******' \
--header 'Request-Idempotency-Key: b691ff08-dea5-4b66-98ea-8d8bb82a568c' \
--header 'Authorization: Bearer ********' \
--data-raw '{
    "paymentMethod": "CARD",
    "autoCapture": true,
    "initiator": "CONSUMER",
    "scheduleType": "RECURRING",
    "instrument": {
        "type": "CARD_NETWORK_TOKEN",
        "details": {
            "brand": "MASTER",
            "holderName": "Tony Stark",
            "expiryMonth": 12,
            "expiryYear": 2025,
            "tokenNumber": "4111111111111111",
            "cryptogram": "CCADBxYzRTBBXXXXXXXYZa0AbZD=",
						"eci":"07"
        }
    },
    "amount": {
        "value": 100000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    
    "paymentDescriptor": "Avengers"
}'

{
    "id": "charge_BuAbK4DjkbRdRxwlMMNwf",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "CONSUMER",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_bopjY4noLpPfmHgheBnPR",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "US",
    "paymentDescriptor": "Avengers",
    "status": "CAPTURED",
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "authorizations": [
        {
            "id": "authz_pjrYD8Q19pfsEBvvvfinl",
            "amount": 100000,
            "status": "AUTHORIZED",
            "schemeAuthorizationReference": "060720116005060",
            "createdAt": "2025-06-05T14:54:49.171Z",
            "updatedAt": "2025-06-05T14:54:49.171Z"
        }
    ],
    "captures": [
        {
            "id": "capture_uVpySnDQGOPHkX5ZXUm2f",
            "amount": 100000,
            "status": "CAPTURED",
            "createdAt": "2025-06-05T14:54:49.171Z",
            "updatedAt": "2025-06-05T14:54:49.171Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-06-05T14:54:48.217Z",
    "updatedAt": "2025-06-05T14:54:49.171Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_BuAbK4DjkbRdRxwlMMNwf/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_BuAbK4DjkbRdRxwlMMNwf/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_BuAbK4DjkbRdRxwlMMNwf/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_BuAbK4DjkbRdRxwlMMNwf/voids"
        }
    }
}

Making a subsequent payment (MIT)

The subsequent payment of a subscription using network tokens must be sent along with the card on file parameters initiator = "MERCHANT" and scheduleType = "RECURRING".

The token's cryptogram in this case is optional.

In the request, you must also include the Network Transaction Identifier (NTI), received on the initial payment, in the payment request through initialSchemeAuthorizationReference.

Example: MIT subsequent request with external network token

curl --location 'https://api.sandbox.eu.ppro.com/v1/payment-charges' \
--header 'Content-Type: application/json' \
--header 'Merchant-Id: ******' \
--header 'Request-Idempotency-Key: b691ff08-dea5-4b66-98ea-8d8bb82a568c' \
--header 'Authorization: Bearer ********' \
--data-raw '{
    "paymentMethod": "CARD",
    "autoCapture": true,
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "initialSchemeAuthorizationReference": "060720116005060",
    "instrument": {
        "type": "CARD_NETWORK_TOKEN",
        "details": {
            "brand": "MASTER",
            "holderName": "Tony Stark",
            "expiryMonth": 12,
            "expiryYear": 2025,
            "tokenNumber": "4111111111111111"
        }
    },
    "amount": {
        "value": 100000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    
    "paymentDescriptor": "Avengers"
}'

{
    "id": "charge_m0425R7HlkOOpleJc5OhH",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_AEe61s0Kwh8yZ8xV1ihgW",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "US",
    "paymentDescriptor": "Avengers",
    "networkTransactionIdentifier": "060720116005061",
    "status": "CAPTURED",
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "authorizations": [
        {
            "id": "authz_gzgNQB8EjAsKwhWkLzs98",
            "amount": 100000,
            "status": "AUTHORIZED",
            "schemeAuthorizationReference": "060720116005061",
            "createdAt": "2025-06-05T19:06:57.395Z",
            "updatedAt": "2025-06-05T19:06:57.395Z"
        }
    ],
    "captures": [
        {
            "id": "capture_hpYaw425rO1JDKQiRuvCt",
            "amount": 100000,
            "status": "CAPTURED",
            "createdAt": "2025-06-05T19:06:57.395Z",
            "updatedAt": "2025-06-05T19:06:57.395Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-06-05T19:06:56.394Z",
    "updatedAt": "2025-06-05T19:06:57.395Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/voids"
        }
    }
}

B. PPRO Managed Network Tokens

With PPRO Managed Network Tokens, you don't need to change your integration to support network tokens. PPRO acts as the token requestor on your behalf.

How it works:

Initial Payment: You send a standard RAW_CARD payment request.
Automatic Enrollment: PPRO identifies if the card is eligible. If so, PPRO exchanges the PAN for a Network Token with the card schemes (Visa, Mastercard, etc.) during the authorization.
Tokenized Storage: The resulting instrumentId (type CARD_PPRO_VAULTED) is linked to the Network Token in PPRO’s secure vault.
Subsequent Payments: When you reuse the instrumentId for future Merchant-Initiated (MIT) or Consumer-Initiated (CIT) transactions, PPRO automatically fetches the latest Network Token and a fresh cryptogram to process the payment.

Example: MIT subsequent request reusing PPRO instrument

curl --location 'https://api.sandbox.eu.ppro.com/v1/payment-charges' \
--header 'Content-Type: application/json' \
--header 'Merchant-Id: ******' \
--header 'Request-Idempotency-Key: b691ff08-dea5-4b66-98ea-8d8bb82a568c' \
--header 'Authorization: Bearer ********' \
--data-raw '{
    "paymentMethod": "CARD",
    "autoCapture": true,
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "initialSchemeAuthorizationReference": "060720116005060",
    "instrumentId": "instr_lyVTH6k5tU7OzTX8ZMr4k",
    "amount": {
        "value": 100000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    
    "paymentDescriptor": "Avengers"
}'

{
    "id": "charge_m0425R7HlkOOpleJc5OhH",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_AEe61s0Kwh8yZ8xV1ihgW",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "US",
    "paymentDescriptor": "Avengers",
    "networkTransactionIdentifier": "060720116005061",
    "status": "CAPTURED",
    "consumer": {
        "name": "Tony Stark",
        "email": "[email protected]",
        "country": "US",
        "taxIdentification": "12345678909",
        "billingAddress": {
            "firstName": "Tony",
            "lastName": "Stark",
            "phoneNumber": "01522113356",
            "street": "890 5th Avenue",
            "postalCode": "10075",
            "city": "New York",
            "region": "Manhattan",
            "country": "US"
        }
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "authorizations": [
        {
            "id": "authz_gzgNQB8EjAsKwhWkLzs98",
            "amount": 100000,
            "status": "AUTHORIZED",
            "schemeAuthorizationReference": "060720116005061",
            "createdAt": "2025-06-05T19:06:57.395Z",
            "updatedAt": "2025-06-05T19:06:57.395Z"
        }
    ],
    "captures": [
        {
            "id": "capture_hpYaw425rO1JDKQiRuvCt",
            "amount": 100000,
            "status": "CAPTURED",
            "createdAt": "2025-06-05T19:06:57.395Z",
            "updatedAt": "2025-06-05T19:06:57.395Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-06-05T19:06:56.394Z",
    "updatedAt": "2025-06-05T19:06:57.395Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_m0425R7HlkOOpleJc5OhH/voids"
        }
    }
}