Transferência P2P
Realiza uma transferência interna entre duas contas Pliqz.
O acesso é feito pelo Gateway Payment, usando os endpoints públicos descritos nesta página.
| Método | POST |
| Path | /api/p2p/transfer |
| Autenticação | Authorization: Bearer <token> e Channel-ID |
Regras de autorização
- A conta de origem é obtida exclusivamente do header
Channel-IDinformado e autorizado.
Corpo da requisição
{
"channel_destination_id": "5b3ac5c0-0caf-4c1d-a2b9-5e2ddac1f5dc",
"amount": 1500,
"description": "Repasse individual",
"operation_id": "repasse-pedido-123"
}
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
channel_destination_id | UUID | Sim | Channel de destino. |
amount | integer | Sim | Valor em centavos. Ex.: 1500 representa R$ 15,00. |
description | string | Sim | Descrição da transferência. |
operation_id | string | Sim | Chave global de idempotência. |
Resposta de sucesso
200 OK
{
"status": "success",
"transaction_id": "313077f8-9c8d-4416-b7a0-767469c0cc0f",
"receipt_url": "",
"operation_id": "repasse-pedido-123"
}
Idempotência
operation_id é global e é retida por cinco minutos. Reenvios nesse período retornam
o resultado original, sem executar uma nova transferência.
O valor de amount é utilizado em centavos, sem conversão, e a API não
realiza retries automáticos da transferência.
Consultar transferência
Consulta o estado atual de uma transferência P2P pelo transaction_id retornado
na criação. A consulta é somente leitura e não executa uma nova transferência.
| Método | GET |
| Path | /api/p2p/transfer/:transaction_id |
| Autenticação | Authorization: Bearer <token> e Channel-ID |
| Corpo | Não possui |
O Payment consulta o estado da transferência e retorna os campos definidos neste contrato. O cliente deve utilizar o host do Payment, conforme os ambientes disponíveis.
Parâmetros e headers
| Nome | Local | Obrigatório | Descrição |
|---|---|---|---|
transaction_id | Path | Sim | UUID não zerado da transferência retornado pelo POST. Não é o operation_id. |
Authorization | Header | Sim | Token JWT válido no formato Bearer <token>. |
Channel-ID | Header | Sim | UUID não zerado do canal de origem da transferência. |
Accept | Header | Não | Utilize application/json. |
A consulta exige autorização para a conta e permissão de cash-out. Uma transferência inexistente ou que não pertence ao canal de origem informado retorna 404, sem expor dados de outro canal.
Exemplo cURL
curl --request GET \
'https://gateway-payment-hm.pliqz.com.br/api/p2p/transfer/313077f8-9c8d-4416-b7a0-767469c0cc0f' \
--header 'Authorization: Bearer SEU_TOKEN_JWT' \
--header 'Channel-ID: UUID_DO_CANAL_DE_ORIGEM' \
--header 'Accept: application/json'
Resposta da consulta
200 OK — consulta realizada. O HTTP 200 indica sucesso da consulta, não
necessariamente da transferência; verifique o campo status.
{
"status": "RECEIVED",
"transaction_id": "313077f8-9c8d-4416-b7a0-767469c0cc0f",
"operation_id": "repasse-pedido-123",
"amount": 1500,
"description": "Repasse individual",
"receipt_url": "",
"created_at": "2026-10-21T03:00:00Z"
}
| Campo | Tipo | Descrição |
|---|---|---|
status | string | Estado persistido: REQUESTED (solicitada), RECEIVED (concluída) ou ERROR (falhou). Diferente do "success" retornado pelo POST. |
transaction_id | UUID | Identificador original da transferência consultada. |
operation_id | string | Chave de idempotência informada na criação. |
amount | integer | Valor original em centavos. |
description | string | Descrição informada na criação. |
receipt_url | string | URL do comprovante; pode ser uma string vazia. |
created_at | string (RFC 3339) | Data e hora de criação da transferência original, não da última mudança de estado. |
message | string, opcional | Mensagem pública da falha quando aplicável; omitida quando vazia. |
Uma transferência com status: "ERROR" também retorna 200, com uma mensagem
pública, por exemplo "Saldo insuficiente para concluir a transferência.".
Detalhes internos do provedor não são expostos.
Erros da consulta
| HTTP | Situação |
|---|---|
| 400 Bad Request | transaction_id inválido/zerado ou Channel-ID ausente, inválido ou zerado. |
| 401 Unauthorized | Token ausente, mal formatado, inválido ou expirado. |
| 403 Forbidden | Consulta não autorizada, inclusive por restrições de acesso ao canal ou de permissão de cash-out. |
| 404 Not Found | Transferência não encontrada para o canal de origem informado. |
| 422 Unprocessable Entity | Erro de negócio. Não representa o estado ERROR de uma transferência encontrada. |
| 500 Internal Server Error | Falha interna ao consultar a transferência. |
| 502 Bad Gateway | Não foi possível obter uma resposta válida para a consulta. |
| 504 Gateway Timeout | Tempo de comunicação excedido ao consultar a transferência. |
Erros de validação, consulta e comunicação usam message, por exemplo:
{ "message": "Transferência não encontrada." }
Outras mensagens incluem "Identificador da transferência inválido.",
"insira um Channel-ID válido na header" e
"Não foi possível consultar a transferência.". No timeout, a mensagem é
"Tempo de comunicação excedido. Não foi possível consultar a transferência.".
Erros de autenticação e determinados erros de autorização usam error:
{ "error": "Token inválido" }
O timeout de comunicação da consulta é de 12 segundos, sem retries
automáticos. A consulta não exige o reenvio
de operation_id nem do corpo utilizado na criação.