Skip to main content

P2P Transfer

Transfers funds internally between two Pliqz accounts.

Access is through Gateway Payment, using the public endpoints described on this page.

MethodPOST
Path/api/p2p/transfer
AuthenticationAuthorization: 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.

MethodGET
Path/api/p2p/transfer/:transaction_id
AuthenticationAuthorization: Bearer <token> and Channel-ID
BodyNone

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​

NameLocationRequiredDescription
transaction_idPathYesNon-zero transfer UUID returned by POST. This is not the operation_id.
AuthorizationHeaderYesValid JWT in the Bearer <token> format.
Channel-IDHeaderYesNon-zero UUID of the transfer's origin channel.
AcceptHeaderNoUse 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"
}
FieldTypeDescription
statusstringStored state: REQUESTED (requested), RECEIVED (completed), or ERROR (failed). Unlike the "success" returned by POST.
transaction_idUUIDOriginal identifier of the queried transfer.
operation_idstringIdempotency key supplied when creating the transfer.
amountintegerOriginal amount in cents.
descriptionstringDescription supplied when creating the transfer.
receipt_urlstringReceipt URL; may be an empty string.
created_atstring (RFC 3339)Original transfer creation timestamp, not the last state change timestamp.
messagestring, optionalPublic 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​

HTTPSituation
400 Bad RequestInvalid/zero transaction_id, or missing, invalid, or zero Channel-ID.
401 UnauthorizedMissing, malformed, invalid, or expired token.
403 ForbiddenQuery not authorized, including channel access or cash-out permission restrictions.
404 Not FoundTransfer not found for the supplied origin channel.
422 Unprocessable EntityBusiness error. This does not represent the ERROR state of a transfer that was found.
500 Internal Server ErrorInternal failure while querying the transfer.
502 Bad GatewayA valid query response could not be obtained.
504 Gateway TimeoutCommunication 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.