Pular para o conteúdo principal

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étodoPOST
Path/api/p2p/transfer
AutenticaçãoAuthorization: Bearer <token> e Channel-ID

Regras de autorização​

  • A conta de origem é obtida exclusivamente do header Channel-ID informado e autorizado.

Corpo da requisição​

{
"channel_destination_id": "5b3ac5c0-0caf-4c1d-a2b9-5e2ddac1f5dc",
"amount": 1500,
"description": "Repasse individual",
"operation_id": "repasse-pedido-123"
}
CampoTipoObrigatórioDescrição
channel_destination_idUUIDSimChannel de destino.
amountintegerSimValor em centavos. Ex.: 1500 representa R$ 15,00.
descriptionstringSimDescrição da transferência.
operation_idstringSimChave 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étodoGET
Path/api/p2p/transfer/:transaction_id
AutenticaçãoAuthorization: Bearer <token> e Channel-ID
CorpoNã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​

NomeLocalObrigatórioDescrição
transaction_idPathSimUUID não zerado da transferência retornado pelo POST. Não é o operation_id.
AuthorizationHeaderSimToken JWT válido no formato Bearer <token>.
Channel-IDHeaderSimUUID não zerado do canal de origem da transferência.
AcceptHeaderNãoUtilize 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"
}
CampoTipoDescrição
statusstringEstado persistido: REQUESTED (solicitada), RECEIVED (concluída) ou ERROR (falhou). Diferente do "success" retornado pelo POST.
transaction_idUUIDIdentificador original da transferência consultada.
operation_idstringChave de idempotência informada na criação.
amountintegerValor original em centavos.
descriptionstringDescrição informada na criação.
receipt_urlstringURL do comprovante; pode ser uma string vazia.
created_atstring (RFC 3339)Data e hora de criação da transferência original, não da última mudança de estado.
messagestring, opcionalMensagem 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​

HTTPSituação
400 Bad Requesttransaction_id inválido/zerado ou Channel-ID ausente, inválido ou zerado.
401 UnauthorizedToken ausente, mal formatado, inválido ou expirado.
403 ForbiddenConsulta não autorizada, inclusive por restrições de acesso ao canal ou de permissão de cash-out.
404 Not FoundTransferência não encontrada para o canal de origem informado.
422 Unprocessable EntityErro de negócio. Não representa o estado ERROR de uma transferência encontrada.
500 Internal Server ErrorFalha interna ao consultar a transferência.
502 Bad GatewayNão foi possível obter uma resposta válida para a consulta.
504 Gateway TimeoutTempo 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.