Documentação
  1. GESTÃO DE TRANSAÇÕES
  2. Transações

Criar Transação Pix Qr Code

Esse endpoint permite a criação de uma nova transação no sistema da Paytime. É utilizada para registrar uma transação e obter os dados necessários para o seu processamento. O endpoint requer autenticação via cabeçalhos e os detalhes da transação devem ser fornecidos no corpo da requisição.

🔼

POST {urlServidor}/v1/marketplace/transactions

Obs: A palavra urlServidor deve ser substituída pela url do servidor.

Parâmetros da Requisição

Headers

NomeTipoObrigatórioDescrição
integration-keystringSimChave de integração.
x-tokenstringSimToken de autenticação. Pode ser encontrado em nosso portal na guia de integração.
AuthorizationAuth Type Bearer TokenSimInserir o Bearer Token, gerado na rota Auth

Exemplo de header da requisição

curl--request POST \
--location '{urlServidor}/v1/marketplace/transactions' \
--header 'integration-key: your_integration_key' \
--header 'x-token: your_x_token
--header 'establishment_id:establishment_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{bearer_token}}' \

Body da requisição

O corpo da requisição deve ser enviado no formato JSON, conforme descrito abaixo:

NomeTipoObrigatórioDescrição
payment_typestringSimTipo de transação. PIX.
amountnumberSimValor da transação em centavos.
intereststringSimCLIENT: o valor das taxas serão repassadas ao cliente, aumentando o valor bruto da transação. - STORE: o valor das taxas serão cobradas do estabelecimento, mantendo o valor bruto da transação.
clientobjectNãoDados do cliente opcional.

Estrutura dos Objetos

💲Payload do objeto da transação

NomeTipoObrigatórioDescrição
payment_typestringSimTipo de transação. PIX.
amountnumberSimValor da transação em centavos.
intereststringNãoQuem arcará com os custos das taxas. Valores permitidos: CLIENT, ESTABLISHMENT.
reference_idstringNãoIdentificador definido pelo cliente, utilizado para controle interno. Limite máximo de 100 caracteres.

👥 Payload do objeto cliente

NomeTipoObrigatórioDescrição
first_namestringNãoNome/Razão Social do cliente.
last_namestringNãoSobrenome/nome fantasia do cliente.
documentstringNãoCPF/CNPJ do cliente.
phonestringNãoNúmero de telefone do cliente.
emailstringNãoEmail do cliente.

🏢 Payload do objeto endereço

O endereço é opcional no envio do payload e deve ser a estrutura

NomeTipoObrigatórioDescrição
streetstringSimLogradouro, rua
numberstringSimNúmero.
complementstringNãoComplemento.
neighborhoodstringSimBairro.
citystringSimCidade.
statestringSimEstado. Possíveis valores: Acre, Alagoas, Amapá, Amazonas, Bahia, Ceará, Distrito Federal, Espirito Santo, Goiás, Maranhão, Mato Grosso do Sul, Mato Grosso, Minas Gerais, Pará, Paraíba, Paraná, Pernambuco, Piauí, Rio de Janeiro, Rio Grande do Norte, Rio Grande do Sul, Rondônia, Roraima, Santa Catarina, São Paulo, Sergipe, Tocantins.
countrystringSimPaís. Exemplo: BR.
zip_codestringSimCEP. Deve conter exatamente 8 caracteres.

🔀 Payload info_additional (opcional)

CampoTipoObrigatórioDescrição
info_additionalarrayOpcionalLista de pares chave-valor com informações adicionais da transação. Utilizado principalmente em transações do tipo PIX, podendo incluir identificadores adicionais definidos pelo parceiro.
info_additional[].keystringSimChave identificadora da informação adicional. Exemplo: "origin_system".
info_additional[].valuestringSimValor vinculado à chave. Exemplo: "ERP12345".

🔀 Payload split (opcional)

