Iniciar pagamento PIX
Este endpoint permite iniciar um pagamento via PIX a partir de uma chave Pix ou código “copia e cola”. A operação realiza a validação da chave, identifica o recebedor e cria uma transação de transferência PIX, retornando todos os dados necessários para acompanhamento.
Obs: A palavra urlServidor deve ser substituída pela url do servidor.
Parâmetros da Requisição
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
integration-key | string | Sim | Chave de integração. |
x-token | string | Sim | Token utilizado para autenticação. Pode ser encontrado no portal da API. |
Authorization | Auth Type Bearer Token | Sim | Inserir o Bearer Token, gerado na rota Auth |
Exemplo de header da requisição
curl--request POST \
--location 'urlServidor/v1/marketplace/banking/transfers/pix-init' \
--header 'integration-key: your_integration_key' \
--header 'x-token: your_x_token' \
--header 'Authorization: Bearer {{bearer_token}}' \📥 Body da requisição
{
"type": "RANDOM",
"key": "597b7eed-ab88-4c2b-947a-c8729f8e21ed"
}Variáveis
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | Consulte Tipo da chave. |
| key | string | Condicional | Chave Pix. Obrigatória quando type ≠ HASH. |
| hash_code | string | Condicional | Código copia e cola. Obrigatório quando type = HASH. |
Tipos de chave (type)
| Valor | Descrição |
|---|---|
| HASH | Código copia e cola |
| CPF | CPF |
| CNPJ | CNPJ |
| PHONE | Telefone |
| RANDOM | Chave aleatória |
Modelo Response
{
"type": "PIX",
"status": "PROCESSING",
"establishment_id": "155392",
"init_type": "DICT",
"transaction_identification": null,
"gateway_authorization": "CELCOIN",
"fees_details": [],
"expected_at": "2026-04-28T17:47:59.156Z",
"pixKey": "597b7eed-ab88-4c2b-947a-c8729f8e21ed",
"recipient": {
"first_name": "DS DESENVOLVIMENTO DE SOFTWARES, APLICATIVOS E SISTEMAS LTDA",
"document": "26244342000140",
"bank_ispb": "13935893",
"bank_name": "CELCOIN INSTITUICAO DE PAGAMENTO S.A.",
"routing_number": "****",
"routing_check_digit": "*",
"account_number": "*******",
"account_check_digit": "*",
"account_type": "CHECKING",
"pix_key": "597b7eed-ab88-4c2b-947a-c8729f8e21ed",
"pix_key_type": "EVP",
"type": "CHECKING"
},
"payer": {
"bank_code": "509",
"bank_name": "CELCOIN IP S.A.",
"routing_number": "0001",
"account_number": "422345",
"account_check_digit": "9",
"establishment": {
"id": 155392,
"first_name": "EC Final3",
"last_name": "Final 3",
"document": "31820784000128",
"type": "BUSINESS",
"access_type": "ACQUIRER",
"risk": "LOW",
"active": true,
"mcc": "5044"
},
"marketplace": {
"id": 26,
"nickname": "Parceiro Integrações",
"first_name": "Webhooks Integrações",
"last_name": "API Integrações",
"document": "60274849000185",
"type": "LICENSED",
"active": true
},
"type": "CHECKING"
},
"history": [
{
"status": "CREATED",
"created_at": "2026-04-28T17:47:59.156Z",
"_id": "69f0f2cf71ad0804c940575b"
},
{
"status": "PROCESSING",
"created_at": "2026-04-28T17:47:59.157Z",
"_id": "69f0f2cf71ad0804c940575c"
}
],
"method": "OUT",
"description": "",
"init_id": "E13935893202604281747Y3pL5YlGFRs",
"end_to_end": "E13935893202604281747Y3pL5YlGFRs",
"reprocessed": false,
"commission_id": null,
"reversal_transaction_id": null,
"transfer_id_fees_origin": null,
"_id": "69f0f2cf71ad0804c940575a",
"created_at": "2026-04-28T17:47:59.161Z",
"updated_at": "2026-04-28T17:47:59.161Z",
"__v": 0
}📊 Estrutura da Resposta – PIX OUT
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
_id | string | Sim | ID único do pagamento. |
type | string | Sim | Tipo da transação (ex: PIX). |
status | string | Sim | Status atual da transação. |
establishment_id | string | Sim | ID do estabelecimento pagador. |
init_type | string | Sim | Tipo de inicialização do Pix (ex: DICT, HASH). |
transaction_identification | string | null | Não |
gateway_authorization | string | Sim | Gateway responsável pela autorização. |
fees_details | array | Sim | Lista de taxas aplicadas. |
expected_at | string (datetime) | Sim | Data prevista de conclusão. |
pixKey | string | Sim | Chave Pix utilizada na transação. |
recipient | object | Sim | Dados do recebedor. |
payer | object | Sim | Dados do pagador. |
history | array | Sim | Histórico de status da transação. |
method | string | Sim | Direção da transação (IN ou OUT). |
description | string | Sim | Descrição da transação. |
init_id | string | Sim | ID retornado na inicialização do Pix. |
end_to_end | string | Sim | Identificador único da transação no Bacen. |
reprocessed | boolean | Sim | Indica se houve reprocessamento. |
commission_id | string | null | ID da comissão. |
reversal_transaction_id | string | null | ID da reversão. |
transfer_id_fees_origin | string | null | ID da reversão. |
created_at | string (datetime) | Sim | Data de criação do registro. |
updated_at | string (datetime) | Sim | Data da última atualização. |
__v | number | Sim | Versão do documento. |
👤 Objeto recipient (Recebedor)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
first_name | string | Sim | Nome / Razão social do recebedor. |
document | string | Sim | CPF ou CNPJ do recebedor. |
bank_ispb | string | Sim | ISPB do banco. |
bank_name | string | Sim | Nome do banco. |
routing_number | string | Sim | Número da agência. |
routing_check_digit | string | Sim | Dígito da agência. |
account_number | string | Sim | Número da conta. |
account_check_digit | string | Sim | Dígito da conta. |
account_type | string | Sim | Tipo da conta (ex: CHECKING). |
pix_key | string | Sim | Chave Pix do recebedor. |
pix_key_type | string | Sim | Tipo da chave (ex: EVP, CPF, EMAIL). |
type | string | Sim | Tipo da conta. |
🏦 Objeto payer (Pagador)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
bank_code | string | Sim | Código do banco. |
bank_name | string | Sim | Nome do banco. |
routing_number | string | Sim | Agência bancária. |
account_number | string | Sim | Número da conta. |
account_check_digit | string | Sim | Dígito da conta. |
type | string | Sim | Tipo da conta. |
establishment | object | Sim | Dados do estabelecimento pagador. |
marketplace | object | Sim | Dados do marketplace. |
🏢 Objeto payer.establishment
| Campo | Tipo | Descrição |
|---|---|---|
id | number | ID do estabelecimento. |
first_name | string | Nome. |
last_name | string | Nome complementar. |
document | string | CPF/CNPJ. |
type | string | Tipo (ex: BUSINESS). |
access_type | string | Tipo de acesso. |
risk | string | Nível de risco. |
active | boolean | Indica se está ativo. |
mcc | string | Código MCC. |
🏪 Objeto payer.marketplace
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | number | Sim | ID do marketplace. |
nickname | string | Sim | Apelido do marketplace. |
first_name | string | Sim | Primeiro nome ou razão social. |
last_name | string | Sim | Nome complementar ou nome fantasia. |
document | string | Sim | CPF ou CNPJ do marketplace. |
type | string | Sim | Tipo do marketplace (ex: LICENSED). |
active | boolean | Sim | Indica se o marketplace está ativo. |
🧾 Objeto history
| Campo | Tipo | Descrição |
|---|---|---|
status | string | Status da transação naquele momento. |
created_at | string | Data do evento. |
_id | string | ID do registro de histórico. |
Registro de logsÉ obrigatório manter registros em logs de todas as validações de OTP realizadas. A Paytime pode solicitar, a qualquer momento, relatórios e evidências desses logs para fins de auditoria e comprovação de segurança em movimentações financeiras.
Códigos de resposta
Consulte a página com os status: Status de respostas
Para mais detalhes sobre os parâmetros e funcionamento da API, acesse a documentação oficial da Paytime.
Updated 3 months ago
Did this page help you?