> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korbit.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar payment intent
> Cria uma cobrança por **PIX** ou **cartão**. A resposta vem em `REQUIRES_ACTION` com os dados para o comprador pagar (código PIX copia-e-cola) ou com o desafio de autenticação pendente. O estado final da cobrança chega pelos eventos de webhook — consulte `GET /v1/payment-intents/{id}` sempre que precisar do estado autoritativo. Requer `Idempotency-Key`.
O valor é sempre em **centavos** e é fixado server-side a partir deste corpo — o comprador não altera valores. Veja [Moeda e valores](/guias/moeda-e-valores).
Gere um `Idempotency-Key` novo por intenção de cobrança e reutilize-o nos retries do mesmo request. Veja [Idempotência](/guias/idempotencia).
## OpenAPI
````yaml /openapi/korbit-public-v1.json post /v1/payment-intents
openapi: 3.1.0
info:
title: Korbit API
version: 1.0.0
description: >-
API de pagamentos da Korbit para merchants: PIX, cartão (com 3DS),
assinaturas, checkout por link, payouts, antecipações e refunds — com
idempotência, webhooks assinados e ambiente sandbox.
contact:
name: Suporte Korbit
email: suporte@korbit.com.br
servers:
- url: https://api.korbit.com.br
description: Produção (chaves kbt_live_)
- url: https://api-test.korbit.com.br
description: Sandbox (chaves kbt_test_)
security:
- bearerAuth: []
tags:
- name: Antecipações
- name: Assinaturas
- name: Atividade
- name: Catálogo
- name: Chaves de API
- name: Checkout
- name: Clientes e Pedidos
- name: Pagamentos
- name: Refunds e Disputas
- name: Saldo e Saques
- name: Sandbox
- name: Webhooks
paths:
/v1/payment-intents:
post:
tags:
- Pagamentos
summary: Criar payment intent
description: >-
Cria uma cobrança por **PIX** ou **cartão**. A resposta vem em
`REQUIRES_ACTION` com os dados para o comprador pagar (código PIX
copia-e-cola) ou com o desafio de autenticação pendente. O estado final
da cobrança chega pelos eventos de webhook — consulte `GET
/v1/payment-intents/{id}` sempre que precisar do estado autoritativo.
Requer `Idempotency-Key`.
operationId: createPaymentIntent
parameters:
- schema:
type: string
minLength: 1
maxLength: 255
in: header
name: idempotency-key
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- paymentMethod
- amount
- card
- currency
properties:
paymentMethod:
type: string
enum:
- PIX
description: >-
Método de pagamento: `PIX` para cobrança instantânea por
QR/copia-e-cola ou `CARD` para cartão de crédito.
amount:
type: integer
minimum: 1
maximum: 9007199254740991
description: >-
Valor total em centavos (BRL). Ex.: `14990` = R$ 149,90. Não
há campo de desconto nem taxa — o valor cobrado é exatamente
este.
card:
type: object
additionalProperties: false
required:
- installments
- payer
- paymentMethodId
- paymentMethodType
- token
properties:
deviceSessionId:
type: string
minLength: 1
maxLength: 256
pattern: ^[A-Za-z0-9_-]+$
installments:
type: integer
minimum: 1
maximum: 24
issuerId:
type: string
minLength: 1
maxLength: 64
payer:
type: object
additionalProperties: false
required:
- email
properties:
email:
type: string
format: email
maxLength: 254
identification:
type: object
additionalProperties: false
required:
- number
- type
properties:
number:
type: string
minLength: 11
maxLength: 18
pattern: ^[0-9]+$
type:
type: string
enum:
- CPF
- CNPJ
paymentMethodId:
type: string
minLength: 1
maxLength: 64
paymentMethodType:
type: string
enum:
- credit_card
- debit_card
token:
type: string
minLength: 1
maxLength: 2048
currency:
type: string
enum:
- BRL
description: Moeda da cobrança. Atualmente apenas `BRL`.
description:
type: string
minLength: 1
maxLength: 200
description: >-
Descrição visível nos relatórios e na conciliação (ex.:
"Pedido #1042"). Não é exibida ao comprador no checkout
hospedado.
externalReference:
type: string
minLength: 1
maxLength: 128
description: >-
Seu identificador interno do pedido (ex.: id no seu banco).
Útil para conciliar depois — pode ser consultado e filtrado.
metadata:
type: object
maxProperties: 20
additionalProperties:
type: string
maxLength: 500
description: >-
Objeto livre para seus dados (máx. de chaves limitado pelo
schema). Nunca inclua dados pessoais sensíveis.
expiresInSeconds:
type: integer
minimum: 300
maximum: 86400
description: >-
TTL da cobrança em segundos. Após expirar, a cobrança não
pode mais ser paga (PIX padrão: 900 s).
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- amount
- createdAt
- currency
- description
- externalReference
- id
- metadata
- paymentMethod
- pix
- status
- updatedAt
properties:
cardAction:
type: object
additionalProperties: false
required:
- type
- externalResourceUrl
- creq
- expiresAt
properties:
type:
enum:
- THREE_DS
externalResourceUrl:
type: string
format: uri
maxLength: 2048
pattern: ^https://
creq:
type: string
minLength: 1
maxLength: 16384
pattern: ^[A-Za-z0-9_=-]+$
expiresAt:
type: string
format: date-time
amount:
type: integer
minimum: 1
maximum: 9007199254740991
createdAt:
type: string
format: date-time
currency:
type: string
enum:
- BRL
description:
anyOf:
- type: string
maxLength: 200
- type: 'null'
externalReference:
anyOf:
- type: string
maxLength: 128
- type: 'null'
id:
type: string
format: uuid
metadata:
type: object
maxProperties: 20
additionalProperties:
type: string
maxLength: 500
paymentMethod:
type: string
enum:
- PIX
- CARD
pix:
anyOf:
- type: object
additionalProperties: false
required:
- copyAndPaste
- expiresAt
properties:
copyAndPaste:
type: string
minLength: 1
maxLength: 4096
expiresAt:
type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- CREATED
- PROCESSING
- REQUIRES_ACTION
- SUCCEEDED
- FAILED
- CANCELED
- EXPIRED
updatedAt:
type: string
format: date-time
'201':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- amount
- createdAt
- currency
- description
- externalReference
- id
- metadata
- paymentMethod
- pix
- status
- updatedAt
properties:
cardAction:
type: object
additionalProperties: false
required:
- type
- externalResourceUrl
- creq
- expiresAt
properties:
type:
enum:
- THREE_DS
externalResourceUrl:
type: string
format: uri
maxLength: 2048
pattern: ^https://
creq:
type: string
minLength: 1
maxLength: 16384
pattern: ^[A-Za-z0-9_=-]+$
expiresAt:
type: string
format: date-time
amount:
type: integer
minimum: 1
maximum: 9007199254740991
createdAt:
type: string
format: date-time
currency:
type: string
enum:
- BRL
description:
anyOf:
- type: string
maxLength: 200
- type: 'null'
externalReference:
anyOf:
- type: string
maxLength: 128
- type: 'null'
id:
type: string
format: uuid
metadata:
type: object
maxProperties: 20
additionalProperties:
type: string
maxLength: 500
paymentMethod:
type: string
enum:
- PIX
- CARD
pix:
anyOf:
- type: object
additionalProperties: false
required:
- copyAndPaste
- expiresAt
properties:
copyAndPaste:
type: string
minLength: 1
maxLength: 4096
expiresAt:
type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- CREATED
- PROCESSING
- REQUIRES_ACTION
- SUCCEEDED
- FAILED
- CANCELED
- EXPIRED
updatedAt:
type: string
format: date-time
'400':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
'401':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
'403':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
'409':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
'429':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
'503':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- detail
- instance
- requestId
- status
- title
- type
properties:
code:
type: string
detail:
type: string
instance:
type: string
requestId:
type: string
status:
type: integer
minimum: 400
maximum: 599
title:
type: string
type:
type: string
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Korbit API key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.