Pagamentos pontuais

Criar Pedido (Order)

Visão Geral

Este endpoint permite criar uma ordem de cobrança (order) associada ao seller autenticado e a um comprador já cadastrado. É indicado para cobranças pontuais via cartão de crédito, com ou sem parcelamento.

Por que usar? • Centraliza o cálculo de valor, parcelas e antecipação • Garante idempotência (evita pedidos duplicados em caso de reenvio) • Retorna em tempo real o resultado da tentativa de pagamento

---

Endpoint

Ambiente	URL base	Caminho
Sandbox	https://sandbox-api.barte.com	/v2/orders
Produção	https://api.barte.com	/v2/orders

Método: POST

---

Autenticação

Todas as requisições exigem o header X-Token-Api com a sua chave de API. Você pode gerar/visualizar esta chave em Configurações → Integração → Chaves API no portal da Barte.

---

Cabeçalhos Requeridos

Header	Tipo	Obrigatório	Descrição
X-Token-Api	string	Sim	Chave da API gerada no painel.
x-idempotency-key	string (UUID v4 recomendado)	Sim	Identificador único para prevenir criação duplicada de ordens. Repita o mesmo valor em attemptReference no corpo.
Content-Type	application/json	Sim	Formato do payload.
Accept	application/json	Não	Formato desejado na resposta (padrão JSON).

---

Corpo da Requisição (JSON)

Campos de primeiro nível

Campo	Tipo	Obrigatório	Descrição
startDate	string (YYYY-MM-DD)	Não	Data em que a ordem deve ser processada. Se ausente, usa a data atual.
value	number	Sim	Valor total da cobrança em centavos ou unidades monetárias (BRL).
installments	integer	Sim	Número de parcelas (mín. 1).
title	string	Não	Identificação amigável da ordem (aparece nos relatórios).
attemptReference	string	Sim	Mesmo valor do header x‑idempotency-key.
description	string	Não	Descrição detalhada da ordem.
payment	object	Sim	Dados de pagamento (ver abaixo).
uuidBuyer	string (UUID)	Sim	Identificador do comprador criado previamente via API /v2/buyers.
threeDSecure	object	Não	Dados para transacionar com 3D Secure 2

Objeto payment

Campo	Tipo	Obrigatório	Descrição
method	string	Sim	Método de pagamento. Ex.: CREDIT_CARD_EARLY_SELLER (captura imediata + antecipação).
brand	string	Sim	Bandeira do cartão (visa, mastercard, etc.).
capture	boolean	Não	true para capturar imediatamente após a autorização (default false).
softDescriptor	string	Não	Texto (máx. 13 caracteres) que aparecerá na fatura do comprador.

---

Objeto payment.card

Há duas maneiras de enviar os dados do cartão:

1. Dados completos (holderName, number, expiration, cvv)

2. Token do cartão (cardToken + cvv)

Campo	Tipo	Obrigatório	Descrição
holderName	string	Cond.¹	Nome impresso no cartão.
number	string	Cond.¹	Número do cartão (PAN).
expiration	string (MM/YYYY)	Cond.¹	Data de expiração do cartão.
cvv	string ou int	Sim	Código de verificação (CCV/CVC).
cardToken	string	Cond.²	Token retornado pelo SDK/tokenizador da Barte. Substitui number e expiration.

¹ Necessários quando não usar cardToken. ² Necessário quando utilizar tokenização. Observação: envie apenas um dos formatos:

---

Objeto threeDSecure

Campo	Tipo	Obrigatório	Descrição
dataOnly	Boolean	Não	Indica se é apenas coleta de dados (sem desafio)
requiresLiabilityShift	Boolean	Não	Indica se é obrigatório a mudança de responsabilidade para prosseguir
setupId	String	Não	ID da sessão de setup 3DS2 gerada
redirectURL	String	Não	URL de redirecionamento após autenticação (usado em desafios)
requestorURL	String	Não	URL do site solicitante do 3DS
billingAddress	object	Não	Endereço de cobrança do portador
shippingAddress	object	Não	Endereço de entrega do portador
browser	object	Não	Informações do navegador do cliente
cardHolder	object	Não	Informações do titular do cartão
mpi	object	Não	Informações sobre autenticação externa MPI

---

Objeto threeDSecure.billingAddress

Campo	Tipo	Obrigatório	Descrição
city	String	Não	Cidade do endereço
country	String	Não	País do endereço
streetNumber	String	Não	Número da residência
zipCode	String	Não	CEP
state	String	Não	Estado (UF)
street	String	Não	Nome da rua

---

Objeto threeDSecure.shippingAddress

Campo	Tipo	Obrigatório	Descrição
city	String	Não	Cidade do endereço
country	String	Não	País do endereço
streetNumber	String	Não	Número da residência
zipCode	String	Não	CEP
state	String	Não	Estado (UF)
street	String	Não	Nome da rua

---

Objeto threeDSecure.browser

Campo	Tipo	Obrigatório	Descrição
ip	String	Não	IP do navegador
userAgent	String	Não	User-Agent do navegador
acceptHeader	String	Não	Accept Header do navegador
language	String	Não	Idioma do navegador
colorDepth	Int	Não	Profundidade de cor da tela
screenHeight	Int	Não	Altura da tela em pixels
screenWidth	Int	Não	Largura da tela em pixels
timeZoneOffset	String	Não	Offset do fuso horário em minutos
javaEnabled	Boolean	Não	Java está habilitado?
javaScriptEnabled	Boolean	Não	JavaScript está habilitado?

---

Objeto threeDSecure.cardHolder

Campo	Tipo	Obrigatório	Descrição
email	String	Não	Email do titular do cartão
mobilePhone	String	Não	Telefone móvel do titular do cartão

---

Objeto threeDSecure.mpi

Campo	Tipo	Obrigatório	Descrição
acsTransactionId	String	Não	Identificador da transação gerado pelo Access Control Server (ACS)
cavv	String	Não	Valor criptográfico de autenticação do portador do cartão (Cardholder Authentication Verification Value)
challenged	Boolean	Não	Indica se o portador foi desafiado (challenge) durante a autenticação 3DS
directoryServerTransactionId	String	Não	Identificador da transação gerado pelo Directory Server da bandeira
eci	String	Não	Electronic Commerce Indicator. Indica o nível de segurança/autenticação da transação
threeDSServerTransactionId	String	Não	Identificador da transação gerado pelo servidor 3DS
transStatus	String	Não	Status do processo de autenticação 3DS
version	String	Não	Versão do protocolo 3-D Secure utilizada na autenticação
xid	String	Não	Identificador da transação gerado pelo sistema de pagamento (Transaction ID do 3DS)