> ## Documentation Index > Fetch the complete documentation index at: https://dev.valorapayments.com.br/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Valora Payments API (Brazil: Pix, card, boleto). Base URL https://api.valorapayments.com.br, Authorization: Bearer sk_vl_... used only on the server. Request amounts are reais as strings ("149.90"); response amounts are integer cents (14990). Use POST /v1/checkouts for card and boleto; POST /v1/payments only creates Pix and should send an Idempotency-Key. Confirm payments only through the payment.succeeded webhook after verifying X-Valora-Signature (hex HMAC-SHA256 of "."), dedupe by event.id and check livemode. Never invent endpoints or fields: check /llms.txt and /openapi.json. # Criar um checkout > Cria uma compra e devolve o `checkout_url`, o link que você manda ao cliente. O cliente escolhe Pix, cartão ou boleto na página da Valora. O preço vem do produto e fica travado na criação. Escopo: `checkouts:write`. ## OpenAPI ````yaml /openapi.json post /v1/checkouts openapi: 3.1.0 info: title: Valora Payments API version: 1.0.0 description: >- API REST da Valora Payments. Valores na entrada em reais (texto, ex.: "149.90"); nas respostas, em centavos inteiros. servers: - url: https://api.valorapayments.com.br description: Teste e produção (o ambiente vem da chave) security: - bearerAuth: [] tags: - name: Pagamentos - name: Checkouts - name: Clientes - name: Produtos - name: Saldo - name: Webhooks paths: /v1/checkouts: post: tags: - Checkouts summary: Criar um checkout description: >- Cria uma compra e devolve o `checkout_url`, o link que você manda ao cliente. O cliente escolhe Pix, cartão ou boleto na página da Valora. O preço vem do produto e fica travado na criação. Escopo: `checkouts:write`. operationId: criarCheckout requestBody: required: true content: application/json: schema: type: object required: - product_cart additionalProperties: false properties: product_cart: type: array minItems: 1 maxItems: 1 description: Exatamente 1 item. items: type: object required: - product_id additionalProperties: false properties: product_id: type: string description: Produto ativo do negócio. pattern: ^prod_[A-Za-z0-9_-]{16}$ examples: - prod_Xk2v9QeR7tLmN3bA quantity: type: integer description: Quantidade. minimum: 1 maximum: 100 default: 1 customer: description: >- Cliente salvo (`customer_id`) **ou** dados para preencher o formulário. oneOf: - title: Cliente salvo type: object required: - customer_id additionalProperties: false properties: customer_id: type: string description: Cliente do negócio. pattern: ^cus_[A-Za-z0-9_-]{16}$ examples: - cus_Xk2v9QeR7tLmN3bA - title: Dados do cliente type: object additionalProperties: false properties: name: type: string description: Nome (até 120). maxLength: 120 email: type: string description: E-mail. format: email phone: type: string description: Celular com DDD, só dígitos (10 ou 11). pattern: ^\d{10,11}$ allowed_payment_method_types: type: array minItems: 1 maxItems: 3 items: type: string enum: - pix - card - boleto description: 'Formas aceitas. Padrão: todas.' success_url: type: string description: Para onde o cliente volta depois de pagar (HTTPS). format: uri cancel_url: type: string description: Para onde o cliente volta ao desistir (HTTPS). format: uri expires_in: type: integer description: Validade do link em segundos. minimum: 300 maximum: 86400 default: 86400 external_reference: type: string description: O seu identificador (id do pedido, SKU). Até 100 caracteres. maxLength: 100 examples: - pedido-1001 metadata: type: object additionalProperties: type: string maxLength: 500 maxProperties: 20 description: >- Até 20 pares chave/valor em texto (chave até 40, valor até 500 caracteres). Volta igual nas respostas e nos webhooks. examples: - order_id: '1001' examples: exemplo: summary: Exemplo value: product_cart: - product_id: prod_Ab12Cd34Ef56Gh78 quantity: 1 customer: name: Ana Souza email: ana@example.com allowed_payment_method_types: - pix - card success_url: https://sualoja.com/pedido/1001/obrigado cancel_url: https://sualoja.com/carrinho external_reference: pedido-1001 responses: '201': description: Compra criada. content: application/json: schema: $ref: '#/components/schemas/CheckoutSession' '401': description: Chave ausente, inválida ou revogada. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_api_key message: Chave de API inválida ou revogada. '403': description: >- A chave não tem o escopo da rota, ou a empresa ainda não opera em produção. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: missing_scope message: A chave não tem o escopo necessário. '404': description: Produto ou cliente não encontrado. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: product_not_found message: Produto não encontrado. '409': description: Produto não está ativo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: product_inactive message: O produto não está ativo. '422': description: Dados inválidos. Veja `details`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request message: Corpo inválido. details: amount: - Valor inválido. '429': description: Limite de requisições. Veja o header `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limited message: Muitas requisições. Tente novamente em instantes. '503': description: Indisponibilidade temporária. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: service_unavailable message: Serviço temporariamente indisponível. security: - bearerAuth: [] components: schemas: CheckoutSession: type: object properties: id: type: string description: Id da compra. pattern: ^cs_[A-Za-z0-9_-]{16}$ examples: - cs_Xk2v9QeR7tLmN3bA object: type: string description: Sempre `checkout_session`. enum: - checkout_session status: type: string description: >- `open`: aguardando; `processing`: em análise; `paid`: pago; `failed`: tentativa falhou; `expired`: venceu. enum: - open - processing - paid - failed - expired livemode: type: boolean description: Ambiente da compra. checkout_url: type: string description: Link para mandar ao cliente. format: uri examples: - https://pay.valorapayments.com.br/s/cs_Xk2v9QeR7tLmN3bA product_cart: type: array items: type: object properties: product_id: type: string description: Produto. name: type: string description: Nome no momento da compra. quantity: type: integer description: Quantidade. unit_amount: type: integer description: Preço unitário em centavos. amount: type: object properties: subtotal: type: integer description: Subtotal em centavos. total: type: integer description: Total em centavos. currency: type: string description: Moeda. enum: - BRL allowed_payment_method_types: type: array items: type: string enum: - pix - card - boleto description: Formas aceitas. customer_id: type: - string - 'null' description: Cliente associado. payment_id: type: - string - 'null' description: Pagamento gerado quando o cliente escolhe a forma de pagamento. method: type: - string - 'null' description: Forma escolhida pelo cliente. enum: - pix - card - boleto success_url: type: - string - 'null' description: Retorno depois de pagar. cancel_url: type: - string - 'null' description: Retorno ao desistir. external_reference: type: - string - 'null' description: O seu identificador. metadata: type: object additionalProperties: type: string maxLength: 500 maxProperties: 20 description: >- Até 20 pares chave/valor em texto (chave até 40, valor até 500 caracteres). Volta igual nas respostas e nos webhooks. examples: - order_id: '1001' expires_at: type: string description: Prazo da compra. format: date-time completed_at: type: - string - 'null' description: Quando foi paga. format: date-time created_at: type: string description: Criação. format: date-time Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string description: Código estável do erro. Veja a página Erros. examples: - invalid_request message: type: string description: Explicação em português. Não compare o texto. examples: - Corpo inválido. details: type: object additionalProperties: type: array items: type: string description: 'Só em erros de validação: problemas por campo.' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave de API `sk_vl_...` criada no painel em Desenvolvedores → Chaves de API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.