Velana

https://velana.readme.io/reference
Admin
Velana is a payment processing API that enables developers to process transactions across multiple...
Tokens:37,656
Snippets:75
Trust Score:9.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### POST /v1/transactions

Source: https://velana.readme.io/reference/introducao

Example of how to make a POST request to the /v1/transactions endpoint, including authentication headers.

```APIDOC
## POST /v1/transactions

### Description

This endpoint is used to create new transactions. Ensure you have authenticated correctly before making this request.

### Method

POST

### Endpoint

`https://api.velana.com.br/v1/transactions`

### Parameters

#### Request Headers

- **authorization** (string) - Required - Your secret API key in the format `Basic <base64_encoded_key>`.

#### Request Body

(The request body structure for this endpoint is not provided in the input text, but would typically include transaction details.)

### Request Example

```typescript
const options = {
    method: "POST",
    url: "https://api.velana.com.br/v1/transactions",
    headers: {
        authorization: 'Basic ' + new Buffer("{SECRET_KEY}:x").toString('base64')
    }
    // Request body would be added here, e.g.:
    // data: {
    //     "amount": 100.50,
    //     "description": "Test transaction"
    // }
}
```

### Response

#### Success Response (200 or 201)

(The success response structure for this endpoint is not provided in the input text, but would typically include details of the created transaction.)

#### Response Example

```json
{
  "example": "{\"transactionId\": \"txn_12345\", \"status\": \"pending\"}"
}
```
```

--------------------------------

### Velana API Transaction Response Example (JSON)

Source: https://velana.readme.io/reference/criar-transacao

This JSON object represents a successful transaction response from the Velana API. It includes details such as transaction ID, amount, status, payment method, customer information, card details, items, and split rules. This example is useful for understanding the structure of data returned after a transaction.

```json
{
	"id": 282,
	"amount": 10000,
	"refundedAmount": 0,
	"companyId": 2,
	"installments": 12,
	"paymentMethod": "credit_card",
	"status": "paid",
	"postbackUrl": null,
	"metadata": null,
	"traceable": false,
	"secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
	"secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
	"createdAt": "2022-07-18T09:54:22.000Z",
	"updatedAt": "2022-07-18T09:54:22.000Z",
	"paidAt": "2022-07-18T09:54:22.000Z",
	"ip": null,
	"externalRef": null,
	"customer": {
		"id": 1,
		"externalRef": null,
		"name": "Gabryel",
		"email": "gabryel@hotmail.com",
		"phone": "11999999999",
		"birthdate": null,
		"createdAt": "2022-05-26T19:17:48.000Z",
		"document": {
			"number": "12345678910",
			"type": "cpf"
		},
		"address": {
			"street": "Rua República Argentina",
			"streetNumber": "4214",
			"complement": null,
			"zipCode": "11065030",
			"neighborhood": "Pompéia",
			"city": "Santos",
			"state": "SP",
			"country": "BR"
		}
	},
	"card": {
		"id": 147,
		"brand": "visa",
		"holderName": "GABRYEL FERREIRA",
		"lastDigits": "1111",
		"expirationMonth": 3,
		"expirationYear": 2028,
		"reusable": true,
		"createdAt": "2022-07-17T18:08:11.000Z"
	},
	"boleto": null,
	"pix": null,
	"shipping": null,
	"refusedReason": null,
	"items": [
		{
			"externalRef": null,
			"title": "b456",
			"unitPrice": 100,
			"quantity": 1,
			"tangible": false
		}
	],
	"splits": [
		{
			"recipientId": 1,
			"amount": 10000,
			"netAmount": 9400
		}
	],
	"refunds": [],
	"delivery": null,
	"fee": {
		"fixedAmount": 200,
		"spreadPercentage": 4,
		"estimatedFee": 600,
		"netAmount": 9400
	}
}
```

--------------------------------

### Payment Method Configuration

Source: https://velana.readme.io/reference/criar-checkout

This section details the configuration options for different payment methods, including enabling/disabling them and setting expiration periods or installment limits.

```APIDOC
## Payment Method Configuration

### Description
Configure the available payment methods for your checkout, including boleto, Pix, and card payments. Set parameters such as expiration days for boleto and Pix, and installment options for card payments.

