Referência da API

Yuupe Pay API v1

Todos os endpoints, campos e respostas, gerados da mesma especificação que valida as chamadas. O que está aqui é o que a API aceita.

URLhttps://yuupe.me/api/v1/pay

Autenticação: Authorization: Bearer yp_test_… (sandbox) ou yp_live_… (produção). Veja Autenticação.
Valores em centavos; datas em ISO 8601; corpo e respostas em JSON.
Erros sempre no mesmo formato, com erro.codigo estável. Veja Erros e mensagens.
Especificação OpenAPI 3.1 para importar no Postman/Insomnia: openapi.json.

Pedidos

Criar e cobrar um pedido

POST/pedidos

Cria o pedido e cobra. Cartão passa sempre pelo 3DS 2.0: envie comprador.documento, comprador.endereco, o dispositivo do pay.js e o IP do comprador no cabeçalho X-Yuupe-IP-Comprador. O cartão responde sempre aguardando_autenticacao com autenticacao, que o navegador passa para YuupePay.autenticar(): o pay.js coleta os dados do dispositivo, o banco aprova direto ou pede confirmação, e só então a cobrança é feita. O resultado final chega pelo webhook e pelo GET /pedidos/{id}. Pix (com comprador.documento e comprador.endereco) responde aguardando_pagamento com o QR. Repetir o mesmo numero_pedido devolve o pedido existente (200) sem nova cobrança.

Cabeçalhos

Campo	Descrição
`X-Yuupe-IP-Comprador` string	IP (IPv4) do navegador do comprador. Obrigatório no cartão.

Corpo (NovoPedido)

Campo	Descrição
`numero_pedido`obrigatório string	Seu número do pedido. Único por loja e ambiente: repetir devolve o mesmo pedido, sem cobrar de novo. mín. 1 · máx. 60 · padrão ^[A-Za-z0-9._\-:/#]+$
`metodo`obrigatório enum	`cartaopix`
`parcelas` integer	Só cartão. Respeita o máximo e a parcela mínima definidos pela loja. ≥ 1 · ≤ 12
`token_cartao` string	Gerado no navegador pelo pay.js (YuupePay.tokenizarCartao). Obrigatório no cartão. Vale 5 minutos. mín. 8 · máx. 200
`dispositivo` Dispositivo	Devolvido por `YuupePay.tokenizarCartao` no navegador. Repasse como veio. Obrigatório no cartão (3DS).
`user_agent`obrigatório string	mín. 1 · máx. 1000
`idioma` string	máx. 20
`tela_largura` integer
`tela_altura` integer
`profundidade_cor` integer
`fuso_horas` number
`java` boolean
`comprador`obrigatório Comprador
`nome`obrigatório string	mín. 2 · máx. 120
`email`obrigatório string (email)	máx. 160
`documento` string	CPF ou CNPJ, com ou sem pontuação. Obrigatório no cartão e no Pix (exigência da operadora). máx. 20
`telefone` string	Recomendado no cartão: o banco usa na autenticação 3DS. máx. 20
`endereco` Endereco	Endereço de cobrança. Obrigatório no cartão e no Pix (exigência da operadora).
`logradouro`obrigatório string	mín. 1 · máx. 120
`numero`obrigatório string	mín. 1 · máx. 20
`complemento` string	máx. 60
`bairro`obrigatório string	mín. 1 · máx. 80
`cidade`obrigatório string	mín. 1 · máx. 80
`uf`obrigatório string	mín. 2 · máx. 2
`cep`obrigatório string	mín. 8 · máx. 9
`itens`obrigatório lista de Item
`descricao`obrigatório string	mín. 1 · máx. 200
`quantidade`obrigatório integer	≥ 1 · ≤ 10000
`valor_unitario_centavos`obrigatório integer	≥ 1
`sku` string	máx. 60
`metadados` object	Até 20 pares chave/valor devolvidos no pedido e no webhook.
`idioma` enum	Idioma do comprador para `motivo.mensagem_comprador`. Padrão: pt-BR. `pt-BRpt-PTenes`

Respostas

200	Pedido já existia (idempotência) · Pedido
201	Pedido criado · Pedido
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
422	A operadora recusou os dados · Erro
429	Limite de requisições · Erro
503	Loja sem configuração para cobrar (ex.: 3DS indisponível) · Erro

Requisição

curl -X POST "https://yuupe.me/api/v1/pay/pedidos" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "X-Yuupe-IP-Comprador: 203.0.113.10" \
  -d '{
  "numero_pedido": "NIC-2026-000123",
  "metodo": "pix",
  "comprador": {
    "nome": "Maria Souza",
    "email": "maria@exemplo.com",
    "documento": "529.982.247-25",
    "telefone": "+5561999990000",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "complemento": "Apto 45",
      "bairro": "Asa Sul",
      "cidade": "Brasília",
      "uf": "DF",
      "cep": "70000-000"
    }
  },
  "itens": [
    {
      "descricao": "Combo Família",
      "quantidade": 1,
      "valor_unitario_centavos": 15118,
      "sku": "COMBO-FAM"
    }
  ],
  "metadados": {},
  "idioma": "pt-BR"
}'

