Criar Pagamento

Criar pagamento

POST /api/v1/payments

Autoriza uma transação com cartão. Envie o numeroCartao OU um token de cartão previamente tokenizado (ver Tokenizar cartão).

Requer autenticação mTLS. Veja Autenticação.

Fluxo com token

Tokenizando o cartão antes, o número real trafega uma única vez. As cobranças seguintes usam apenas o token.

Request

Body

{
  "identificacaoPagamento": "PAG-20250723-0001",
  "numeroParcelas": 3,
  "tipoParcelamento": "4",
  "bandeiraCartao": "1",
  "valor": 150.00,
  "dataExpiracao": "12/28",
  "codigoSeguranca": "123",
  "numeroCartao": "4111111111111111"
}

Campos

Campo	Tipo	Obrigatório	Descrição
`identificacaoPagamento`	string	sim	Identificação única do pagamento, gerada pelo sistema de origem
`numeroParcelas`	integer	sim	Número de parcelas (mínimo `1`)
`tipoParcelamento`	enum	sim	Tipo de parcelamento. Valores: `3`, `4`, `6`, `7`
`bandeiraCartao`	string	sim	Código numérico da bandeira do cartão (ex.: `1`)
`valor`	number	sim	Valor total da transação
`dataExpiracao`	string	não	Validade do cartão no formato `MM/AA` (ex.: `12/28`)
`codigoSeguranca`	string	não	CVV/CVC do cartão
`numeroCartao`	string	condicional	Número do cartão. Obrigatório quando não for pagamento via token
`token`	string	condicional	Token do cartão tokenizado. Obrigatório quando for pagamento via token (dispensa `numeroCartao`)

A lista completa de códigos de bandeiraCartao é extensa e é fornecida pelo time de Crédito. Utilize o código correspondente à bandeira do cartão usado na transação.

Response

`201 Created`

{
  "id": "8f14e45f-ceea-467e-9a9f-1d1a3c1e5b3a",
  "codigo": "0",
  "mensagem": "Transacao autorizada",
  "codigoAutorizacao": "00",
  "mensagemAutorizador": "Transacao aprovada",
  "status": "CON",
  "identicadorPagamentoAdquirente": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "identificadorPagamento": "PAG-20250723-0001",
  "bandeiraCartao": "1",
  "codigoAdquirente": "1",
  "nomeAdquirente": "Rede",
  "dataAutorizacao": "23/07/2026T14:35",
  "numeroAutorizacao": "123456",
  "merchantUsn": "123456789012",
  "esitefUsn": "123456789012345",
  "sitefUsn": "123456",
  "hostUsn": "123456789012345",
  "valor": 150.00,
  "tipoPagamento": "C",
  "emissor": "VISA",
  "authorizerMerchantId": "0001234567",
  "terminalId": "12345678",
  "dataPagamento": "23/07/2026T14:35",
  "parcelas": [
    {
      "id": "3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607",
      "transacaoCartaoId": "8f14e45f-ceea-467e-9a9f-1d1a3c1e5b3a",
      "numeroParcela": 1,
      "valorParcela": 50.00,
      "dataVencimento": "2026-08-23"
    }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
`id`	string (uuid)	Identificador da transação. Use em Consultar pagamento
`codigo`	string	Código de resposta. Diferente de `0` significa falha
`mensagem`	string	Mensagem de resposta. Diferente de `Transacao autorizada` significa falha
`codigoAutorizacao`	string	Código de resposta do autorizador
`mensagemAutorizador`	string	Mensagem de resposta do autorizador
`status`	enum	Status da transação — ver Status de transação
`identicadorPagamentoAdquirente`	string	Identificador da transação na adquirente (nit)
`identificadorPagamento`	string	Código de pedido enviado na criação (order_id)
`cupomCliente`	string	Cupom fiscal via cliente (customer_receipt)
`cupomEstabelecimento`	string	Cupom fiscal via estabelecimento (merchant_receipt)
`merchantAdviceCode`	string	Advice code retornado em caso de recusa — ver abaixo
`bandeiraCartao`	string	Código da bandeira utilizada na transação
`codigoAdquirente`	string	Código da adquirente (acquirer_id)
`nomeAdquirente`	string	Nome da adquirente (acquirer_name)
`dataAutorizacao`	string	Data retornada pelo autorizador, `DD/MM/AAAA'T'HH:mm`
`numeroAutorizacao`	string	Número de autorização da transação
`merchantUsn`	string	Número sequencial único enviado pela loja
`esitefUsn`	string	Número sequencial único da transação no e-SiTef
`sitefUsn`	string	Número sequencial único da transação no SiTef
`hostUsn`	string	NSU da autorizadora (host_usn)
`valor`	number	Valor da transação
`tipoPagamento`	enum	`B` boleto, `C` crédito, `D` débito, `P` private label, `T` transferência, `G` gift, `O` outros, `W` boleto NR
`emissor`	string	Código da bandeira retornado pelo autorizador (issuer)
`authorizerMerchantId`	string	Código de afiliação do lojista na autorizadora
`terminalId`	string	Código do terminal utilizado na transação
`dataPagamento`	string	Data de efetivação no formato `DD/MM/AAAA'T'HH:mm`
`recorrenciaId`	string	TID da bandeira da primeira transação da recorrência. Só retornado em recorrências
`parcelas`	array	Parcelas geradas para a transação

Campos de `parcelas[]`

Campo	Tipo	Descrição
`id`	string (uuid)	Identificador da parcela
`transacaoCartaoId`	string (uuid)	Identificador da transação a que a parcela pertence
`numeroParcela`	integer	Número da parcela na sequência
`valorParcela`	number	Valor da parcela
`dataVencimento`	string (date)	Data de vencimento da parcela

Advice code em recusas

Quando a transação é recusada, merchantAdviceCode traz a ação recomendada pelo autorizador/bandeira — por exemplo, não repetir a tentativa ou solicitar dados atualizados do cartão.

Respeite o advice code antes de retentar uma cobrança recusada. Retentativas contrariando a orientação da bandeira podem gerar penalidades ao lojista. Os códigos e suas ações são fornecidos pelo time de Crédito.

Erros

Status	Significado
`400`	Requisição inválida (campos obrigatórios ausentes ou mal formatados)
`401`	Não autorizado
`500`	Erro interno ao processar o pagamento

Corpo de erro (ErrorResponse):

{
  "code": "VALIDATION_ERROR",
  "message": "Campos obrigatorios ausentes",
  "details": [{ "campo": "valor", "erro": "obrigatorio" }],
  "traceId": "a1b2c3d4",
  "timestamp": "2026-08-06T14:30:00Z"
}

Criar Pagamento

On this page