P2P Transfer
Transfers funds internally between two Pliqz accounts.
Access is through Gateway Payment, using the public endpoints described on this page.
| Method | POST |
| Path | /api/p2p/transfer |
| Authentication | Authorization: Bearer <token> and Channel-ID |
Request body
{
"channel_destination_id": "5b3ac5c0-0caf-4c1d-a2b9-5e2ddac1f5dc",
"amount": 1500,
"description": "Individual transfer",
"operation_id": "transfer-order-123"
}
amount is an integer in cents. The origin account is always read from the
authorized Channel-ID. The integration requires cash-out permission.
Success response
200 OK
{
"status": "success",
"transaction_id": "313077f8-9c8d-4416-b7a0-767469c0cc0f",
"receipt_url": "",
"operation_id": "transfer-order-123"
}
Idempotency and states
operation_id is global for five minutes. Repeated requests return the original
result without executing a second transfer. Stored states are REQUESTED,
RECEIVED, and ERROR.
The API uses amount in cents without conversion and does not retry
transfers automatically.
Get transfer
Retrieves the current state of a P2P transfer using the transaction_id returned
when it was created. This read-only request does not execute another transfer.
| Method | GET |
| Path | /api/p2p/transfer/:transaction_id |
| Authentication | Authorization: Bearer <token> and Channel-ID |
| Body | None |
Payment retrieves the transfer state and returns the fields defined in this contract. Clients must use the Payment host listed in the available environments.
Parameters and headers
| Name | Location | Required | Description |
|---|---|---|---|
transaction_id | Path | Yes | Non-zero transfer UUID returned by POST. This is not the operation_id. |
Authorization | Header | Yes | Valid JWT in the Bearer <token> format. |
Channel-ID | Header | Yes | Non-zero UUID of the transfer's origin channel. |
Accept | Header | No | Use application/json. |
The query requires account authorization and cash-out permission. A transfer that does not exist or does not belong to the supplied origin channel returns 404, without exposing another channel's data.
cURL example
curl --request GET \
'https://gateway-payment-hm.pliqz.com.br/api/p2p/transfer/313077f8-9c8d-4416-b7a0-767469c0cc0f' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'Channel-ID: ORIGIN_CHANNEL_UUID' \
--header 'Accept: application/json'
Query response
200 OK — query succeeded. HTTP 200 indicates a successful query, not
necessarily a successful transfer; check the status field.
{
"status": "RECEIVED",
"transaction_id": "313077f8-9c8d-4416-b7a0-767469c0cc0f",
"operation_id": "transfer-order-123",
"amount": 1500,
"description": "Individual transfer",
"receipt_url": "",
"created_at": "2026-10-21T03:00:00Z"
}
| Field | Type | Description |
|---|---|---|
status | string | Stored state: REQUESTED (requested), RECEIVED (completed), or ERROR (failed). Unlike the "success" returned by POST. |
transaction_id | UUID | Original identifier of the queried transfer. |
operation_id | string | Idempotency key supplied when creating the transfer. |
amount | integer | Original amount in cents. |
description | string | Description supplied when creating the transfer. |
receipt_url | string | Receipt URL; may be an empty string. |
created_at | string (RFC 3339) | Original transfer creation timestamp, not the last state change timestamp. |
message | string, optional | Public failure message when applicable; omitted when empty. |
A transfer with status: "ERROR" also returns 200, with a public message
such as "Saldo insuficiente para concluir a transferência.".
Internal provider details are not exposed. API messages remain in Portuguese.
Query errors
| HTTP | Situation |
|---|---|
| 400 Bad Request | Invalid/zero transaction_id, or missing, invalid, or zero Channel-ID. |
| 401 Unauthorized | Missing, malformed, invalid, or expired token. |
| 403 Forbidden | Query not authorized, including channel access or cash-out permission restrictions. |
| 404 Not Found | Transfer not found for the supplied origin channel. |
| 422 Unprocessable Entity | Business error. This does not represent the ERROR state of a transfer that was found. |
| 500 Internal Server Error | Internal failure while querying the transfer. |
| 502 Bad Gateway | A valid query response could not be obtained. |
| 504 Gateway Timeout | Communication timeout while querying the transfer. |
Validation, query, and communication errors use message, for example:
{ "message": "Transferência não encontrada." }
Other messages include "Identificador da transferência inválido.",
"insira um Channel-ID válido na header", and
"Não foi possível consultar a transferência.". The timeout message is
"Tempo de comunicação excedido. Não foi possível consultar a transferência.".
Authentication errors and certain authorization errors use error:
{ "error": "Token inválido" }
The query has a 12-second communication timeout and is not retried
automatically. The query does not require resubmitting
operation_id or the original request body.