> ## Documentation Index > Fetch the complete documentation index at: https://fortal-pay.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Criar checkout > Cria uma página de pagamento hospedada com cliente opcional. Somente `items` é obrigatório. Informe `customerId` para associar um cliente existente. ## OpenAPI ````yaml openapi.yaml POST /checkouts openapi: 3.1.0 info: title: FortalPay API version: '1' description: > API para gerenciar clientes, produtos e cupons e para criar ou listar cobranças. A autenticação utiliza uma API key no cabeçalho `Authorization`. servers: - url: https://api-sandbox.fortalpay.tech/v1 description: Produção — API v1 security: - apiKeyAuth: [] tags: - name: Clientes description: Crie, filtre, consulte e remova clientes do lojista associado à API key. - name: Charges description: >- Create Pix charges and list charges owned by the merchant associated with the API key. - name: Checkouts description: Crie páginas de pagamento hospedadas pela FortalPay usando uma API key. - name: Produtos description: >- Crie, liste, consulte, atualize e remova produtos do lojista associado à API key. - name: Coupons description: >- Create, list, retrieve, update, and delete coupons owned by the merchant associated with the API key. paths: /checkouts: post: tags: - Checkouts summary: Criar checkout description: >- Cria uma página de pagamento hospedada pela FortalPay. Quando customerId é informado, a cobrança Pix é gerada e persistida antes da resposta. Requer uma API key FULL_ACCESS. operationId: createCheckout requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutRequest' examples: minimum: summary: Coletar os dados do cliente no checkout hospedado value: items: - id: 550e8400-e29b-41d4-a716-446655440000 quantity: 1 withCustomer: summary: Gerar Pix para um cliente existente value: items: - id: 550e8400-e29b-41d4-a716-446655440000 quantity: 1 coupons: - 9b49b454-235f-44ae-82e8-ff46bcf75df1 paymentMethods: - PIX customerId: 6f84d2b5-a612-4e67-8af5-69f98de980f5 completionUrl: https://seusite.com/sucesso returnUrl: https://seusite.com/voltar externalId: pedido-45891 metadata: origem: mobile responses: '201': description: Checkout criado com retorno resumido. content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutEnvelope' example: data: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 status: PENDING_PAYMENT total: 10000 availablePaymentMethods: - PIX checkoutUrl: >- https://pay.fortalpay.com.br/pay/3fa85f64-5717-4562-b3fc-2c963f66afa6 completionUrl: https://seusite.com/sucesso returnUrl: https://seusite.com/voltar externalId: pedido-45891 metadata: origem: mobile customer: name: Maria Silva email: maria@email.com document: '***.***.***-25' phone: '85999999999' items: - productName: Produto de exemplo unitPrice: 10000 quantity: 1 total: 10000 success: true error: null '400': description: >- Uma regra de negócio rejeitou a requisição ou o estado atual do recurso. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: A API key está ausente, é inválida, foi revogada ou expirou. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: A API key foi autenticada, mas não possui acesso de escrita. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- O produto, cliente ou cupom informado não existe ou não pertence ao merchant autenticado. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Um ou mais campos da requisição falharam na validação. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: CreateCheckoutRequest: title: Corpo de criação do checkout type: object required: - items properties: items: type: array minItems: 1 items: $ref: '#/components/schemas/CreateCheckoutItem' coupons: type: - array - 'null' items: type: string format: uuid description: UUIDs dos cupons disponibilizados no checkout hospedado. paymentMethods: type: - array - 'null' items: type: string enum: - PIX description: Quando omitido, utiliza PIX. Atualmente, apenas PIX é suportado. customerId: type: - string - 'null' format: uuid description: UUID de um cliente existente. completionUrl: type: - string - 'null' format: uri returnUrl: type: - string - 'null' format: uri externalId: type: - string - 'null' maxLength: 255 metadata: type: - object - 'null' maxProperties: 50 additionalProperties: true CreateCheckoutEnvelope: title: Retorno da criação do checkout type: object required: - data - success - error properties: data: $ref: '#/components/schemas/CreateCheckoutResponse' success: type: boolean const: true error: type: 'null' ErrorEnvelope: type: object required: - data - success - error properties: data: type: 'null' success: type: boolean const: false error: $ref: '#/components/schemas/ApiError' CreateCheckoutItem: title: Item do checkout type: object required: - id - quantity properties: id: type: string format: uuid description: UUID de um produto ativo pertencente ao merchant. quantity: type: integer minimum: 1 CreateCheckoutResponse: title: Checkout criado type: object required: - id - status - total - availablePaymentMethods - checkoutUrl - completionUrl - returnUrl - externalId - metadata - customer - items properties: id: type: string format: uuid status: $ref: '#/components/schemas/CheckoutStatus' total: type: integer description: Valor total do checkout em centavos. availablePaymentMethods: type: array items: type: string enum: - PIX checkoutUrl: type: string format: uri completionUrl: type: - string - 'null' format: uri returnUrl: type: - string - 'null' format: uri externalId: type: - string - 'null' description: Valor normalizado recebido em externalId. metadata: type: object additionalProperties: true customer: $ref: '#/components/schemas/CreateCheckoutCustomerResponse' items: type: array items: $ref: '#/components/schemas/CreateCheckoutItemResponse' ApiError: type: object required: - timestamp - status - message - path properties: timestamp: type: string format: date-time status: type: integer message: type: string description: Current backend messages are returned in Portuguese. path: type: string fields: type: - array - 'null' items: $ref: '#/components/schemas/FieldError' CheckoutStatus: type: string enum: - WAITING_CUSTOMER - READY_TO_CHARGE - PROCESSING_PAYMENT - PENDING_PAYMENT - PENDING_ANALYSIS - PAID - EXPIRED - CANCELED - FAILED - REFUNDED CreateCheckoutCustomerResponse: title: Cliente do checkout type: - object - 'null' description: >- Cliente associado ao checkout. Retorna null quando customerId não é informado. properties: name: type: string email: type: - string - 'null' document: type: - string - 'null' description: CPF ou CNPJ mascarado, preservando somente os dois últimos dígitos. example: '***.***.***-25' phone: type: - string - 'null' CreateCheckoutItemResponse: title: Item retornado type: object required: - productName - unitPrice - quantity - total properties: productName: type: string unitPrice: type: integer description: Preço unitário em centavos. quantity: type: integer total: type: integer description: Valor total do item em centavos. FieldError: type: object required: - field - message properties: field: type: string message: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > Todas as requisições devem incluir sua API key no cabeçalho `Authorization` usando o formato `ApiKey `. Não use o esquema `Bearer`. Sem esse cabeçalho, a requisição será rejeitada. Use `fpay_sk_test_...` no ambiente de teste e `fpay_sk_live_...` em produção. [Saiba como criar e usar uma API key](/authentication). ````