Payment Integration#

There are two ways to perform a payment transaction at Tuna. They are as follows:

Card Tokenization: mandatory when paying with a credit card;
Direct Request: for other payment methods, such as Boleto, PIX, Bitcoin and Nupay.

Payment Integration in the Frontend or Backend!?

All requests for Tuna serves must come from a backend application due to security reasons with your production keys. Thus, if a request is handling data that comes from your frontend application, your frontend must request for your backend to communicate with Tuna servers. Finally, your backend will handle the response and pass the result to your frontend.

note

On this page, it is shown how to perform the integration using Tuna's Sandbox Environment. Let's start it out.

Card Tokenization#

To perform credit card payments, you must use our api/Token. The api/Token is responsible for creating a unique session for your customer at Tuna and the tokenization process of credit card data following Payment Card Industry Data Security Standard ("PCI DSS").

There are three steps in performing a payment transaction with credit card:

Step 1: start a new session for your customer;
Step 2: create a valid credit card token. This process can be done in two ways:
- using a new credit card;
- using a stored credit card (from previous sessions).
Step 3: request for the payment transaction at Tuna's api/Payment/Init endpoint.

Step 1: Start a new session for your customer#

In this step, the request is for the endpoint api/Token/NewSession. If you need more information about this endpoint, check it out here.

You can do this step only at the checkout page.

Request
Response

curl -X 'POST' \
  'https://token.tuna-demo.uy/api/Token/NewSession' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: demo' \
  -H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "id": "7",
      "email": "maju.cheapetta@synapcom.com.br"
    }
  }'

Step 2: Create a valid credit card token#

There are two ways to create a valid credit card token:

Using a New Credit Card
Using a Stored Credit Card

Using a New Credit Card#

When you have a new customer, it is the first the credit card is going to be used. So, you need to create the token for the credit card. This is done through the endpoint api/Token/Generate. The exemplary request and response is shown bellow:

Request
Response

curl -X 'POST' \
  'https://token.tuna-demo.uy/api/Token/Generate' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: demo' \
  -H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "qsTfE2PUGhuncSiaSkFxwJ5vqtsMDrUQsnyM4ZbeTKvx5EJutFovAHEt2/QGjHe61spKmCY8saNoht+VfqTGgxqu2r49ShW2",
    "card": {
      "cardHolderName": "Captured",
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2023,
      "cvv": "222",
      "singleUse": false
    }
  }'

Using a Stored Credit Card#

If you have a recurring customer, you can ask Tuna for stored credit card tokens. This is performed by making a request for the endpoint api/Token/List, which will respond with a list of available tokens. Then, at your frontend, the customer will select a credit card and confirm its CVV for security reasons. After the confirmation, a request for the api/Token/Bind endpoint is required to validate the token with its CVV. Now, please, check out the examples that follow.

Exemplary request and response for the api/token/List endpoint

Request
Response

curl -X 'POST' \
  'https://token.tuna-demo.uy/api/Token/List' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: demo' \
  -H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "k4cUOKYig2artPWooVru/GoYbQU2Jc1PhbEZtZcnlQqXHO7kLPXAgFhjJJuPsb8DIij/RgNyxx7NpNBhkT6w+CEfzrfjpeyP"
  }

Exemplary request and response for the api/Token/Bind endpoint

Request
Response

curl -X 'POST' \
  'https://token.tuna-demo.uy/api/Token/Bind' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: demo' \
  -H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId": "qsTfE2PUGhuncSiaSkFxwJ5vqtsMDrUQsnyM4ZbeTKvx5EJutFovAHEt2/QGjHe61spKmCY8saNoht+VfqTGgxqu2r49ShW2",
    "token": "ct_NjJmM2QxOTUtYTM4OS00YmYyLTg4MDAtOTE3YzY1NzM0NmE30",
    "cvv": "222"
  }'

Step 3: Request for the Payment#

Once the tokenization process is successful, you can request the payment transaction, which is performed through the endpoint api/Payment/Init. Here is shown a request and response for a credit card transaction:

Request
Response

curl -X 'POST' \
  'https://sandbox.tuna-demo.uy/api/Payment/Init' \
  -H 'accept: application/json' \
  -H 'x-tuna-account: demo' \
  -H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
  -H 'Content-Type: application/json' \
  -d '{
  "tokenSession": "Tqra0uZACXDPFRYlvWExU++QIjhQBnQTSNbvFY6/uLLn31fjqVT6y5jeEwpMzQT/vR6xXxz1AGkDMBj1dtsCfESDolhTolMr+VZNIPO7CsM=",
  "partnerUniqueId": "#000.001",
  "customer": {
    "id": "7",
    "email": "maju.cheapetta@synapcom.com.br",
    "document": "744.479.870-23",
    "documentType": "CPF",
    "name": "Maju Cheapetta"
  },
  "paymentItems": {
    "items": [
      {
        "amount": 20,
        "detailUniqueId": "A01",
        "productDescription": "Test product",
        "itemQuantity": 1
      }
    ]
  },
  "paymentData": {
    "paymentMethods": [
      {
        "paymentMethodType": "1",
        "amount": 20,
        "installments": 1,
        "cardInfo": {
          "token": "ct_NjJmM2QxOTUtYTM4OS00YmYyLTg4MDAtOTE3YzY1NzM0NmE30",
          "tokenProvider": "Tuna",
          "cardHolderName": "Captured",
          "expirationMonth": 12,
          "expirationYear": 2023,
          "brandName": "Visa",
          "tokenSingleUse": 0,
          "saveCard": false,
          "billingInfo": {
            "document": "744.479.870-23",
            "documentType": "CPF"
          }
        }
      }
    ],
    "deliveryAddress": {
      "street": "Rua João Longo",
      "number": "1004",
      "neighborhood": "Jandira",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "06608-420",
      "phone": "(11) 6536-8864",
      "country": "BR"
    },
    "countryCode": "BR"
  }
}'

Direct Request#

For other payment methods, such as Boleto, PIX, Bitcoin and Nupay, you can directly request the payment transaction at Tuna's api/Payment/Init endpoint. This is almost the same as Step 3 taken for the Card Tokenization. The only difference is that when performing a direct request, you don't need to send the sessionId used as tokenSession for the request.

Increase your approval rates

If you are implementing a major integration with Tuna, using multiple payment methods, you should perform an extra step to start a new session for your customer. This is the same as Step 1 taken for the Card Tokenization, and it would be already implemented in your backend for credit card payment. Performing this step leverages the increase in your approval rates.

Examples for all payment methods

Check out the documentation of the api/Payment/Init endpoint and look for more examples on the right side of the page. You will find examples of requests and responses for Boleto, PIX, Bitcoin, Split, Gift Card, and much more.