### Request Body
```json
{
  "boleto": {
    "enabled": "boolean",
    "expiresInDays": "integer"
  },
  "pix": {
    "enabled": "boolean",
    "expiresInDays": "integer"
  },
  "card": {
    "enabled": "boolean",
    "freeInstallments": "integer",
    "maxInstallments": "integer"
  }
}
```

### Response
#### Success Response (200)
- **boleto** (object) - Boleto payment configuration.
- **pix** (object) - Pix payment configuration.
- **card** (object) - Card payment configuration.

#### Response Example
```json
{
  "boleto": {
    "enabled": true,
    "expiresInDays": 5
  },
  "pix": {
    "enabled": true,
    "expiresInDays": 1
  },
  "card": {
    "enabled": true,
    "freeInstallments": 3,
    "maxInstallments": 12
  }
}
```
```

--------------------------------

### Authentication and Transactions

Source: https://velana.readme.io/reference

This section details how to authenticate with the Velana API using Basic Access Authentication and provides an example for the transactions endpoint.

```APIDOC
## Authentication

### Description
Our API follows REST standards, and all responses are in JSON format. To authenticate, you must use Basic Access Authentication with your secret key.

### Method
POST

### Endpoint
`https://api.velana.com.br/v1/transactions`

### Parameters
#### Headers
- **authorization** (string) - Required - Your secret key in the format `Basic {SECRET_KEY}:x` encoded in base64.

### Request Example
```javascript
const options = {
    method: "POST",
    url: "https://api.velana.com.br/v1/transactions",
    headers: {
        authorization: 'Basic ' + new Buffer("{SECRET_KEY}:x").toString('base64')
    }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status of the operation.
- **message** (string) - A message describing the result of the operation.

#### Response Example
```json
{
  "status": "success",
  "message": "Transaction processed successfully."
}
```
```

--------------------------------

### GET /websites/{websiteId}

Source: https://velana.readme.io/reference/atualizar-dados-da-empresa

Retrieves detailed information about a specific website, including its configuration, balance, and associated volumes.

```APIDOC
## GET /websites/{websiteId}

### Description
Retrieves detailed information about a specific website, including its configuration, balance, and associated volumes.

### Method
GET

### Endpoint
/websites/{websiteId}

### Parameters
#### Path Parameters
- **websiteId** (string) - Required - The unique identifier of the website.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the website.
- **name** (string) - The name of the website.
- **url** (string) - The URL of the website.
- **anticipatableVolumePercentage** (integer) - The percentage of anticipatable volume.
- **createdAt** (string) - The timestamp when the website was created.
- **balance** (object) - An object containing the website's balance information.
  - **available** (integer) - The available balance for the website.
  - **updatedAt** (string) - The timestamp when the balance was last updated.

#### Response Example
```json
{
  "id": "67098e77995e710050882732",
  "name": "Example Website",
  "url": "https://example.com",
  "anticipatableVolumePercentage": {
    "type": "integer",
    "example": 100,
    "default": 0
  },
  "createdAt": {
    "type": "string",
    "example": "2022-05-26T19:06:35.000Z"
  },
  "balance": {
    "type": "object",
    "properties": {
      "available": {
        "type": "integer",
        "example": 6470,
        "default": 0
      },
      "updatedAt": {
        "type": "string",
        "example": "2022-06-02T01:37:48.000Z"
      }
    }
  }
}
```
```

--------------------------------

### Authentication

Source: https://velana.readme.io/reference/introducao

Details on how to authenticate with the Velana API using Basic Access Authentication.

```APIDOC
## Authentication

### Description

Our API follows REST standards and all responses are in JSON format. To authenticate, you must use Basic Access Authentication with your secret key.

### Method

All requests require authentication.

### Endpoint

N/A (Authentication is done via headers)

### Parameters

#### Request Headers

- **authorization** (string) - Required - Your secret API key in the format `Basic <base64_encoded_key>`.

### Request Example

```typescript
const options = {
    method: "POST",
    url: "https://api.velana.com.br/v1/transactions",
    headers: {
        authorization: 'Basic ' + new Buffer("{SECRET_KEY}:x").toString('base64')
    }
}
```

### Response

Authentication errors will typically result in a 401 Unauthorized status code.
```

--------------------------------

### Retrieve Transfer by ID (Shell, Node, Ruby, PHP, Python)

