Documentação da API PixPlay BR

Esta documentação descreve como integrar com o endpoint de consulta de depósitos da PixPlay BR para verificar o status de uma transação.

1. Endpoint

2. Autenticação

Todas as requisições para este endpoint devem ser autenticadas usando um token de API. O token deve ser enviado no cabeçalho da requisição no formato Bearer.

Cabeçalho de Autenticação:

Authorization: Bearer [SEU_TOKEN_DE_API]

Exemplo:

Authorization: Bearer 73b88cd2947eb34e24d24600238ac86908203e9f3962bdaed595681f6825614a

Nota: Seu token de API é pessoal e secreto. Não o compartilhe publicamente e mantenha-o seguro.

3. Requisição (Request)

A requisição deve ser enviada via POST e conter um corpo no formato JSON.

Cabeçalho da Requisição:

Content-Type: application/json

Corpo da Requisição (Body):

O corpo deve ser um objeto JSON com o campo external_id, que é o identificador único da transação que você deseja consultar.

Campo	Tipo	Obrigatório	Descrição
external_id	string	Sim	O ID da transação gerado pelo seu sistema.

Exemplo do Corpo da Requisição:

{
  "external_id": "pedido_12347856"
}

4. Respostas (Responses)

A API retornará uma resposta no formato JSON com um código de status HTTP apropriado.

4.1. Resposta de Sucesso (200 OK)

A requisição foi processada com sucesso e o status do depósito foi encontrado.

Exemplo de Resposta:

{
    "success": true,
    "message": "Status do depósito consultado com sucesso.",
    "data": {
        "external_id": "pedido_12347856",
        "valor": "10.00",
        "status": "pago",
        "created_at": "2025-08-07 18:55:50",
        "updated_at": "2025-08-08 19:00:32"
    }
}

Possíveis valores para data.status:

• pendente: O pagamento foi iniciado, mas ainda não foi confirmado.
• pago: O pagamento foi recebido e a transação foi concluída.
• cancelled: O pagamento foi cancelado ou expirou.

4.2. Respostas de Erro

Em caso de falha, a API retornará uma das seguintes respostas com o código de status HTTP correspondente.

• Código 400 Bad Request: O corpo da requisição é inválido ou está faltando o campo external_id.

  {
      "success": false,
      "message": "O campo 'external_id' é obrigatório."
  }

• Código 401 Unauthorized: O token de autenticação está ausente, é inválido ou foi revogado.

  {
      "success": false,
      "message": "Token de autenticação inválido ou revogado."
  }

• Código 404 Not Found: Nenhuma transação de depósito foi encontrada para o external_id e token fornecidos.

  {
      "success": false,
      "message": "Transação de depósito não encontrada para o ID externo e usuário fornecidos."
  }

• Código 405 Method Not Allowed: O método da requisição não é POST.

  {
      "success": false,
      "message": "Método não permitido. Use POST."
  }

• Código 500 Internal Server Error: Ocorreu um erro interno no servidor.

  {
      "success": false,
      "message": "Erro interno do servidor ao consultar o depósito."
  }

5. Exemplo de Integração (cURL)

Você pode testar e simular a requisição usando a linha de comando cURL:

curl --location 'https://api.pixplaybr.com/api/v1/consulta_deposito.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 73b88cd2947eb34e24d24600238ac86908203e9f3962bdaed595681f6825614a' \
--data '{
    "external_id": "DEP_5_1754415317_4275"
}'