Antifraud Integration#

Tuna is a payment orchestrator that can also orchestrate fraud and recovery tooling independently.

With this product, you can run antifraud and recovery strategies (such as biometric and 3DS flows) with or without payment-method orchestration, depending on your architecture.

This model is widely used by:

acquirers that want to improve internal fraud prevention and increase approvals;
large enterprises that orchestrate payment methods and antifraud tools separately.

There are 3 ways to send antifraud orchestration requests to Tuna:

Direct antifraud request (no full PAN/CVV)
Tokenized card request (non-PCI integration)
PCI full-card request (PCI certified customers)

Antifraud Integration in the Frontend or Backend!?

All requests to Tuna APIs must come from your backend application, using your private credentials.

If data originates in your frontend, send it to your backend first, then let your backend call Tuna and return a safe response to the frontend.

note

For onboarding and testing, use the homologation account provided by Tuna and the production endpoints provisioned to your account.

Do not build this integration using a sandbox-only base URL.

Base URLs and Endpoints#

This page uses placeholders in examples:

<ENGINE_BASE_URL> for engine calls (for example, POST /api/Payment/Init)
<TOKEN_BASE_URL> for tokenization calls (/api/Token/...)

Use the exact base URLs and headers provided during your onboarding.

1) Direct Antifraud Request#

Use this mode when you want Tuna to orchestrate antifraud/recovery checks without sending full PAN/CVV.

You can and should still send masked card and other non-sensitive card metadata to improve risk analysis quality.

Key points:

no full PAN or CVV in the payload
use paymentData.paymentMethods[].cardInfo with masked cardNumber and non-sensitive card metadata
no prior tokenization step
in most integrations, tokenSession is not required

Example request and response#

Request
Response

curl -X 'POST' \
  '<ENGINE_BASE_URL>/api/Payment/Init' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: <your-account>' \
  -H 'x-tuna-apptoken: <your-app-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerUniqueId": "AF-ORDER-10001",
    "customer": {
      "id": "customer-7",
      "name": "Maria Silva",
      "email": "maria.silva@example.com",
      "document": "087.145.977-99",
      "documentType": "CPF",
      "data": {
        "isCorporate": false,
        "createdDate": "2023-05-10T14:21:00Z"
      }
    },
    "paymentItems": {
      "items": [
        {
          "amount": 3.57,
          "detailUniqueId": "ITEM-1",
          "productDescription": "Subscription",
          "itemQuantity": 1,
          "antiFraud": {
            "isEmailConfirmed": true,
            "isPhoneNumberConfirmed": false,
            "data": {
              "channel": "mobile-app",
              "campaign": "retargeting"
            }
          }
        }
      ]
    },
    "paymentData": {
      "paymentMethods": [
        {
          "paymentMethodType": "1",
          "amount": 3.57,
          "installments": 1,
          "cardInfo": {
            "cardHolderName": "alex doe",
            "saveCard": false,
            "cardNumber": "555544******4444",
            "expirationMonth": 3,
            "expirationYear": 2030,
            "brandName": "mastercard"
          }
        }
      ],
      "countryCode": "BR",
      "antiFraud": {
        "deliveryAddressee": "Maria Silva",
        "data": {
          "travel": {
            "type": "bus",
            "numberOfConnections": 0
          },
          "returnOriginalResponse": true
        }
      }
    },
    "frontData": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    }
  }'

2) Tokenized Card Request (Non-PCI)#

Use this mode when you need card-based risk analysis or payment orchestration and your environment is not PCI certified to send raw card PAN/CVV.

Flow summary:

Create a session: POST /api/Token/NewSession
Generate token: POST /api/Token/Generate (or list/bind stored token)
Call POST /api/Payment/Init with tokenSession and cardInfo.token

Step 1: Start session#

Endpoint: api/Token/NewSession

Step 2: Tokenize card or bind stored token#

Endpoints:

Step 3: Init with tokenized card#

Request
Response