Source: https://velana.readme.io/reference/buscar-transfer%C3%AAncia

This snippet demonstrates how to retrieve a specific transfer by its ID using the Velana API. It includes examples for making a GET request in Shell, Node.js, Ruby, PHP, and Python. Ensure you replace '{id}' with the actual transfer ID.

```Shell
curl --request GET \
     --url https://api.velana.com.br/v1/transfers/id \
     --header 'accept: application/json'
```

```Node.js
const fetch = require('node-fetch');

const url = "https://api.velana.com.br/v1/transfers/id";

fetch(url, {
  method: 'GET',
  headers: {
    'accept': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```Ruby
require 'net/http'
require 'uri'

uri = URI.parse("https://api.velana.com.br/v1/transfers/id")
request = Net::HTTP::Get.new(uri)
request["accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(request)
end

puts response.body
```

```PHP
<?php

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, "https://api.velana.com.br/v1/transfers/id");
curl_setopt($curl, CURLOPT_HTTPHEADER, [
  'accept: application/json',
]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo $response;
}

curl_close($curl);
?>
```

```Python
import requests

url = "https://api.velana.com.br/v1/transfers/id"
headers = {
    'accept': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.json())
```

--------------------------------

### Create Checkout

Source: https://velana.readme.io/reference/criar-checkout

Creates a new checkout session by providing the total amount, cart items, and available payment methods. Users are then redirected to a secure URL for payment.

```APIDOC
## POST /checkout

### Description
Creates a new checkout session. Requires the total amount, cart items, and available payment methods. Returns a `secureUrl` for user redirection and optionally accepts a `postbackUrl` for transaction updates.

### Method
POST

### Endpoint
/checkout

