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!

How it works:

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).

Supported countries:

Argentina	Brazil	Chile	Colombia	Mexico	Peru
Not Supported	Passthrough only (external provider)	Not Supported	Not Supported	Not Supported	Not Supported

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	The unique cryptogram generated by the issuer for the network token in use in the transaction. Mandatory for CIT, optional for MIT.
authorizations.schemeAuthorizationReference	Conditional	String	Received on the initial transaction. Mandatory for subsequent transactions.

Making an initial network token payment (CIT)

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 Initial request

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="
        }
    },
    "amount": {
        "value": 100000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "consumer": {
        "name": "Tony Start",
        "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": "PPRO   *Avengers"
}'

{
    "id": "charge_BuAbK4DjkbRdRxwlMMNwf",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "CONSUMER",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_bopjY4noLpPfmHgheBnPR",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "US",
    "paymentDescriptor": "PPRO   *Avengers",
    "status": "CAPTURED",
    "consumer": {
        "name": "Tony Start",
        "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

The subsequent payment of a subscription using network tokens must be sent along with the card on file parameters initiator = "CONSUMER"(if CIT) or "MERCHANT" (if MIT) and scheduleType = "RECURRING" or "UNSCHEDULED".

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

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",
            "cryptogram": "CCADBxYzRTBBXXXXXXXYZa0AbZD="
        }
    },
    "amount": {
        "value": 100000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [],
        "industryData": [],
        "installmentPlan": {
            "numberOfInstallments": 1
        }
    },
    "consumer": {
        "name": "Tony Start",
        "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": "PPRO   *Avengers"
}'

{
    "id": "charge_m0425R7HlkOOpleJc5OhH",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_AEe61s0Kwh8yZ8xV1ihgW",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "US",
    "paymentDescriptor": "PPRO   *Avengers",
    "networkTransactionIdentifier": "060720116005061",
    "status": "CAPTURED",
    "consumer": {
        "name": "Tony Start",
        "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"
        }
    }
}