Primeiros passos

Para começar a utilizar as APIs da Vipsgateway, é essencial compreender os processos de integração dos serviços disponíveis e os requisitos para sua utilização.

1. Obtenha sua Chave de API

Acesse sua conta na plataforma, navegue até a seção Configurações > API e gere sua chave. Ela será usada para autenticar todas as suas requisições.

Autenticação

A API utiliza o método Bearer Token. Inclua sua chave de API no cabeçalho Authorization. Requisições não autenticadas retornarão um erro 401 Unauthorized.

Exemplo de Cabeçalho

                        Authorization: Bearer SUA_CHAVE_SECRETA_DE_API
Accept: application/json
Content-Type: application/json
                    

Criar Transação

Este endpoint permite iniciar uma nova transação de pagamento.

POST /api/transactions

Corpo da Requisição

REQUEST BODY

{
  "product_hash_id": "prod_a1b2c3d4e5f6",
  "customer": {
    "name": "João da Silva",
    "email": "joao.silva@email.com",
    "phone": "11999998888",
    "document": "12345678900"
  }
}

Resposta de Sucesso

RESPONSE (200 OK )

{
  "success": true,
  "message": "Transação iniciada com sucesso!",
  "transaction_id": "txn_a1b2c3d4e5",
  "pix_copy_paste": "00020126...",
  "product_name": "Nome do Produto Exemplo",
  "total_price": 99.90
}

Consultar Transação

Use este endpoint para verificar o status de uma transação criada anteriormente.

GET /api/transactions/{transactionId}

Resposta de Sucesso

RESPONSE (200 OK)

{
  "success": true,
  "transaction_id": "txn_a1b2c3d4e5",
  "status": "paid",
  "created_at": "2025-09-24T10:00:00Z",
  "updated_at": "2025-09-24T10:01:30Z",
  "product": { "name": "Nome do Produto Exemplo" },
  "customer": { "name": "João da Silva", "email": "joao.silva@email.com" },
  "total_price": 99.90
}

Códigos de Erro

A API utiliza códigos de status HTTP padrão para indicar o sucesso ou a falha de uma requisição.

Exemplos de Erros

// 401 Unauthorized
{ "message": "Token de autenticação não fornecido." }

// 404 Not Found
{ "success": false, "message": "Transação não encontrada." }

// 422 Unprocessable Entity
{
  "message": "Dados inválidos.",
  "errors": {
    "product_hash_id": ["O campo product hash id é obrigatório."]
  }
}