### Parameters
#### Request Body
- **amount** (number) - Required - The total amount for the checkout.
- **items** (array) - Required - A list of items in the cart. Each item should have properties like `id`, `name`, `quantity`, and `price'.
- **paymentMethods** (array) - Required - A list of available payment methods for this checkout.
- **postbackUrl** (string) - Optional - A URL to receive asynchronous updates about transaction status.

### Request Example
```json
{
  "amount": 100.50,
  "items": [
    {
      "id": "item123",
      "name": "Example Product",
      "quantity": 2,
      "price": 50.25
    }
  ],
  "paymentMethods": ["credit_card", "bank_slip"],
  "postbackUrl": "https://yourdomain.com/api/postback"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created checkout.
- **secureUrl** (string) - The URL where the user will be redirected to complete the payment.
- **status** (string) - The initial status of the checkout (e.g., 'pending').

#### Response Example
```json
{
  "id": "chk_abcdef123456",
  "secureUrl": "https://secure.paymentgateway.com/checkout/abcdef123456",
  "status": "pending"
}
```
```

--------------------------------

### Get Available Balance (OpenAPI)

Source: https://velana.readme.io/reference/obter-saldo

This snippet details the OpenAPI definition for the 'Get Available Balance' endpoint. It specifies the HTTP GET method, the '/balance/available' path, and expected query parameters like 'recipientId'. The response schema includes 'amount' and 'recipientId'.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "API V1",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.velana.com.br/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/balance/available": {
      "get": {
        "summary": "Obter saldo disponível",
        "description": "Para operações de saldo, use a rota /balance.",
        "operationId": "obter-saldo",
        "parameters": [
          {
            "name": "recipientId",
            "in": "query",
            "description": "ID do recebedor. Caso não seja enviado, será usado o recebedor principal da empresa.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"amount\": 1000,\n    \"recipientId\": 327\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "amount": {
                      "type": "integer",
                      "example": 1000,
                      "default": 0
                    },
                    "recipientId": {
                      "type": "integer",
                      "example": 327,
                      "default": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true,
  "_id": "67098e77995e710050882757:67098e77995e710050882733"
}
```

--------------------------------

### GET /company

Source: https://velana.readme.io/reference/dados-da-empresa

Retrieves company data. This endpoint is used for company operations.

```APIDOC
## GET /company

### Description
Retrieves company data. This endpoint is used for company operations.

### Method
GET

### Endpoint
https://api.velana.com.br/v1/company

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the company.
- **userId** (integer) - The identifier of the user associated with the company.
- **legalName** (string) - The legal name of the company.
- **blocked** (boolean) - Indicates if the company account is blocked.
- **invoiceDescriptor** (string) - Descriptor used for invoices.
- **commercialName** (string | null) - The commercial name of the company, if any.
- **createdAt** (string) - The timestamp when the company record was created.
- **uploadedDocuments** (boolean) - Indicates if company documents have been uploaded.
- **user** (object) - User details associated with the company.
  - **id** (integer) - User ID.
  - **email** (string) - User's email address.
  - **phone** (string) - User's phone number.
  - **name** (string) - User's name.
  - **isEmailVerified** (boolean) - Whether the user's email is verified.
  - **isPhoneVerified** (boolean) - Whether the user's phone is verified.
  - **isAdmin** (boolean) - Whether the user has admin privileges.
  - **isMaster** (boolean) - Whether the user has master privileges.
  - **createdAt** (string) - Timestamp of user creation.
- **document** (object) - Company's identification document details.
  - **id** (integer) - Document ID.
  - **number** (string) - Document number (e.g., CPF or CNPJ).
  - **type** (string) - Type of document (e.g., 'cpf', 'cnpj').
- **permissions** (object) - Company's permissions and feature settings.
  - **id** (integer) - Permissions ID.
  - **companyId** (integer) - The ID of the company this permission set belongs to.
  - **isCreditCardAvailable** (boolean) - Whether credit card payments are available.
  - **isBoletoAvailable** (boolean) - Whether boleto payments are available.
  - **isPixAvailable** (boolean) - Whether Pix payments are available.
  - **transferEnabled** (boolean) - Whether transfers are enabled.
  - **transferPriceCents** (integer) - The price of a transfer in cents.
  - **anticipationEnabled** (boolean) - Whether anticipation of payments is enabled.
  - **anticipatableVolumePercentage** (integer) - The percentage of volume that can be anticipated.
  - **anticipationPricePercent** (number) - The percentage fee for anticipation.
  - **minAnticipatableDays** (integer) - The minimum number of days for anticipation.
  - **createdAt** (string) - Timestamp of permission creation.
- **details** (object) - Additional details about the company.
  - **id** (integer) - Details ID.
  - **averageRevenue** (integer) - Average monthly revenue.
  - **averageTicket** (integer) - Average ticket value.
  - **physicalProducts** (boolean) - Whether the company deals with physical products.
  - **productsDescription** (string) - Description of the company's products.
  - **siteUrl** (string) - The company's website URL.
  - **phone** (string) - Company contact phone number.
  - **email** (string) - Company contact email address.
  - **createdAt** (string) - Timestamp of details creation.
- **legalRepresentative** (object) - Details of the company's legal representative.
  - **id** (integer) - Legal representative ID.
  - **name** (string) - Name of the legal representative.
  - **phone** (string) - Phone number of the legal representative.
  - **motherName** (string) - Mother's name of the legal representative.
  - **birthdate** (string) - Birthdate of the legal representative.
  - **createdAt** (string) - Timestamp of legal representative creation.
  - **document** (object) - Document details of the legal representative.
    - **id** (integer) - Document ID.
    - **number** (string) - Document number.
    - **type** (string) - Type of document.
- **socialContract** (string | null) - URL or identifier for the social contract document.
- **partnerDocument** (string | null) - URL or identifier for partner documents.
- **address** (object) - Company's address details.
  - **id** (integer) - Address ID.
  - **street** (string) - Street name.
  - **streetNumber** (string) - Street number.
  - **complement** (string | null) - Complement information for the address.
  - **zipCode** (string) - Postal code.
  - **neighborhood** (string) - Neighborhood.
  - **city** (string) - City.
  - **state** (string) - State.
  - **country** (string) - Country.
- **revenue** (object) - Financial revenue summary for the company.
  - **totalAmount** (integer) - Total revenue amount.
  - **totalCount** (integer) - Total number of transactions.
  - **cardAmount** (integer) - Revenue from card payments.
  - **cardCount** (integer) - Number of card transactions.
  - **pixAmount** (integer) - Revenue from Pix payments.
  - **pixCount** (integer) - Number of Pix transactions.
  - **boletoAmount** (integer) - Revenue from boleto payments.
  - **boletoCount** (integer) - Number of boleto transactions.
  - **chargebackAmount** (integer) - Amount of chargebacks.
  - **chargebackCount** (integer) - Number of chargebacks.
  - **refundAmount** (integer) - Amount of refunds.
  - **refundCount** (integer) - Number of refunds.
  - **createdAt** (string) - Timestamp of revenue data creation.
- **defaultRecipient** (object) - Details of the default recipient for transactions.
  - **id** (integer) - Recipient ID.
  - **legalName** (string) - Legal name of the recipient.
  - **createdAt** (string) - Timestamp of recipient creation.
  - **document** (object) - Document details of the recipient.
    - **id** (integer) - Document ID.
    - **number** (string) - Document number.
    - **type** (string) - Type of document.
  - **transferSettings** (object) - Transfer settings for the recipient.
    - **id** (integer) - Transfer settings ID.
    - **transferEnabled** (boolean) - Whether transfers are enabled for this recipient.
    - **automaticAnticipationEnabled** (boolean) - Whether automatic anticipation is enabled.
    - **anticipatableVolumePercentage** (integer) - Percentage of volume that can be anticipated.
    - **createdAt** (string) - Timestamp of transfer settings creation.
  - **balance** (object) - Current balance information for the recipient.
    - **available** (integer) - Available balance amount.
    - **updatedAt** (string) - Timestamp when the balance was last updated.

#### Response Example
```json
{
    "id": 2,
    "userId": 1,
    "legalName": "Gabryel Ferreira",
    "blocked": false,
    "invoiceDescriptor": "Gabryel",
    "commercialName": null,
    "createdAt": "2022-05-26T19:06:35.000Z",
    "uploadedDocuments": false,
    "user": {
        "id": 1,
        "email": "gabryel.ferreira@hotmail.com",
        "phone": "11999999999",
        "name": "Gabryel",
        "isEmailVerified": true,
        "isPhoneVerified": false,
        "isAdmin": true,
        "isMaster": true,
        "createdAt": "2022-05-26T19:03:23.000Z"
    },
    "document": {
        "id": 3,
        "number": "12345678910",
        "type": "cpf"
    },
    "permissions": {
        "id": 1,
        "companyId": 2,
        "isCreditCardAvailable": true,
        "isBoletoAvailable": true,
        "isPixAvailable": true,
        "transferEnabled": true,
        "transferPriceCents": 200,
        "anticipationEnabled": true,
        "anticipatableVolumePercentage": 100,
        "anticipationPricePercent": 2,
        "minAnticipatableDays": 2,
        "createdAt": "2022-05-26T19:06:35.000Z"
    },
    "details": {
        "id": 1,
        "averageRevenue": 5000,
        "averageTicket": 500,
        "physicalProducts": true,
        "productsDescription": "Produtos fera",
        "siteUrl": "www.fera.com",
        "phone": "11999999999",
        "email": "gabryel.ferreira@hotmail.com",
        "createdAt": "2022-05-26T19:06:35.000Z"
    },
    "legalRepresentative": {
        "id": 1,
        "name": "Gabryel Ferreira",
        "phone": "11999999999",
        "motherName": "Ana Paula do Nascimento",
        "birthdate": "1998-07-03",
        "createdAt": "2022-05-26T19:06:35.000Z",
        "document": {
            "id": 4,
            "number": "12345678910",
            "type": "cpf"
        }
    },
    "socialContract": null,
    "partnerDocument": null,
    "address": {
        "id": 2,
        "street": "Avenida Presidente Wilson",
        "streetNumber": "42",
        "complement": null,
        "zipCode": "11065200",
        "neighborhood": "Gonzaga",
        "city": "Santos",
        "state": "SP",
        "country": "br"
    },
    "revenue": {
        "totalAmount": 133501,
        "totalCount": 20,
        "cardAmount": 103501,
        "cardCount": 17,
        "pixAmount": 30000,
        "pixCount": 3,
        "boletoAmount": 0,
        "boletoCount": 0,
        "chargebackAmount": 0,
        "chargebackCount": 0,
        "refundAmount": 66979,
        "refundCount": 11,
        "createdAt": "2022-05-26T19:06:35.000Z"
    },
    "defaultRecipient": {
        "id": 1,
        "legalName": "Gabryel Ferreira",
        "createdAt": "2022-05-26T19:06:35.000Z",
        "document": {
            "id": 5,
            "number": "12345678910",
            "type": "cpf"
        },
        "transferSettings": {
            "id": 1,
            "transferEnabled": true,
            "automaticAnticipationEnabled": true,
            "anticipatableVolumePercentage": 100,
            "createdAt": "2022-05-26T19:06:35.000Z"
        },
        "balance": {
            "available": 6470,
            "updatedAt": "2022-06-02T01:37:48.000Z"
        }
    }
}
```
```

--------------------------------

### GET /v1/transfers/{id}

Source: https://velana.readme.io/reference/buscar-transfer%C3%AAncia

Retrieves details of a specific transfer using its unique ID.

```APIDOC
## GET /v1/transfers/{id}

### Description
Retrieves details of a specific transfer using its unique ID.

### Method
GET

### Endpoint
https://api.velana.com.br/v1/transfers/{id}

### Parameters
#### Path Parameters
- **id** (int32) - Required - ID da transferência.

### Request Example
```bash
curl --request GET \
     --url https://api.velana.com.br/v1/transfers/id \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
- **(structure not provided)** - Description of the transfer details.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Customer Object

Source: https://velana.readme.io/reference/objeto-customer

This section details the properties available within the customer object.

```APIDOC
## Customer Object

### Description
This object represents a customer and contains their personal information, contact details, and associated data.

### Properties

- **id** (int) - Required - The unique identifier for the customer.
- **name** (string) - Required - The full name of the customer.
- **email** (string) - Required - The email address of the customer.
- **phone** (string) - Optional - The customer's phone number, in the format `11999999999`.
- **birthdate** (date) - Optional - The customer's date of birth, in the format `YYYY-MM-DD`.
- **createdAt** (datetime) - Required - The timestamp indicating when the customer record was created.
- **document** (object) - Optional - Contains the customer's document information. Refer to the [document object](/reference/objeto-document) for more details.
- **address** (object) - Optional - Contains the customer's address details. Refer to the [address object](/reference/objeto-address) for more details.
- **revenue** (object) - Optional - Contains information about the customer's spending and refunds. Refer to the [revenue object](/reference/objeto-revenue) for more details.
```

--------------------------------

### GET /customers/{id}

Source: https://velana.readme.io/reference/buscar-cliente

Retrieves detailed information about a specific customer using their unique identifier.

```APIDOC
## GET /customers/{id}

### Description
Retrieves detailed information about a specific customer using their unique identifier.

### Method
GET

### Endpoint
/customers/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the customer to retrieve.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the customer.
- **externalRef** (any) - External reference ID for the customer.
- **name** (string) - The full name of the customer.
- **email** (string) - The email address of the customer.
- **phone** (any) - Phone number of the customer.
- **createdAt** (string) - The date and time when the customer was created (ISO 8601 format).
- **document** (object) - Information about the customer's identification document.
  - **id** (integer) - The unique identifier for the document.
  - **number** (string) - The document number.
  - **type** (string) - The type of document (e.g., 'cpf').
- **address** (object) - The customer's address details.
  - **id** (integer) - The unique identifier for the address.
  - **street** (string) - The street name.
  - **streetNumber** (string) - The street number.
  - **complement** (any) - Additional address details.
  - **zipCode** (string) - The postal code.
  - **neighborhood** (string) - The neighborhood.
  - **city** (string) - The city name.
  - **state** (string) - The state or province abbreviation.
  - **country** (string) - The country code (e.g., 'br').
- **revenue** (object) - Financial revenue information for the customer.
  - **totalAmount** (integer) - Total revenue amount.
  - **totalCount** (integer) - Total number of transactions.
  - **cardAmount** (integer) - Revenue amount from card payments.
  - **cardCount** (integer) - Number of card transactions.
  - **pixAmount** (integer) - Revenue amount from Pix payments.
  - **pixCount** (integer) - Number of Pix transactions.
  - **boletoAmount** (integer) - Revenue amount from Boleto payments.
  - **boletoCount** (integer) - Number of Boleto transactions.
  - **chargebackAmount** (integer) - Amount of chargebacks.
  - **chargebackCount** (integer) - Number of chargebacks.
  - **refundAmount** (integer) - Amount of refunds.
  - **refundCount** (integer) - Number of refunds.
  - **createdAt** (string) - The date and time when the revenue information was recorded (ISO 8601 format).

#### Response Example
```json
{
    "id": 23,
    "externalRef": null,
    "name": "Bruce Wayne",
    "email": "atendimento@peterparker.com",
    "phone": null,
    "createdAt": "2021-09-19T04:05:55.000Z",
    "document": {
        "id": 3,
        "number": "11111111111",
        "type": "cpf"
    },
    "address": {
        "id": 99,
        "street": "Avenida Paulista",
        "streetNumber": "807",
        "complement": null,
        "zipCode": "01311941",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "br"
    },
    "revenue": {
        "totalAmount": 990,
        "totalCount": 1,
        "cardAmount": 990,
        "cardCount": 1,
        "pixAmount": 0,
        "pixCount": 0,
        "boletoAmount": 0,
        "boletoCount": 0,
        "chargebackAmount": 0,
        "chargebackCount": 0,
        "refundAmount": 0,
        "refundCount": 0,
        "createdAt": "2021-09-19T04:05:55.000Z"
    }
}
```
```

--------------------------------

### POST /checkouts

Source: https://velana.readme.io/reference/criar-checkout

Creates a new checkout session. You can specify the total amount, items, payment methods, and a postback URL for status updates. The response includes a secure URL to redirect your user to complete the payment.

```APIDOC
## POST /checkouts

### Description
Creates a new checkout session. You can specify the total amount, items, payment methods, and a postback URL for status updates. The response includes a secure URL to redirect your user to complete the payment.

When a `postbackUrl` is provided, you will receive updates on your API when a transaction is confirmed. After this, no other transaction can be created from this checkout; only the existing transaction can have its status updated.

You can consult the format for postbacks [here](/reference/formato-dos-postbacks#section-checkout).

To update the status of test transactions, consult [here](/reference/atualizar-transação-de-teste).

### Method
POST

### Endpoint
/checkouts

### Parameters
#### Query Parameters
None

#### Request Body
- **amount** (integer) - Required - The total amount in cents (e.g., 500 for R$ 5.00).
- **postbackUrl** (string) - Optional - The URL of your API that will receive checkout updates.
- **items** (array) - Required - An array of items included in the checkout.
  - **title** (string) - Required - The title of the item.
  - **unitPrice** (integer) - Required - The unit price in cents (e.g., 500 for R$ 5.00).
  - **quantity** (integer) - Required - The quantity of the item in the transaction.
  - **tangible** (boolean) - Required - Indicates if the item is physical.
  - **externalRef** (string) - Optional - The reference of the item in your API.
- **settings** (object) - Required - Settings for the checkout.
  - **defaultPaymentMethod** (string) - Required - The payment method that will appear pre-selected in the checkout. Possible values: `credit_card`, `boleto`, `pix`.
  - **requestAddress** (boolean) - Required - Whether the address will be requested during checkout.
  - **requestPhone** (boolean) - Required - Whether the phone number will be requested during checkout.
  - **traceable** (boolean) - Required - Whether the delivery status will be managed by the panel.
  - **boleto** (object) - Optional - Boleto payment settings.
    - **enabled** (boolean) - Required - Whether boleto payment is enabled.
    - **expiresInDays** (integer) - Required - The number of days until the boleto expires.

### Request Example
```json
{
  "amount": 5000,
  "postbackUrl": "https://your-api.com/webhook",
  "items": [
    {
      "title": "Product A",
      "unitPrice": 1000,
      "quantity": 2,
      "tangible": true,
      "externalRef": "prod-a-123"
    },
    {
      "title": "Service B",
      "unitPrice": 3000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "settings": {
    "defaultPaymentMethod": "credit_card",
    "requestAddress": true,
    "requestPhone": false,
    "traceable": true,
    "boleto": {
      "enabled": true,
      "expiresInDays": 5
    }
  },
  "splits": []
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout.
- **secureUrl** (string) - The URL where the user can complete the payment.
- **status** (string) - The current status of the checkout.

#### Response Example
```json
{
  "id": "chk_abc123xyz",
  "secureUrl": "https://checkout.velana.com.br/pay/chk_abc123xyz",
  "status": "pending"
}
```
```

--------------------------------

### Shipping Object Structure

Source: https://velana.readme.io/reference/objeto-shipping

Details the properties of the shipping object, including ID, fee, and address.

```APIDOC
## Shipping Object

### Description
This object contains shipping details required when creating a transaction. The structure is returned in the following format.

### Method
N/A (Object Definition)

### Endpoint
N/A (Object Definition)

### Parameters
#### Properties
- **id** (int) - Description: ID of the shipping data object.
- **fee** (int) - Description: Shipping cost. **This value is NOT added to the total transaction amount**.
- **address** (object) - Description: Delivery address. Refer to the [address object](/reference/objeto-address) documentation.

### Request Example
```json
{
  "id": 12345,
  "fee": 5000,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "US"
  }
}
```

### Response
#### Success Response (200)
- **id** (int) - ID of the shipping data object.
- **fee** (int) - Shipping cost.
- **address** (object) - Delivery address details.

#### Response Example
```json
{
  "id": 12345,
  "fee": 5000,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "US"
  }
}
```
```

--------------------------------

### Transaction Creation API

Source: https://velana.readme.io/reference/criar-transacao

This section details the structure for creating a transaction, including customer information, shipping details, items, and payment specifics like boleto expiration.

```APIDOC
## POST /transactions

### Description
Creates a new transaction with detailed customer, shipping, and item information.

### Method
POST

### Endpoint
/transactions

### Parameters
#### Request Body
- **customer** (object) - Required - Customer details including name, email, phone, and document.
  - **name** (string) - Required - Customer's full name.
  - **email** (string) - Required - Customer's email address.
  - **document** (object) - Required - Customer's identification document.
    - **number** (string) - Required - Document number (CPF or CNPJ).
    - **type** (string) - Required - Document type. Possible values: "cpf", "cnpj".
  - **phone** (string) - Optional - Customer's phone number in the format 1199999999.
  - **externalRef** (string) - Optional - Customer's reference ID in your system.
- **shipping** (object) - Required - Shipping details.
  - **fee** (integer) - Required - Shipping fee. This is not added to the total transaction amount.
  - **address** (object) - Required - Shipping address.
    - **street** (string) - Required - Street name.
    - **streetNumber** (string) - Required - Street number.
    - **complement** (string) - Optional - Address complement.
    - **zipCode** (string) - Required - Postal code.
    - **neighborhood** (string) - Required - Neighborhood.
    - **city** (string) - Required - City name.
    - **state** (string) - Required - State abbreviation (e.g., "SP").
    - **country** (string) - Required - Country code (e.g., "br").
- **items** (array) - Required - List of items in the transaction.
  - **item** (object) - Required - Details of each item.
    - **title** (string) - Required - Item title.
    - **unitPrice** (integer) - Required - Unit price in cents (e.g., 500 for R$ 5.00).
    - **quantity** (integer) - Required - Quantity of the item.
    - **tangible** (boolean) - Required - Indicates if the item is physical.
    - **externalRef** (string) - Optional - Item's reference ID in your system.
- **boleto** (object) - Optional - Boleto specific information.
  - **expiresInDays** (integer) - Optional - Number of days until the boleto expires.

### Request Example
```json
{
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "document": {
      "number": "12345678900",
      "type": "cpf"
    },
    "phone": "11987654321",
    "externalRef": "cust_123"
  },
  "shipping": {
    "fee": 500,
    "address": {
      "street": "Main St",
      "streetNumber": "123",
      "complement": "Apt 4B",
      "zipCode": "01000000",
      "neighborhood": "Downtown",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "br"
    }
  },
  "items": [
    {
      "title": "Product A",
      "unitPrice": 1000,
      "quantity": 2,
      "tangible": true,
      "externalRef": "prod_A"
    },
    {
      "title": "Service B",
      "unitPrice": 5000,
      "quantity": 1,
      "tangible": false,
      "externalRef": "serv_B"
    }
  ],
  "boleto": {
    "expiresInDays": 5
  }
}
```

### Response
#### Success Response (200)
- **transactionId** (string) - The unique identifier for the created transaction.
- **status** (string) - The current status of the transaction.
- **paymentUrl** (string) - URL for completing the payment (if applicable).

#### Response Example
```json
{
  "transactionId": "txn_abc123",
  "status": "pending_payment",
  "paymentUrl": "https://example.com/pay/txn_abc123"
}
```
```
Tokens:
Raw