Resposta 200

{
  "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "numero_pedido": "texto",
  "ambiente": "sandbox",
  "status": "criado",
  "metodo": "cartao",
  "parcelas": 1,
  "valor_centavos": 1,
  "valor_estornado_centavos": 1,
  "comprador": {
    "nome": "Maria Souza",
    "email": "maria@exemplo.com",
    "documento": "529.982.247-25",
    "telefone": "+5561999990000",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "complemento": "Apto 45",
      "bairro": "Asa Sul",
      "cidade": "Brasília",
      "uf": "DF",
      "cep": "70000-000"
    }
  },
  "itens": [
    {
      "descricao": "Combo Família",
      "quantidade": 1,
      "valor_unitario_centavos": 15118,
      "sku": "COMBO-FAM"
    }
  ],
  "metadados": {},
  "cartao": {
    "bandeira": "texto",
    "ultimos4": "texto"
  },
  "pix": {
    "qr_code": "texto",
    "qr_code_imagem": "texto",
    "expira_em": "texto"
  },
  "autenticacao": {
    "pedido_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "etapa": "coleta",
    "url": "texto",
    "token": "texto",
    "continuar_url": "texto",
    "expira_em": "texto"
  },
  "verificacao_3ds": {
    "resultado": "texto",
    "responsabilidade_do_emissor": true
  },
  "motivo_recusa": "texto",
  "motivo": {
    "codigo": "cartao_sem_limite",
    "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
    "tentar_novamente": "sim",
    "detalhe_operadora": {
      "codigo": "texto",
      "mensagem": "texto"
    }
  },
  "criado_em": "texto",
  "pago_em": "texto"
}

Pix e cartão

No Pix, comprador.documento e comprador.endereco são obrigatórios. No cartão, também token_cartao, dispositivo e o cabeçalho X-Yuupe-IP-Comprador.

Pedidos

Listar pedidos

GET/pedidos

Parâmetros da URL

Campo	Descrição
`status` enum
`desde` string	ISO 8601
`ate` string
`limite` integer
`antes_de` string	Cursor: `criado_em` do último item da página anterior.

Respostas

200	Página de pedidos, mais novos primeiro · JSON
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
429	Limite de requisições · Erro

Requisição

curl -X GET "https://yuupe.me/api/v1/pay/pedidos?status=aprovado&desde=2026-10-01T00%3A00%3A00-03%3A00&limite=20" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE"

Resposta 200

{
  "pedidos": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
      "numero_pedido": "texto",
      "ambiente": "sandbox",
      "status": "criado",
      "metodo": "cartao",
      "parcelas": 1,
      "valor_centavos": 1,
      "valor_estornado_centavos": 1,
      "comprador": {
        "nome": "Maria Souza",
        "email": "maria@exemplo.com",
        "documento": "529.982.247-25",
        "telefone": "+5561999990000",
        "endereco": {
          "logradouro": "Rua das Flores",
          "numero": "123",
          "complemento": "Apto 45",
          "bairro": "Asa Sul",
          "cidade": "Brasília",
          "uf": "DF",
          "cep": "70000-000"
        }
      },
      "itens": [
        {
          "descricao": "Combo Família",
          "quantidade": 1,
          "valor_unitario_centavos": 15118,
          "sku": "COMBO-FAM"
        }
      ],
      "metadados": {},
      "cartao": {
        "bandeira": "texto",
        "ultimos4": "texto"
      },
      "pix": {
        "qr_code": "texto",
        "qr_code_imagem": "texto",
        "expira_em": "texto"
      },
      "autenticacao": {
        "pedido_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
        "etapa": "coleta",
        "url": "texto",
        "token": "texto",
        "continuar_url": "texto",
        "expira_em": "texto"
      },
      "verificacao_3ds": {
        "resultado": "texto",
        "responsabilidade_do_emissor": true
      },
      "motivo_recusa": "texto",
      "motivo": {
        "codigo": "cartao_sem_limite",
        "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
        "tentar_novamente": "sim",
        "detalhe_operadora": {
          "codigo": "texto",
          "mensagem": "texto"
        }
      },
      "criado_em": "texto",
      "pago_em": "texto"
    }
  ],
  "proximo": "texto"
}