curl -X 'POST' \
  '<ENGINE_BASE_URL>/api/Payment/Init' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: <your-account>' \
  -H 'x-tuna-apptoken: <your-app-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tokenSession": "<session-id-from-newsession>",
    "partnerUniqueId": "AF-ORDER-10002",
    "customer": {
      "id": "customer-7",
      "email": "maria.silva@example.com",
      "document": "087.145.977-99",
      "documentType": "CPF",
      "name": "Maria Silva"
    },
    "paymentItems": {
      "items": [
        {
          "amount": 12000,
          "detailUniqueId": "ITEM-1",
          "productDescription": "Subscription",
          "itemQuantity": 1
        }
      ]
    },
    "paymentData": {
      "paymentMethods": [
        {
          "paymentMethodType": "1",
          "amount": 12000,
          "installments": 1,
          "cardInfo": {
            "token": "<card-token>",
            "tokenProvider": "Tuna",
            "saveCard": false
          }
        }
      ],
      "countryCode": "BR",
      "antiFraud": {
        "data": {
          "returnOriginalResponse": true
        }
      }
    },
    "frontData": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    }
  }'

3) PCI Full-Card Request (PCI Certified)#

If your company is PCI certified, Tuna supports a direct PCI integration where you send full card PAN/CVV in the init payload.

This is the pattern represented in the PCI folder of Tuna's Postman collection.

Important: for PCI full-card requests, the entrypoint is different from the standard payment init endpoint.

PCI entrypoint: https://token.tunagateway.com/api/integrations/pci/init
Request body contract: same init structure used in api/Payment/Init

Key points:

no prior tokenization step is required
no prior session is required for tokenization
card data is sent directly in paymentData.paymentMethods[].cardInfo

PCI init example#

curl -X 'POST' \
  'https://token.tunagateway.com/api/integrations/pci/init' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: <your-account>' \
  -H 'x-tuna-apptoken: <your-app-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "partnerUniqueId": "AF-ORDER-10003",
    "customer": {
      "id": "customer-7",
      "name": "Maria Silva",
      "email": "maria.silva@example.com",
      "document": "087.145.977-99",
      "documentType": "CPF"
    },
    "paymentItems": {
      "items": [
        {
          "amount": 12000,
          "detailUniqueId": "ITEM-1",
          "productDescription": "Subscription",
          "itemQuantity": 1
        }
      ]
    },
    "paymentData": {
      "paymentMethods": [
        {
          "paymentMethodType": "1",
          "amount": 12000,
          "installments": 1,
          "cardInfo": {
            "cardNumber": "4111111111111111",
            "cardHolderName": "Authorized",
            "expirationMonth": 6,
            "expirationYear": 2032,
            "cvv": "123",
            "singleUse": true,
            "saveCard": false
          }
        }
      ],
      "countryCode": "BR",
      "antiFraud": {
        "data": {
          "returnOriginalResponse": true
        }
      }
    },
    "frontData": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    }
  }'

Sending Custom Data for Antifraud and Recovery#

Tuna supports rich custom payloads so you can pass data required by internal models and external antifraud/recovery providers.

Common locations for custom data:

customer.data
paymentItems.items[].antiFraud
paymentData.antiFraud
paymentData.antiFraud.data
paymentData.paymentMethods[].data
frontData (including device/network/session fields)

You can include nested JSON objects (for example, travel, lodging, marketplace, subscriptions, digital goods, and channel metadata) according to your strategy.

tip

The api/Payment/Init reference includes multiple request examples showing antifraud payload variations, including custom travel and vertical-specific data.

For curated samples focused on advanced antifraud payloads, see Antifraud Init Examples.

Related API References#

Postman Collection and Integration Examples#

All major Tuna integration modes are available in our official Postman repository, including PCI and non-PCI card flows, antifraud-only patterns, tokenization, 3DS, PIX, boleto, wallets, cancellations, and other operational APIs.

Repository: tuna-software/postman

Use it as a practical companion to the API reference, with ready-to-run requests and many end-to-end examples.