Process Payments Directly Using Network Tokens API
Use a card-network token and transaction cryptogram to initiate a secure FiatPe card payment directly from your backend.
Sandbox network-token test values
Use these simulator values with card.tokenised: true to test each supported authentication response in FiatPe Sandbox. These values are not real card-network tokens and must never be used in Live mode.
Include a Sandbox cryptogram in card.cryptogram_value. Do not reuse production cryptograms, dynamic CVVs, or network tokens when testing these simulated flows.
Before you begin
This integration is intended for merchants that act as a network-token requestor or receive payment-ready network tokens from an approved tokenisation provider. The value sent in card.number must be the network token, not the customer’s original card number.
For payments that use raw test-card details, see the standard S2S Card integration guide.
Contact FiatPe to enable network-token payments for your account. Submit the required PCI DSS documentation and complete the applicable card-network and acquiring-bank checks before using this API in Live mode.
Create the order on your server
Create a new FiatPe order for each payment attempt. Amounts use the smallest currency sub-unit: for INR, 5000 represents ₹50.00. Store the returned order ID against your internal order before using it in the S2S payment request.
Server request example
Use your FiatPe credentials only from a trusted backend environment.
REQUEST
curl --request POST \
--url https://api.fiatpe.com/v1/orders/ \
--header "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
--header "Content-Type: application/json" \
--data '{
"amount": 5000,
"currency": "INR"
}'Response
Store the returned data.id and pass it as the order_id in Step 2.
{
"data": {
"id": "order_2f40f08f4baa4e5b",
"amount": 5000,
"entity": "order",
"status": "created",
"currency": "INR",
"metadata": {},
"created_at": 1788148983,
"return_url": null,
"amount_paid": 0,
"bank_details": null,
"return_method": "POST",
"amount_pending": 5000
},
"message": "order created successfully."
}Initiate a payment with a network token
Send this request only from your secure backend. Generate the Basic authorization value by Base64 encoding api_key:secret_key, set card.tokenised to true, and provide the transaction cryptogram issued for this payment attempt.
REQUEST
curl --location 'https://api.fiatpe.com/v1/payments/create/s2s/' \
--header 'Authorization: Basic <base64(api_key:secret_key)>' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 5000,
"currency": "INR",
"contact": "+919898989898",
"name": "Aftab Hussain",
"email": "customer@example.com",
"order_id": "order_ef06bf8c31864055",
"return_url": "https://example.com/payment/return",
"description": "Test payment",
"method": "card",
"card": {
"number": "4000000000000002",
"expiry_month": "11",
"expiry_year": "26",
"cryptogram_value": "fsdf2423432sfsd424",
"tokenised": true,
"cvv": "123"
},
"metadata": {
"note_key": "value1"
}
}'Request fields
Handle the response action
Tokenised card payments use the same response actions as standard S2S card payments. The action returned can vary with the network, issuer, acquiring TID, and transaction configuration. Always inspect next[].action instead of assuming a fixed flow.
Your integration must successfully handle Native, Redirect, and HTML Form flows in the UAT environment. The flow returned for a transaction can vary based on the configured TID, acquiring bank, issuing bank, payment network, payment method, and other transaction parameters.
Do not hardcode a flow for a card, bank, or wallet. Always inspect the returned next[].action value and process otp_submit, resend_otp, redirect, or html_form as instructed by the API response.
Native OTP response
{
"payment_id": "FIATPESTCM3YWO15VB1790705241",
"next": [
{
"action": "otp_submit",
"url": "https://api.fiatpe.com/v1/payments/FIATPESTCM3YWO15VB1790705241/otp/submit/"
},
{
"action": "resend_otp",
"url": "https://api.fiatpe.com/v1/payments/FIATPESTCM3YWO15VB1790705241/otp/resend/"
}
]
}Redirect response
{
"payment_id": "FIATPESTK1CU1FNRXR1790705821",
"next": [
{
"action": "redirect",
"url": "https://api.fiatpe.com/v1/payments/FIATPESTK1CU1FNRXR1790705821/authentication/"
}
]
}HTML Form response
{
"payment_id": "FIATPEST8OJ7CDB2BI1790705845",
"next": [
{
"action": "html_form",
"html_content": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <title>Redirecting | FiatPe</title>\n <script src=\"https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js\"></script>\n</head>\n<body>\n <div class=\"redirect-container\">\n <div id=\"lottie-loader\"></div>\n <h1>Redirecting...</h1>\n <p>Please wait while we redirect you securely. Do not close this window.</p>\n <form id=\"payment-form\" method=\"GET\"\n action=\"https://api.fiatpe.com/v1/payments/FIATPEST8OJ7CDB2BI1790705845/authentication/\"\n hidden>\n <input type=\"hidden\" name=\"paymentMode\" value=\"CARD\">\n </form>\n <noscript>\n <button type=\"submit\" form=\"payment-form\">Continue to payment</button>\n </noscript>\n </div>\n <script>\n if (window.lottie) {\n lottie.loadAnimation({\n container: document.getElementById(\"lottie-loader\"),\n renderer: \"svg\",\n loop: true,\n autoplay: true,\n path: \"https://bucket.fiatpe.com/static/animation/lottie/fiatpe_pg_processing_loader.json\"\n });\n }\n window.setTimeout(function () {\n document.getElementById(\"payment-form\").submit();\n }, 1000);\n </script>\n</body>\n</html>"
}
]
}Complete and verify the payment
- For
otp_submitorresend_otp, use the action URLs returned for that payment. - For
redirect, navigate the customer’s browser to the returned URL. - For
html_form, render the returned HTML as a complete browser document. - Never log a token cryptogram, CVV, OTP, API secret, or other authentication value.
- Confirm the final payment status on your backend and process webhooks idempotently before fulfilment.