Pedidos

Consultar um pedido

GET/pedidos/{id}

Se o pedido estiver aguardando, a Yuupe confere o estado na operadora antes de responder. Use numero_pedido no lugar do id com GET /pedidos/por-numero/{numero_pedido}.

Parâmetros do caminho

Campo	Descrição
`id`obrigatório string (uuid)	id do pedido na Yuupe Pay

Respostas

200	Pedido · Pedido
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
404	Não encontrado · Erro
429	Limite de requisições · Erro

Requisição

curl -X GET "https://yuupe.me/api/v1/pay/pedidos/3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE"

Resposta 200

{
  "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "numero_pedido": "texto",
  "ambiente": "sandbox",
  "status": "criado",
  "metodo": "cartao",
  "parcelas": 1,
  "valor_centavos": 1,
  "valor_estornado_centavos": 1,
  "comprador": {
    "nome": "Maria Souza",
    "email": "maria@exemplo.com",
    "documento": "529.982.247-25",
    "telefone": "+5561999990000",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "complemento": "Apto 45",
      "bairro": "Asa Sul",
      "cidade": "Brasília",
      "uf": "DF",
      "cep": "70000-000"
    }
  },
  "itens": [
    {
      "descricao": "Combo Família",
      "quantidade": 1,
      "valor_unitario_centavos": 15118,
      "sku": "COMBO-FAM"
    }
  ],
  "metadados": {},
  "cartao": {
    "bandeira": "texto",
    "ultimos4": "texto"
  },
  "pix": {
    "qr_code": "texto",
    "qr_code_imagem": "texto",
    "expira_em": "texto"
  },
  "autenticacao": {
    "pedido_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "etapa": "coleta",
    "url": "texto",
    "token": "texto",
    "continuar_url": "texto",
    "expira_em": "texto"
  },
  "verificacao_3ds": {
    "resultado": "texto",
    "responsabilidade_do_emissor": true
  },
  "motivo_recusa": "texto",
  "motivo": {
    "codigo": "cartao_sem_limite",
    "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
    "tentar_novamente": "sim",
    "detalhe_operadora": {
      "codigo": "texto",
      "mensagem": "texto"
    }
  },
  "criado_em": "texto",
  "pago_em": "texto"
}

Pedidos

Consultar pelo seu número do pedido

GET/pedidos/por-numero/{numero_pedido}

Parâmetros do caminho

Campo	Descrição
`numero_pedido`obrigatório string

Respostas

200	Pedido · Pedido
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
404	Não encontrado · Erro
429	Limite de requisições · Erro

Requisição

curl -X GET "https://yuupe.me/api/v1/pay/pedidos/por-numero/NIC-2026-000123" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE"

Resposta 200

{
  "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "numero_pedido": "texto",
  "ambiente": "sandbox",
  "status": "criado",
  "metodo": "cartao",
  "parcelas": 1,
  "valor_centavos": 1,
  "valor_estornado_centavos": 1,
  "comprador": {
    "nome": "Maria Souza",
    "email": "maria@exemplo.com",
    "documento": "529.982.247-25",
    "telefone": "+5561999990000",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "123",
      "complemento": "Apto 45",
      "bairro": "Asa Sul",
      "cidade": "Brasília",
      "uf": "DF",
      "cep": "70000-000"
    }
  },
  "itens": [
    {
      "descricao": "Combo Família",
      "quantidade": 1,
      "valor_unitario_centavos": 15118,
      "sku": "COMBO-FAM"
    }
  ],
  "metadados": {},
  "cartao": {
    "bandeira": "texto",
    "ultimos4": "texto"
  },
  "pix": {
    "qr_code": "texto",
    "qr_code_imagem": "texto",
    "expira_em": "texto"
  },
  "autenticacao": {
    "pedido_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "etapa": "coleta",
    "url": "texto",
    "token": "texto",
    "continuar_url": "texto",
    "expira_em": "texto"
  },
  "verificacao_3ds": {
    "resultado": "texto",
    "responsabilidade_do_emissor": true
  },
  "motivo_recusa": "texto",
  "motivo": {
    "codigo": "cartao_sem_limite",
    "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
    "tentar_novamente": "sim",
    "detalhe_operadora": {
      "codigo": "texto",
      "mensagem": "texto"
    }
  },
  "criado_em": "texto",
  "pago_em": "texto"
}

