Criar venda avulsa

Utilize este endpoint para criar um pedido e processá-lo no mesmo request (pagamento direto / checkout transparente síncrono), enviando os itens e os dados de pagamento — cartão ou Pix — diretamente, sem necessidade de cadastrar produtos no painel.

Os itens são avulsos (sku, title, unit_price, quantity) e existem apenas naquele pedido.

Endpoint

POST /api/v1/order/single

Diferença para o POST /api/v1/order

O endpoint Criar venda (/api/v1/order) exige produtos e checkouts previamente cadastrados no painel. Já o order/single cria e processa o pagamento em um único request, com itens avulsos. O processamento é síncrono: a resposta já indica se o pagamento foi aprovado.

Abaixo, você pode ver exemplos de requisições para os métodos de pagamento: Cartão de crédito, Pix e Boleto.

Exemplo para cartão de crédito

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/order/single \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "customer": {
            "email": "cliente@exemplo.com",
            "fullname": "Maria Souza",
            "taxvat": "12345678909",
            "telephone": "11999998888"
        },
        "address": {
            "postcode": "01310-100",
            "street": "Av. Paulista",
            "number": 1000,
            "complement": "Sala 1",
            "city": "São Paulo",
            "region": "SP",
            "district": "Bela Vista"
        },
        "items": [
            {
                "sku": "ABC-123",
                "title": "Consultoria",
                "unit_price": 150.00,
                "quantity": 1
            }
        ],
        "payment": {
            "method": "credit",
            "installments": 1,
            "card": {
                "holder": "MARIA SOUZA",
                "number": "4111111111111111",
                "expiration": "12/2027",
                "security": "123"
            }
        }
    }'

Exemplo para Pix

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/order/single \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "customer": {
            "email": "cliente@exemplo.com",
            "fullname": "Maria Souza",
            "taxvat": "12345678909",
            "telephone": "11999998888"
        },
        "address": {
            "postcode": "01310-100",
            "street": "Av. Paulista",
            "number": 1000,
            "city": "São Paulo",
            "region": "SP",
            "district": "Bela Vista"
        },
        "items": [
            {
                "sku": "ABC-123",
                "title": "Consultoria",
                "unit_price": 150.00,
                "quantity": 1
            }
        ],
        "payment": {
            "method": "pix",
            "expiration": 10
        }
    }'

Exemplo para boleto bancário

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/order/single \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "customer": {
            "email": "cliente@exemplo.com",
            "fullname": "Maria Souza",
            "taxvat": "12345678909",
            "telephone": "11999998888"
        },
        "address": {
            "postcode": "01310-100",
            "street": "Av. Paulista",
            "number": 1000,
            "city": "São Paulo",
            "region": "SP",
            "district": "Bela Vista"
        },
        "items": [
            {
                "sku": "ABC-123",
                "title": "Consultoria",
                "unit_price": 150.00,
                "quantity": 1
            }
        ],
        "payment": {
            "method": "bank_slip"
        }
    }'

Pagamento com cartão tokenizado

Quando payment.method = credit, é possível enviar payment.card.token no lugar dos dados brutos do cartão (holder / number / expiration / security). Nesse caso, apenas o token é validado.

Exemplo com cartão tokenizado

curl --request POST \
    --url https://sandbox.azpag.dev/api/v1/order/single \
    --header 'Authorization: Bearer {token}' \
    --header 'Accept: application/json' \
    --header 'Content-type: application/json' \
    --data '{
        "customer": {
            "email": "cliente@exemplo.com",
            "fullname": "Maria Souza",
            "taxvat": "12345678909",
            "telephone": "11999998888"
        },
        "address": {
            "postcode": "01310-100",
            "street": "Av. Paulista",
            "number": 1000,
            "city": "São Paulo",
            "region": "SP",
            "district": "Bela Vista"
        },
        "items": [
            {
                "sku": "ABC-123",
                "title": "Consultoria",
                "unit_price": 150.00,
                "quantity": 1
            }
        ],
        "payment": {
            "method": "credit",
            "installments": 1,
            "card": {
                "token": "card_3e1d9542-09fe-4b8b-9800-38f99f5b2147"
            }
        }
    }'

Desconto

Para aplicar um desconto ao total do pedido, informe o nó discount com o valor em total.

"discount": { "total": 30.00 }

Todos os atributos

