> ## Documentation Index > Fetch the complete documentation index at: https://docs.veepag.com/llms.txt > Use this file to discover all available pages before exploring further. # Adicionar uma nova transação > Cria uma transacao avulsa com cartao. A API pode criar ou reutilizar cliente por documento, criar o meio de pagamento e disparar webhook transaction.created. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/transaction openapi: 3.1.1 info: title: Veepag API description: >- API publica da Veepag para transacoes, clientes, assinaturas, produtos, cobrancas e alertas. Autentique as chamadas com o header `apiKey` no formato `keyId.secret` ou com o header `token` contendo um JWT valido. Use o ambiente de sandbox para testes e producao apenas depois da homologacao. version: 1.0.0 contact: {} servers: - url: https://sandbox.api.veepag.com description: Sandbox - url: https://api.veepag.com description: Produção security: - api_key: [] - token: [] tags: - name: Transaction description: >- Pagamentos avulsos, captura, cancelamento, consulta e exportacao de transacoes. - name: Client description: Cadastro, atualizacao e consulta de clientes. - name: Subscription description: Criacao, consulta, atualizacao e cancelamento de assinaturas. - name: Product description: Configuracao de produtos, precos e regras de cobranca. - name: Charge description: Criacao, pagamento, cancelamento e conciliacao de cobrancas. - name: Alert description: Consulta e tratamento de alertas Ethoca/Visa. paths: /v1/transaction: post: tags: - Transaction summary: Adicionar uma nova transação description: >- Cria uma transacao avulsa com cartao. A API pode criar ou reutilizar cliente por documento, criar o meio de pagamento e disparar webhook transaction.created. operationId: TransactionController_createTransaction parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTransactionDto' example: companyId: company_id amount: 9900 installments: 1 capture: true paymentProfile: cardNumber: '4111111111111111' cardExpiration: 10/2026 holderName: CLIENTE TESTE cardCvv: '123' client: name: Cliente Teste doc: '12345678909' email: cliente@example.com responses: '201': description: Transacao criada. content: application/json: schema: $ref: '#/components/schemas/Transaction' example: _id: transaction_id companyId: company_id status: PAID amount: 9900 paymentMethod: CREDIT_CARD '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Payload invalido. type: field path: companyId location: body code: ZodValidationException path: /v1/transaction metadata: {} '401': description: Credencial ausente ou invalida. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Unauthorized. code: unauthorized path: /v1/transaction metadata: {} '403': description: Credencial sem acesso ao recurso ou empresa solicitada. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Forbidden. code: forbidden path: /v1/transaction metadata: {} '500': description: Erro interno nao mapeado. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error_messages: - msg: Unknown server error. code: unknown_server_error path: /v1/transaction metadata: {} security: - api_key: [] - token: [] components: schemas: CreateTransactionDto: type: object properties: companyId: type: string description: >- ID da empresa que recebera a transacao. A credencial precisa ter acesso a essa empresa. paymentProfile: type: object properties: cardNumber: type: string cardExpiration: type: string holderName: type: string cardCvv: type: string required: - cardNumber - cardExpiration - holderName description: Dados do cartao usados para processar a transacao. client: type: object properties: referenceId: type: string name: type: string minLength: 1 doc: type: string minLength: 1 cpf: type: string minLength: 1 birth: type: string email: type: string format: email phone: type: array items: type: string note: type: string type: type: - string - 'null' enum: - INDIVIDUAL - COMPANY x-enumNames: - INDIVIDUAL - COMPANY address: type: object properties: street: type: string number: type: string additionalDetails: type: string complement: type: string zipcode: type: string neighborhood: type: string city: type: string state: type: string country: type: string device: type: object properties: colorDepth: type: number javaEnable: type: boolean language: type: string screenHeight: type: number screenWidth: type: number timezoneOffset: type: number userAgent: type: - string - 'null' javaEnabled: type: boolean ipAddress: type: string required: - name description: >- Dados do cliente enviados inline. Quando informado, o documento deve ser enviado em doc ou cpf. amount: type: number description: 'Valor da transacao em centavos. Exemplo: 9900 representa R$ 99,00.' example: 9900 installments: type: number default: 1 description: Quantidade de parcelas. Quando omitido, o fluxo usa 1 parcela. capture: type: boolean default: true description: >- Indica se a transacao deve ser capturada imediatamente. Quando omitido, o fluxo usa true. required: - companyId - paymentProfile - amount Transaction: type: object properties: _id: type: string description: ID da transacao. companyId: type: string description: ID da empresa vinculada a transacao. clientId: type: string description: ID do cliente vinculado, quando houver. productId: type: string description: ID do produto vinculado, quando houver. subscriptionId: type: string description: ID da assinatura vinculada, quando houver. chargeId: type: string description: ID da cobranca vinculada, quando houver. amount: type: number description: >- Valor da transacao, normalmente com value em centavos e currency BRL. installments: type: number description: Parcelamento da transacao. paymentMethod: $ref: '#/components/schemas/PaymentMethod' description: Meio de pagamento usado na transacao. status: $ref: '#/components/schemas/TransactionStatus' description: Status atual da transacao. message: type: string description: Mensagem principal retornada pelo processamento. message2: type: string description: Mensagem complementar retornada pelo processamento. card: type: object additionalProperties: true description: Dados de cartao salvos internamente, quando houver. acquirer: type: object additionalProperties: true description: Dados da adquirente vinculada a transacao. boleto: type: - object - 'null' additionalProperties: true description: Dados de boleto, quando gerados. qrCode: type: - object - 'null' additionalProperties: true description: Dados de Pix, quando gerados. metadata: type: object additionalProperties: true description: Metadados livres vinculados a transacao. createdAt: type: string format: date-time description: Data de criacao da transacao. lastUpdate: type: string format: date-time description: Data da ultima atualizacao da transacao. ErrorResponse: type: object properties: error_messages: type: array items: $ref: '#/components/schemas/ErrorMessage' code: type: string example: unauthorized path: type: string example: /v1/transaction metadata: type: object additionalProperties: true PaymentMethod: type: string enum: - CREDIT_CARD - DEBIT_CARD - BOLETO - PIX TransactionStatus: type: string enum: - PAID - PROCESSING - DECLINED - CANCELED - DISCARDED - AUTHORIZED - IN_ANALYSIS - ERROR_PAYMENT - DISPUTE - STANDBY - CHARGEBACK - PENDING_REVIEW - PENDING_3DS - BLOCKED - INVALID_PAYMENT - NO_PAYMENT_ROUTE - PENDING_PAYMENT - ERROR_REFUNDED ErrorMessage: type: object properties: msg: type: string example: Unauthorized. type: type: string example: field path: type: string example: companyId location: type: string example: body securitySchemes: api_key: type: apiKey in: header name: apiKey description: API key no formato keyId.secret. token: type: apiKey in: header name: token description: JWT valido. O token confirmado na codebase tem validade de 14 dias. ````