Checkout

Configuração do checkout para um valor

GET/checkout-config

Devolve a chave pública para o pay.js e as opções de parcelamento que a loja aceita para o valor do carrinho.

Parâmetros da URL

Campo	Descrição
`valor_centavos`obrigatório integer

Respostas

200	Configuração · CheckoutConfig
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
429	Limite de requisições · Erro

Requisição

curl -X GET "https://yuupe.me/api/v1/pay/checkout-config?valor_centavos=15980" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE"

Resposta 200

{
  "ambiente": "sandbox",
  "chave_publica": "texto",
  "pix_ativo": true,
  "pix_validade_min": 1,
  "opcoes_parcelamento": [
    {
      "parcelas": 1,
      "valor_parcela_centavos": 15118
    },
    {
      "parcelas": 3,
      "valor_parcela_centavos": 5040
    }
  ]
}

Estornos

Estornar (total ou parcial)

POST/pedidos/{id}/estornos

Cartão: total ou parcial, vários parciais até o valor pago. Pix: cancela antes da liquidação; depois, até 5 dias (estorno_em_processamento). O cabeçalho Idempotency-Key é obrigatório: repetir a chave devolve o mesmo estorno.

Parâmetros do caminho

Campo	Descrição
`id`obrigatório string (uuid)	id do pedido na Yuupe Pay

Cabeçalhos

Campo	Descrição
`Idempotency-Key`obrigatório string

Corpo (NovoEstorno)

Campo	Descrição
`valor_centavos` integer	Sem valor = estorno total do saldo estornável. ≥ 1
`motivo` string	máx. 250

Respostas

201	Estorno registrado · JSON
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
409	Estorno não permitido · Erro
429	Limite de requisições · Erro

Requisição

curl -X POST "https://yuupe.me/api/v1/pay/pedidos/3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90/estornos" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: estorno-NIC-2026-000123-1" \
  -d '{
  "valor_centavos": 5039,
  "motivo": "Cliente desistiu da visita"
}'

Resposta 201

{
  "estorno": {
    "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "valor_centavos": 1,
    "motivo": "texto",
    "status": "solicitado",
    "criado_em": "texto",
    "concluido_em": "texto"
  },
  "pedido": {
    "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "numero_pedido": "texto",
    "ambiente": "sandbox",
    "status": "criado",
    "metodo": "cartao",
    "parcelas": 1,
    "valor_centavos": 1,
    "valor_estornado_centavos": 1,
    "comprador": {
      "nome": "Maria Souza",
      "email": "maria@exemplo.com",
      "documento": "529.982.247-25",
      "telefone": "+5561999990000",
      "endereco": {
        "logradouro": "Rua das Flores",
        "numero": "123",
        "complemento": "Apto 45",
        "bairro": "Asa Sul",
        "cidade": "Brasília",
        "uf": "DF",
        "cep": "70000-000"
      }
    },
    "itens": [
      {
        "descricao": "Combo Família",
        "quantidade": 1,
        "valor_unitario_centavos": 15118,
        "sku": "COMBO-FAM"
      }
    ],
    "metadados": {},
    "cartao": {
      "bandeira": "texto",
      "ultimos4": "texto"
    },
    "pix": {
      "qr_code": "texto",
      "qr_code_imagem": "texto",
      "expira_em": "texto"
    },
    "autenticacao": {
      "pedido_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
      "etapa": "coleta",
      "url": "texto",
      "token": "texto",
      "continuar_url": "texto",
      "expira_em": "texto"
    },
    "verificacao_3ds": {
      "resultado": "texto",
      "responsabilidade_do_emissor": true
    },
    "motivo_recusa": "texto",
    "motivo": {
      "codigo": "cartao_sem_limite",
      "mensagem_comprador": "Seu cartão não tem limite disponível para esta compra. Tente outro cartão ou pague com Pix.",
      "tentar_novamente": "sim",
      "detalhe_operadora": {
        "codigo": "texto",
        "mensagem": "texto"
      }
    },
    "criado_em": "texto",
    "pago_em": "texto"
  }
}