CampoTipoObrigatórioDescrição
split.titlestringSimTítulo para identificar o split na transação. Exemplo: "Comissão do Representante"
split.divisionstringSimTipo de divisão a ser aplicada entre os participantes. Valores possíveis: <br>• PERCENTAGE (porcentagem)<br>• CURRENCY (valor fixo)
split.establishmentsarraySimLista dos estabelecimentos que participarão do split.
split.establishments[].idnumberSimID do estabelecimento secundário. Este será o recebedor de parte do valor da transação.
split.establishments[].valuenumberSimValor que será destinado ao estabelecimento: <br>• Percentual, se division for PERCENTAGE <br>• Em centavos, se division for CURRENCY

Exemplo do Body para criar a transação

{
    "payment_type": "PIX",
    "amount": 3005,
    "interest": "CLIENT",
    "client": {
            "first_name":"João",
            "last_name": "da Silva",
            "document": "10068114001",
            "phone": "00000000001",
            "email": "[email protected]"
        },
          "info_additional": [//Opcional
            {
            "key": "Origem da Venda",
            "value": "ClienteID"
            }
        ],
        "split": {//Opcional
        "title": "Split PIX",
        "division": "PERCENTAGE",
        "establishments": [
        {
            "id": 155100,
            "value": 30
        }
        ]
    }
}

Exemplo de Resposta (200):

{
    "_id": "68cd583ac28afa3e818e48ed",
    "status": "PENDING",
    "interest": "CLIENT",
    "establishment": {
        "id": 1085,
        "type": "INDIVIDUAL",
        "first_name": "EC Cobranças API",
        "last_name": null,
        "document": "10068114001",
        "access_type": "ACQUIRER"
    },
    "marketplace": {
        "id": 26,
        "type": "LICENSED",
        "nickname": "Parceiro Integrações",
        "active": true,
        "first_name": "Webhooks Integrações",
        "last_name": "API Integrações",
        "document": "60274849000185"
    },
    "representative": {
        "id": 63,
        "marketplace_id": 26,
        "active": true,
        "first_name": "EC Cobranças API",
        "last_name": null,
        "document": "10068114001"
    },
    "amount": 3005,
    "original_amount": 3041,
    "fees": 36,
    "type": "PIX",
    "gateway_key": "b4ab240dc9284fdaacf98ea7ec85caa9",
    "gateway_authorization": "PAYTIME",
    "card": null,
    "installments": 1,
    "customer": {
        "_id": "68cd583ac28afa3e818e48da"
    },
    "point_of_sale": {
        "type": "ONLINE",
        "identification_type": "API"
    },
    "acquirer": {
        "name": "SANTANDER",
        "key": "60701190000104",
        "gateway_key": "b4ab240dc9284fdaacf98ea7ec85caa9",
        "_id": "68cd583ac28afa3e818e48fe"
    },
    "expected_on": [
        {
            "date": "2025-09-22T12:00:00.088Z",
            "amount": 3005,
            "status": "PENDING",
            "installment": 1
        }
    ],
    "emv": "00020101021226910014BR.GOV.BCB.PIX2569spi-h.santander.com.br/pix/qr/v2/af581bdc-624e-4333-af38-1adaddfa6ce05204000053039865802BR5914PMD BASHAR RIO6009SAO PAULO62070503***6304E7DB",
    "antifraud": [
        {
            "analyse_status": "NO_ANALYSED",
            "_id": "68cd583ac28afa3e818e48eb",
            "session": null
        }
    ],
    "created_at": "2025-09-19T13:18:50.095Z",
    "info_additional": []
}

Casos de testes

CondiçãoRetorno
"amount": 105, Final com número igual 5 (cinco)Transação do tipo PIX Aprovada.
"amount": 108, Final com número diferente 5 (cinco)Transação do tipo PIX Pendente.
⚠️

Formato de data e hora

As Datas e horas geradas nos response, estão no formato ISO 8601, um padrão internacional para representação de datas e horas. Para utilizar o formato Brasileiro é necessário converter. Para converter a hora do UTC para o Horário de Brasília, basta subtrair 3 horas.

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 4 months ago

Did this page help you?