Atributo	Tipo	Obrigatório	Descrição	Instruções
customer ⌄	Objeto	Sim
id	Número	Não	ID de um cliente já existente.
fullname	Texto	Sim	Nome do comprador. Ex: Maria Souza	Em caso de empresas, informar a Razão Social.
taxvat	Texto	Sim	Documento do comprador (CPF ou CNPJ). Ex: 12345678909	Apenas números.
email	Texto	Sim	Email do comprador.
telephone	Texto	Sim	Telefone do comprador. Ex: 11999998888
address ⌄	Objeto	Sim
postcode	Texto	Sim	CEP do endereço do comprador. Ex: 01310-100	Formato com hífen (00000-000).
street	Texto	Sim	Logradouro do endereço do comprador. Ex: Av. Paulista
number	Número	Sim	Número do endereço do comprador. Ex: 1000
complement	Texto	Não	Complemento do endereço do comprador. Ex: Sala 1
district	Texto	Sim	Bairro do endereço do comprador. Ex: Bela Vista
city	Texto	Sim	Cidade do endereço do comprador. Ex: São Paulo
region	Texto	Sim	UF do endereço do comprador. Ex: SP
items ⌄	Array	Sim	Lista de itens avulsos do pedido (sem cadastro prévio).
items[].sku	Texto	Sim	Código do item nessa transação. Ex: ABC-123
items[].title	Texto	Sim	Descrição do item nessa transação. Ex: Consultoria
items[].unit_price	Decimal	Sim	Valor unitário do item. Não utilize vírgula para os centavos. Ex: 150.00
items[].quantity	Inteiro	Sim	Quantidade do item nessa transação. Ex: 1
discount ⌄	Objeto	Não	Desconto aplicado ao total do pedido.
discount.total	Decimal	Não	Valor do desconto. Ex: 30.00
payment ⌄	Objeto	Sim
method	Texto	Sim	Qual opção de pagamento será realizada: credit, pix ou bank_slip.
installments	Inteiro	Condicional	Número de parcelas (1 a 12).	Obrigatório quando method for credit.
expiration	Inteiro	Não	Validade do Pix/boleto.
payment.card ⌄	Objeto	Condicional	Obrigatório quando method for credit. Envie os dados do cartão ou um token de cartão salvo.
holder	Texto	Sim	Nome impresso no cartão (máx. 25 caracteres). Ex: MARIA SOUZA
number	Texto	Sim	Número do cartão de crédito do comprador.
expiration	Texto	Sim	Data de expiração no formato MM/YYYY, não vencida. Ex: 12/2027
security	Texto	Sim	Código de segurança do cartão (CVV).
token	Texto	Não	Token de cartão salvo, enviado no lugar dos dados completos do cartão.	Quando informado, apenas o token é validado.

Respostas

Todas as respostas retornam HTTP 200 (exceto empresa em moderação); o resultado real é indicado pelos campos success / hasError no corpo.

Sucesso — pagamento aprovado (HTTP 200)

{
    "success": true,
    "response": "Pedido criado com sucesso",
    "data": {
        "order_number": "1654112455",
        "public_key": "t9rb",
        "status": "paid"
    },
    "payment": {
        "tid": "...",
        "nsu": "...",
        "link_to_pay": "https://sandbox.azpag.dev/...",
        "digitable_number": "...",
        "due_date": "...",
        "card": {
            "token": "card_3e1d9542-09fe-4b8b-9800-38f99f5b2147",
            "brand": "visa",
            "last_digits": "1111"
        }
    }
}

Os campos link_to_pay e digitable_number são retornados para Pix e boleto (rota de pagamento e linha digitável / copia-e-cola). O nó card só é retornado quando há pagamento com cartão.

Falha de pagamento — pedido criado, mas não pago (HTTP 200)

{
    "hasError": true,
    "response": "<motivo da recusa>",
    "data": {
        "order_number": "1654112455",
        "public_key": "t9rb",
        "status": "unpaid"
    }
}

Empresa em moderação (HTTP 403)

{
    "hasError": true,
    "response": "No momento não foi possível processar sua solicitação..."
}

Endereço IP do cliente

O endereço IP de quem está realizando a compra (ip_address) é uma informação importante para a validação e autorização da transação, especialmente quando o método de pagamento é cartão de crédito. Esse dado é utilizado pelas adquirentes em análises antifraude e pode ser decisivo para a aprovação do pagamento.

Por isso, envie sempre o IP real do cliente final na requisição.

Nas transações por cartão de crédito, a resposta inclui o token do cartão. É possível armazenar esse token para realizar novas vendas, informando apenas este campo em payment.card.token no lugar de todos os dados do cartão.