Estornos

Estornos de um pedido

GET/pedidos/{id}/estornos

Parâmetros do caminho

Campo	Descrição
`id`obrigatório string (uuid)	id do pedido na Yuupe Pay

Respostas

200	Lista · JSON
400	Requisição inválida · Erro
401	Chave ausente, inválida ou revogada · Erro
429	Limite de requisições · Erro

Requisição

curl -X GET "https://yuupe.me/api/v1/pay/pedidos/3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90/estornos" \
  -H "Authorization: Bearer yp_test_SUA_CHAVE"

Resposta 200

{
  "estornos": [
    {
      "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
      "valor_centavos": 1,
      "motivo": "texto",
      "status": "solicitado",
      "criado_em": "texto",
      "concluido_em": "texto"
    }
  ]
}

POSTEvento de pedido (webhook)

Enviado quando o status do pedido muda. Assinado: X-Yuupe-Signature: t=<unix>,v1=<hex> = HMAC-SHA256 de <t>.<corpo> com o segredo do webhook. Reenvio por até 24 h até receber 2xx.

Eventos: pedido.aprovado, pedido.recusado, pedido.expirado, pedido.estornado, pedido.estorno_parcial, pedido.contestado. Veja Webhooks.

Corpo enviado à sua URL

null

Objetos

Os objetos que a API recebe e devolve. Campos marcados como obrigatórios precisam vir no corpo da chamada.

Pedido

Campo	Descrição
`id`obrigatório string (uuid)
`numero_pedido`obrigatório string
`ambiente`obrigatório enum	`sandboxproducao`
`status`obrigatório enum	`criadoaguardando_autenticacaoaguardando_pagamentoem_analiseaprovadorecusadoexpiradoestorno_em_processamentoestorno_parcialestornadocontestadoerro`
`metodo`obrigatório enum	`cartaopix`
`parcelas`obrigatório integer
`valor_centavos`obrigatório integer
`valor_estornado_centavos`obrigatório integer
`comprador`obrigatório Comprador
`nome`obrigatório string	mín. 2 · máx. 120
`email`obrigatório string (email)	máx. 160
`documento` string	CPF ou CNPJ, com ou sem pontuação. Obrigatório no cartão e no Pix (exigência da operadora). máx. 20
`telefone` string	Recomendado no cartão: o banco usa na autenticação 3DS. máx. 20
`endereco` Endereco	Endereço de cobrança. Obrigatório no cartão e no Pix (exigência da operadora).
`logradouro`obrigatório string	mín. 1 · máx. 120
`numero`obrigatório string	mín. 1 · máx. 20
`complemento` string	máx. 60
`bairro`obrigatório string	mín. 1 · máx. 80
`cidade`obrigatório string	mín. 1 · máx. 80
`uf`obrigatório string	mín. 2 · máx. 2
`cep`obrigatório string	mín. 8 · máx. 9
`itens`obrigatório lista de Item
`descricao`obrigatório string	mín. 1 · máx. 200
`quantidade`obrigatório integer	≥ 1 · ≤ 10000
`valor_unitario_centavos`obrigatório integer	≥ 1
`sku` string	máx. 60
`metadados`obrigatório object · pode ser nulo
`cartao`obrigatório object · pode ser nulo
`bandeira`obrigatório string · pode ser nulo
`ultimos4`obrigatório string · pode ser nulo
`pix`obrigatório object · pode ser nulo
`qr_code`obrigatório string · pode ser nulo
`qr_code_imagem`obrigatório string · pode ser nulo
`expira_em`obrigatório string · pode ser nulo
`autenticacao`obrigatório object · pode ser nulo	Só com `status = aguardando_autenticacao` (todo cartão começa assim): passe este objeto, como veio, para `YuupePay.autenticar()` no navegador. O comprador tem 5 minutos.
`pedido_id`obrigatório string (uuid)
`etapa`obrigatório enum	`coleta`: o pay.js coleta os dados do dispositivo e segue sozinho para o desafio, se o banco pedir. `desafio`: já na confirmação do banco. `coletadesafio`
`url`obrigatório string
`token`obrigatório string · pode ser nulo
`continuar_url`obrigatório string · pode ser nulo
`expira_em`obrigatório string
`verificacao_3ds`obrigatório object · pode ser nulo
`resultado`obrigatório string · pode ser nulo	Como a Vindi devolve: authenticated_with_challenge, authenticated_frictionless, not_verified_unsupported, not_verified_auth_failed…
`responsabilidade_do_emissor`obrigatório boolean · pode ser nulo	true = em caso de contestação por fraude, a responsabilidade é do banco emissor (liability shift).
`motivo_recusa`obrigatório string · pode ser nulo	Texto técnico da recusa, para log. Para o comprador, use `motivo.mensagem_comprador`.
`motivo`obrigatório Motivo · pode ser nulo	Com `recusado`, `expirado` ou `erro`: o que mostrar ao comprador e se vale tentar de novo.
`codigo`obrigatório string	Código estável do motivo (ex.: cartao_sem_limite, cartao_dados_invalidos, autenticacao_falhou, pix_expirado, pagamento_indisponivel).
`mensagem_comprador`obrigatório string	Mostre esta frase ao comprador, como está. Vem no `idioma` do pedido.
`tentar_novamente`obrigatório enum	`sim`: pode tentar de novo com o mesmo meio. `outro_meio`: ofereça outro cartão ou Pix. `nao`: não adianta tentar de novo. `simoutro_meionao`
`detalhe_operadora`obrigatório object · pode ser nulo	O que a operadora respondeu, para o seu log e o suporte. Não mostre ao comprador.
`codigo`obrigatório string · pode ser nulo
`mensagem`obrigatório string · pode ser nulo
`criado_em`obrigatório string
`pago_em`obrigatório string · pode ser nulo

