> ## Documentation Index > Fetch the complete documentation index at: https://docs.paybridge.dev/llms.txt > Use this file to discover all available pages before exploring further. # Criar Pagamento > Cria um novo pagamento PIX. O pagamento será processado através do PSP configurado e um código PIX será gerado. **Autenticação:** Requer uma API Key válida no header `X-API-Key`. **Modo de Teste:** Se você usar uma API Key de teste (`pk_test_*`), o pagamento será processado em modo sandbox sem transações reais. **Modo de Produção:** Se você usar uma API Key de produção (`pk_live_*`), cobranças reais serão criadas no PSP. ## Roteamento de Credenciais Existem 3 modos para selecionar a credencial usada no pagamento: 1. **`credentialId` fornecido** → Usa a credencial especificada diretamente (ignora regras do rule set). 2. **`ruleSetId` fornecido** → Usa o rule set para selecionar a credencial com base nas regras configuradas (faixa de preço → credencial padrão → fallbacks). 3. **Nenhum fornecido** → Usa a credencial padrão da organização (modo legado). ## OpenAPI ````yaml POST /v1/payments openapi: 3.0.0 info: title: Paybridge Public API description: >- API para integração de pagamentos PIX. ## Autenticação Todas as requisições devem incluir um header `X-API-Key` com uma API Key válida. ### Tipos de API Key - **Chaves de Teste** (`pk_test_*`): Usadas para pagamentos em sandbox/teste. Sem transações reais. - **Chaves de Produção** (`pk_live_*`): Usadas para pagamentos em produção. Transações reais. ### Exemplo ``` X-API-Key: pk_test_abc123... ``` ## Limite de Requisições Requisições à API são limitadas a 100 por minuto por API Key. ## Webhooks Configure webhooks no dashboard para receber atualizações de status dos pagamentos. version: '1.0' contact: {} servers: - url: https://api.paybridge.dev security: [] tags: - name: Pagamentos description: Operações de pagamento PIX paths: /v1/payments: post: tags: - Pagamentos summary: Criar um pagamento PIX description: >- Cria um novo pagamento PIX. O pagamento será processado através do PSP configurado e um código PIX será gerado. **Autenticação:** Requer uma API Key válida no header `X-API-Key`. **Modo de Teste:** Se você usar uma API Key de teste (`pk_test_*`), o pagamento será processado em modo sandbox sem transações reais. **Modo de Produção:** Se você usar uma API Key de produção (`pk_live_*`), cobranças reais serão criadas no PSP. ## Roteamento de Credenciais Existem 3 modos para selecionar a credencial usada no pagamento: 1. **`credentialId` fornecido** → Usa a credencial especificada diretamente (ignora regras do rule set). 2. **`ruleSetId` fornecido** → Usa o rule set para selecionar a credencial com base nas regras configuradas (faixa de preço → credencial padrão → fallbacks). 3. **Nenhum fornecido** → Usa a credencial padrão da organização (modo legado). operationId: PublicPaymentsController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInput' responses: '201': description: Pagamento criado com sucesso content: application/json: schema: $ref: '#/components/schemas/CreatePaymentOutput' '400': description: Dados da requisição inválidos content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: API Key inválida ou ausente content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: API Key não tem permissão para esta operação content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '500': description: Erro interno do servidor content: application/json: schema: $ref: '#/components/schemas/PublicApiInternalErrorResponse' security: - X-API-Key: [] components: schemas: CreatePaymentInput: type: object properties: credentialId: type: string description: >- ID da credencial a ser usada para este pagamento. Se fornecido, ignora as regras do rule set. Se nem `credentialId` nem `ruleSetId` forem fornecidos, a credencial padrão será usada. ruleSetId: type: string format: uuid description: >- ID do Rule Set para roteamento de credenciais. Quando fornecido, as regras do rule set serão usadas para selecionar a credencial primária e fallbacks. Se não fornecido, a credencial padrão será usada. amount: type: number example: 10 description: 'Valor em BRL (ex: 10.00 para R$ 10,00)' description: type: string example: 'Pagamento do pedido #123' description: Descrição do pagamento externalId: type: string example: pedido-123 description: ID de referência externa payer: $ref: '#/components/schemas/PayerDto' expirationMinutes: type: number default: 30 minimum: 5 description: Tempo de expiração em minutos metadata: type: object example: orderId: '123' source: mobile description: Metadados customizados (objeto JSON) required: - amount CreatePaymentOutput: type: object properties: id: type: string description: ID único do pagamento amount: type: number description: Valor do pagamento currency: type: string description: Moeda (BRL) status: type: string description: Status do pagamento provider: type: string description: Provedor de pagamento pixCopyPaste: type: string description: Código PIX copia e cola pixQrCodeBase64: type: string description: QR Code em Base64 expiresAt: format: date-time type: string description: Data de expiração createdAt: format: date-time type: string description: Data de criação isTest: type: boolean description: Se é um pagamento de teste/sandbox metadata: type: object example: orderId: '123' source: mobile description: Metadados customizados required: - id - amount - currency - status - provider - pixCopyPaste - expiresAt - createdAt PublicApiBadRequestResponse: type: object properties: statusCode: type: number example: 400 error: type: string example: BadRequest message: type: string example: amount must be greater than or equal to 1 timestamp: type: string example: '2026-01-21T22:00:00.000Z' required: - statusCode - error - message - timestamp PublicApiUnauthorizedResponse: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Invalid or missing API Key timestamp: type: string example: '2026-01-21T22:00:00.000Z' required: - statusCode - error - message - timestamp PublicApiForbiddenResponse: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: API Key does not have permission for this operation timestamp: type: string example: '2026-01-21T22:00:00.000Z' required: - statusCode - error - message - timestamp PublicApiInternalErrorResponse: type: object properties: statusCode: type: number example: 500 error: type: string example: InternalError message: type: string example: An unexpected error occurred timestamp: type: string example: '2026-01-21T22:00:00.000Z' traceId: type: string example: 2771463d58840c8e116dc6dda1e1e5d0 required: - statusCode - error - message - timestamp PayerDto: type: object properties: name: type: string example: João Silva description: Nome do pagador document: type: string example: '12345678900' description: CPF ou CNPJ do pagador email: type: string example: joao@exemplo.com.br description: E-mail do pagador phone: type: string example: '11999999999' description: >- Telefone do pagador (obrigatório por alguns gateways como AbacatePay) securitySchemes: X-API-Key: type: apiKey in: header name: X-API-Key description: API Key para autenticação (pk_live_* ou pk_test_*) ````