> ## 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 pagamento Pix > Cria uma cobrança Pix e devolve o QR Code e o código copia e cola. Envie `amount` **ou** `product_id` (um dos dois). A confirmação chega pelo webhook `payment.succeeded`. Escopo: `payments:write`. ## OpenAPI ````yaml /openapi.json post /v1/payments 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/payments: post: tags: - Pagamentos summary: Criar um pagamento Pix description: >- Cria uma cobrança Pix e devolve o QR Code e o código copia e cola. Envie `amount` **ou** `product_id` (um dos dois). A confirmação chega pelo webhook `payment.succeeded`. Escopo: `payments:write`. operationId: criarPagamento parameters: - name: Idempotency-Key in: header required: false description: >- Chave única da operação (até 200 caracteres). Repetir com o mesmo corpo devolve o pagamento já criado. schema: type: string maxLength: 200 requestBody: required: true content: application/json: schema: type: object required: - method additionalProperties: false properties: method: type: string description: Forma de pagamento. Pela API, só `pix`. enum: - pix amount: oneOf: - type: string pattern: ^\d{1,9}(\.\d{1,2})?$ - type: number description: >- Valor da cobrança. Obrigatório sem `product_id`. Em reais, com até 2 casas e ponto decimal (ex.: "149.90"). Mínimo 0.01. examples: - '149.90' product_id: type: string description: Produto do catálogo. O valor passa a ser preço × `quantity`. pattern: ^prod_[A-Za-z0-9_-]{16}$ examples: - prod_Xk2v9QeR7tLmN3bA quantity: type: integer description: Quantidade do produto. minimum: 1 maximum: 10000 default: 1 currency: type: string description: Moeda. enum: - BRL default: BRL customer_id: type: string description: Cliente associado. pattern: ^cus_[A-Za-z0-9_-]{16}$ examples: - cus_Xk2v9QeR7tLmN3bA external_reference: type: string description: O seu identificador (id do pedido, SKU). Até 100 caracteres. maxLength: 100 examples: - pedido-1001 description: type: string description: Descrição da cobrança (até 200 caracteres). maxLength: 200 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_in: type: integer description: Validade do Pix em segundos. minimum: 60 maximum: 86400 default: 3600 splits: type: array minItems: 1 maxItems: 5 description: >- Divide o valor líquido entre negócios do mesmo dono. A soma de `share_bps` deve ser 10000. items: type: object required: - business_id - share_bps properties: business_id: type: string description: Negócio que recebe a parte. share_bps: type: integer description: Parte em pontos-base. minimum: 1 maximum: 10000 examples: exemplo: summary: Exemplo value: method: pix amount: '149.90' description: Pedido 1001 external_reference: pedido-1001 expires_in: 1800 responses: '200': description: >- Repetição com a mesma `Idempotency-Key` e o mesmo corpo: o pagamento já criado (header `Idempotent-Replayed: true`). content: application/json: schema: $ref: '#/components/schemas/Payment' '201': description: Pagamento criado. content: application/json: schema: $ref: '#/components/schemas/Payment' '400': description: '`Idempotency-Key` inválida ou JSON malformado.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_idempotency_key message: Idempotency-Key deve ter até 200 caracteres. '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. '409': description: Mesma `Idempotency-Key` com corpo diferente. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: idempotency_conflict message: Idempotency-Key já usada com outro corpo. '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. '502': description: >- Falha no provedor de pagamento. Repita com a mesma `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: provider_error message: Falha ao criar a cobrança. Tente novamente. security: - bearerAuth: [] components: schemas: Payment: type: object required: - id - object - livemode - method - status - amount - fee - created_at properties: id: type: string description: Id do pagamento. pattern: ^pay_[A-Za-z0-9_-]{16}$ examples: - pay_Xk2v9QeR7tLmN3bA object: type: string description: Sempre `payment`. enum: - payment livemode: type: boolean description: '`true` em produção, `false` no ambiente de teste.' method: type: string description: Forma de pagamento. enum: - pix - card - boleto status: type: string description: >- Status. `requires_payment`: aguardando; `processing`: em análise; `succeeded`: pago; `underpaid`/`overpaid`: pago com valor diferente (em análise); `expired`; `failed`; `canceled`; `partially_refunded`; `refunded`; `disputed`: cartão contestado. enum: - requires_payment - processing - succeeded - underpaid - overpaid - expired - failed - canceled - partially_refunded - refunded - disputed amount: type: object description: Valor cobrado. required: - value - currency properties: value: type: integer description: Valor em centavos. examples: - 14990 currency: type: string description: Moeda. enum: - BRL customer_id: type: - string - 'null' description: Cliente associado. external_reference: type: - string - 'null' description: O seu identificador. description: type: - string - 'null' description: Descrição da cobrança. 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' fee: type: object description: Taxa da Valora neste pagamento. properties: bps: type: integer description: Parte percentual em pontos-base (199 = 1,99%). fixed: type: integer description: Parte fixa, em centavos. amount: type: integer description: Taxa total, em centavos. refunded_amount: type: integer description: Total já devolvido ao pagador, em centavos. dispute: type: - object - 'null' description: Contestação (chargeback) do cartão. properties: status: type: string description: Estado. enum: - open - won - lost opened_at: type: string description: Abertura. format: date-time closed_at: type: - string - 'null' description: Encerramento. format: date-time items: type: array description: Cópia do produto no momento da compra. items: type: object properties: product_id: type: string description: Produto. name: type: string description: Nome. unit_amount: type: integer description: Preço unitário em centavos. quantity: type: integer description: Quantidade. splits: type: array description: Divisão do valor líquido entre negócios do mesmo dono. items: type: object properties: business_id: type: string description: Negócio. share_bps: type: integer description: Parte em pontos-base. amount: type: integer description: Valor em centavos. status: type: string description: Estado. enum: - pending - settled expires_at: type: string description: Prazo para pagar. format: date-time succeeded_at: type: - string - 'null' description: Quando o pagamento foi confirmado. format: date-time created_at: type: string description: Criação. format: date-time pix: type: object description: Só em pagamentos Pix. properties: txid: type: string description: Id da cobrança Pix. e2e_id: type: - string - 'null' description: >- Identificador da transação no Banco Central (depois do pagamento). brcode: type: string description: Código copia e cola. qr_image: type: - string - 'null' description: QR Code em PNG (data URL). payer: type: - object - 'null' description: Quem pagou (documento mascarado). properties: name: type: - string - 'null' description: Nome. document_masked: type: - string - 'null' description: Documento mascarado. card: type: object description: Só em pagamentos com cartão. properties: brand: type: - string - 'null' description: Bandeira. last4: type: - string - 'null' description: Últimos 4 dígitos. installments: type: integer description: Parcelas (1, 2, 3, 6 ou 12). decline_reason: type: - string - 'null' description: Motivo da recusa informado pelo emissor. boleto: type: object description: Só em pagamentos por boleto. properties: barcode: type: - string - 'null' description: Linha digitável. link: type: - string - 'null' description: Página do boleto. pdf: type: - string - 'null' description: PDF do boleto. due_date: type: string description: Vencimento (AAAA-MM-DD). format: date pix: type: - object - 'null' description: Pix embutido. properties: brcode: type: string description: Copia e cola. qr_image: type: - string - 'null' description: QR Code (data URL). 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.