NovoPedido

Campo	Descrição
`numero_pedido`obrigatório string	Seu número do pedido. Único por loja e ambiente: repetir devolve o mesmo pedido, sem cobrar de novo. mín. 1 · máx. 60 · padrão ^[A-Za-z0-9._\-:/#]+$
`metodo`obrigatório enum	`cartaopix`
`parcelas` integer	Só cartão. Respeita o máximo e a parcela mínima definidos pela loja. ≥ 1 · ≤ 12
`token_cartao` string	Gerado no navegador pelo pay.js (YuupePay.tokenizarCartao). Obrigatório no cartão. Vale 5 minutos. mín. 8 · máx. 200
`dispositivo` Dispositivo	Devolvido por `YuupePay.tokenizarCartao` no navegador. Repasse como veio. Obrigatório no cartão (3DS).
`user_agent`obrigatório string	mín. 1 · máx. 1000
`idioma` string	máx. 20
`tela_largura` integer
`tela_altura` integer
`profundidade_cor` integer
`fuso_horas` number
`java` boolean
`comprador`obrigatório Comprador
`nome`obrigatório string	mín. 2 · máx. 120
`email`obrigatório string (email)	máx. 160
`documento` string	CPF ou CNPJ, com ou sem pontuação. Obrigatório no cartão e no Pix (exigência da operadora). máx. 20
`telefone` string	Recomendado no cartão: o banco usa na autenticação 3DS. máx. 20
`endereco` Endereco	Endereço de cobrança. Obrigatório no cartão e no Pix (exigência da operadora).
`logradouro`obrigatório string	mín. 1 · máx. 120
`numero`obrigatório string	mín. 1 · máx. 20
`complemento` string	máx. 60
`bairro`obrigatório string	mín. 1 · máx. 80
`cidade`obrigatório string	mín. 1 · máx. 80
`uf`obrigatório string	mín. 2 · máx. 2
`cep`obrigatório string	mín. 8 · máx. 9
`itens`obrigatório lista de Item
`descricao`obrigatório string	mín. 1 · máx. 200
`quantidade`obrigatório integer	≥ 1 · ≤ 10000
`valor_unitario_centavos`obrigatório integer	≥ 1
`sku` string	máx. 60
`metadados` object	Até 20 pares chave/valor devolvidos no pedido e no webhook.
`idioma` enum	Idioma do comprador para `motivo.mensagem_comprador`. Padrão: pt-BR. `pt-BRpt-PTenes`

Comprador

Campo	Descrição
`nome`obrigatório string	mín. 2 · máx. 120
`email`obrigatório string (email)	máx. 160
`documento` string	CPF ou CNPJ, com ou sem pontuação. Obrigatório no cartão e no Pix (exigência da operadora). máx. 20
`telefone` string	Recomendado no cartão: o banco usa na autenticação 3DS. máx. 20
`endereco` Endereco	Endereço de cobrança. Obrigatório no cartão e no Pix (exigência da operadora).
`logradouro`obrigatório string	mín. 1 · máx. 120
`numero`obrigatório string	mín. 1 · máx. 20
`complemento` string	máx. 60
`bairro`obrigatório string	mín. 1 · máx. 80
`cidade`obrigatório string	mín. 1 · máx. 80
`uf`obrigatório string	mín. 2 · máx. 2
`cep`obrigatório string	mín. 8 · máx. 9

Endereco

Endereço de cobrança. Obrigatório no cartão e no Pix (exigência da operadora).

Campo	Descrição
`logradouro`obrigatório string	mín. 1 · máx. 120
`numero`obrigatório string	mín. 1 · máx. 20
`complemento` string	máx. 60
`bairro`obrigatório string	mín. 1 · máx. 80
`cidade`obrigatório string	mín. 1 · máx. 80
`uf`obrigatório string	mín. 2 · máx. 2
`cep`obrigatório string	mín. 8 · máx. 9

Item

Campo	Descrição
`descricao`obrigatório string	mín. 1 · máx. 200
`quantidade`obrigatório integer	≥ 1 · ≤ 10000
`valor_unitario_centavos`obrigatório integer	≥ 1
`sku` string	máx. 60

Motivo

Com recusado, expirado ou erro: o que mostrar ao comprador e se vale tentar de novo.

Campo	Descrição
`codigo`obrigatório string	Código estável do motivo (ex.: cartao_sem_limite, cartao_dados_invalidos, autenticacao_falhou, pix_expirado, pagamento_indisponivel).
`mensagem_comprador`obrigatório string	Mostre esta frase ao comprador, como está. Vem no `idioma` do pedido.
`tentar_novamente`obrigatório enum	`sim`: pode tentar de novo com o mesmo meio. `outro_meio`: ofereça outro cartão ou Pix. `nao`: não adianta tentar de novo. `simoutro_meionao`
`detalhe_operadora`obrigatório object · pode ser nulo	O que a operadora respondeu, para o seu log e o suporte. Não mostre ao comprador.
`codigo`obrigatório string · pode ser nulo
`mensagem`obrigatório string · pode ser nulo

Erro

Campo	Descrição
`erro`obrigatório object
`codigo`obrigatório enum	`nao_autenticadochave_revogadaconta_inativaconta_nao_configuradarequisicao_invalidavalor_invalidoparcelas_nao_permitidasmetodo_indisponiveltoken_cartao_obrigatoriopedido_nao_encontradoidempotency_key_obrigatoriavalor_acima_do_estornavelestorno_nao_permitidodados_recusadosautenticacao_indisponivelvalor_abaixo_minimo_3dserro_gatewaylimite_de_requisicoeserro_interno`
`mensagem`obrigatório string
`campo` string
`motivo` any

Estorno

Campo	Descrição
`id`obrigatório string (uuid)
`valor_centavos`obrigatório integer
`motivo`obrigatório string · pode ser nulo
`status`obrigatório enum	`solicitadoem_processamentoconcluidofalhou`
`criado_em`obrigatório string
`concluido_em`obrigatório string · pode ser nulo

NovoEstorno

Campo	Descrição
`valor_centavos` integer	Sem valor = estorno total do saldo estornável. ≥ 1
`motivo` string	máx. 250

CheckoutConfig

Campo	Descrição
`ambiente`obrigatório enum	`sandboxproducao`
`chave_publica`obrigatório string · pode ser nulo	Passe para o pay.js no navegador (YuupePay.tokenizarCartao). Não é segredo.
`pix_ativo`obrigatório boolean
`pix_validade_min`obrigatório integer
`opcoes_parcelamento`obrigatório lista de object
`parcelas`obrigatório integer
`valor_parcela_centavos`obrigatório integer

Dispositivo

Devolvido por YuupePay.tokenizarCartao no navegador. Repasse como veio. Obrigatório no cartão (3DS).

Campo	Descrição
`user_agent`obrigatório string	mín. 1 · máx. 1000
`idioma` string	máx. 20
`tela_largura` integer
`tela_altura` integer
`profundidade_cor` integer
`fuso_horas` number
`java` boolean