API Guide#

Table of Contents#

Payment Integration#

To perform credit card payments or have a significant integration with multiple payments methods at Tuna, you will need first to use our api/Token endpoint. The api/Token endpoint is responsible for creating a unique session for your user 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. They are as follows:

Setp 1: Start a new session for your customer.
Setp 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

Then, you will be able to request a payment transaction at Tuna's api/Payment/Init endpoint.

This page shows how to perform these steps using Tuna's Sandbox Environment.

Let's start it out.

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.

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"
  },
  "partnerUniqueId": "#022"
}'

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": "34wPRB9p61J0/Vo8jjakPgYjAh5UXUG1EtYwd57yqTLl716AmLjFW+Qdw+QXqDtS4bV/v2Gsu0YPc9HsnFDeYaBlh2YMarxJOuHWYA==",
  "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": "34wPRB9p61J0/Vo8jjakPgYjAh5UXUG1EtYwd57yqTLl716AmLjFW+Qdw+QXqDtS4bV/v2Gsu0YPc9HsnFDeYaBlh2YMarxJOuHWYA=="
}'

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": "34wPRB9p61J0/Vo8jjakPgYjAh5UXUG1EtYwd57yqTLl716AmLjFW+Qdw+QXqDtS4bV/v2Gsu0YPc9HsnFDeYaBlh2YMarxJOuHWYA==",
  "token": "ct_YmUwNDgwMmEtZDNhNC00ZDA0LTg5MDMtOWVkMTBjZjBjODZl0",
  "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.

Examples for all payment methods

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

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"
  }
}'

Resources#

API Guide: are you looking for a guide for our APIs? Check out the introduction to the API Guide.
Payment Integration: do you need to be able to perform secure credit card payments and/or also use other payment methods such as Debit Card, Boleto, PIX, Bitcoin? Checkout how to perform a Payment Integration with our Payment API and Token API.
Split Integration: are you looking to set up a marketplace, so your merchants will use split payment solutions in your marketplace? Check out how to perform a Split Integration with our Merchant API.
Tuna Codes: do you need to learn about your codes and status? Please, check out the Tuna Codes.
Webhooks Notifications: learn more about our notifications in the guide Webhooks Notifications.
Sandbox Environment: check out for information about test data and a full description of the Sandbox Environment.
Idempotent Requests: do you require idempotent requests? Take a look how to make Idempotent Requests.