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

Criar transação Boleto

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}}' \

Payload do objeto da transaction

NomeTipoObrigatórioDescrição
payment_typestringSimTipo de transação. BILLET.
amountnumberSimValor da transação em centavos.
intereststringNãoCLIENT: 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.
reference_idstringNãoIdentificador definido pelo cliente, utilizado para controle interno. Limite máximo de 100 caracteres.
clientobjectSimDados do cliente pagador.
splitobjectNãoDados do split.
billetobjectSimDados do boleto.

Payload do objeto client

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 address

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 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

Payload do objeto billet

NomeTipoObrigatórioDescrição
due_datedateSimData de vencimento do boleto, no formato YYYY-MM-DD.
issue_datedateSimData de emissão do boleto, no formato YYYY-MM-DD.
document_kindstringNãoEspécie do documento. (completar)
days_until_expirationnumberNãoQuantidade de dias após o vencimento até que o boleto expire e não possa mais ser pago.
Valores aceitos: de 1 a 99.
iof_percentagestringNãoPercentual de IOF no formato 0.00000 (ex: 0.00820). Aplicado sobre o valor do boleto.
messagesarrayNãoMensagens de instrução exibidas no boleto (máximo de 3 linhas).
discountobjectNãoConfiguração de desconto do boleto.
fineobjectNãoConfiguração de multa por atraso.
interest_percentagestringNãoPercentual de juros ao mês no formato 0.00 (ex: 1.00 representa 1%).

Payload do objeto discount

NomeTipoObrigatórioDescrição
typeenumSimTipo de desconto.
Valores aceitos: VALOR_DATA_FIXA
items[].limit_datedateSimData limite para aplicação do desconto, no formato YYYY-MM-DD.
items[].valuenumberSimValor do desconto em centavos.

Payload do objeto fine

NomeTipoObrigatórioDescrição
percentagestringSimPercentual de multa no formato 0.00 (ex: 2.00 representa 2%).
quantity_daysnumberSimQuantidade de dias de multa.
Valor aceito: de 1 a 99.

Exemplo do Body para criar a transação

{
   "reference_id": "ABCD1223456",
   "payment_type": "BILLET",
   "interest": "STORE",
   "billet": {
      "discount": {
         "type": "VALOR_DATA_FIXA",
         "items": [
            {
               "value": 500,
               "limit_date": "2026-09-01"
            },
            {
               "limit_date": "2026-10-01",
               "value": 200
            }
         ]
      },
      "fine": {
         "percentage": "2.00",
         "quantity_days": 60
      },
      "due_date": "2026-10-10",
      "issue_date": "2026-07-20",
      "document_kind": "DUPLICATA_MERCANTIL",
      "days_until_expiration": 30,
      "messages": [
         "Primeira mensagem",
         "Segunda mensagem"
      ],
      "interest_percentage": "1.00"
   },
   "amount": 10000,
   "client": {
      "first_name": "Fulano de Tal",
      "document": "12345678910",
      "email": "[email protected]",
      "address": {
         "state": "ES",
         "street": "Rua X",
         "number": "123",
         "neighborhood": "Bairro X",
         "city": "Cidade X",
         "zip_code": "29123456"
      }
   }
}

Exemplo de Resposta (200):

{
   "_id": "string",
   "status": "PENDING",
   "amount": 0,
   "original_amount": 0,
   "interest": "STORE",
   "fees": 0,
   "establishment": {
      "first_name": "string",
      "last_name": "string",
      "document": "string",
      "type": "INDIVIDUAL",
      "access_type": "ACQUIRER",
      "id": 0
   },
   "marketplace": {
      "id": 0,
      "type": "WHITELABEL",
      "nickname": "string",
      "active": true,
      "first_name": "string",
      "last_name": "string",
      "document": "string"
   },
   "representative": {
      "id": 0,
      "marketplace_id": 0,
      "active": true,
      "first_name": "string",
      "last_name": "string",
      "document": "string"
   },
   "type": "BILLET",
   "gateway_authorization": "PAYTIME",
   "customer": {
      "first_name": "string",
      "last_name": "string",
      "document": "string",
      "phone": "string",
      "email": "string"
   },
   "expected_on": [
      {
         "installment": 0,
         "date": "2026-07-24T02:42:39.552Z",
         "paid_at": "2026-07-24T02:42:39.552Z",
         "amount": 0,
         "status": "PENDING"
      }
   ],
   "created_at": "2026-07-24T02:42:39.552Z",
   "split": {
      "active": true,
      "is_origin": true,
      "processing": true,
      "initial_amount": 0
   },
   "reference_id": "string",
   "billet": {
      "due_date": "2026-07-18",
      "issue_date": "2026-06-18",
      "entry_date": "2023-09-09",
      "document_kind": "BOLETO_PROPOSTA",
      "iof_percentage": "32.45325",
      "messages": [
         "Mensagem 1",
         "Mensagem 2"
      ],
      "digitable_line": "03399356782060000000201234501011693970000000100",
      "barcode": "03396939700000001009356720600000000123450101",
      "qr_code_pix": "string",
      "qr_code_url": "pix.santander.com.br/qr/v2/cobv/...",
      "pdf_url": "https://storage.example.com/billets/billet.pdf",
      "configured_amount": 44308,
      "configured_original_amount": 45678,
      "discount": {
         "type": "VALOR_DATA_FIXA",
         "items": [
            {
               "value": 55,
               "limit_date": "2026-12-12"
            }
         ]
      },
      "fine": {
         "percentage": "1.20",
         "quantity_days": 5
      },
      "interest_percentage": "1.12",
      "payment": {
         "paid_via": "BARCODE",
         "date": "2025-11-24T13:46:52.015Z",
         "paid_amount": 10000,
         "interest_value": 150,
         "fine": 200,
         "deduction_value": 0,
         "iof_value": 0
      }
   }
}
⚠️

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 about 1 month ago

Did this page help you?