Criar intenção de pagamento
Registra o que vai ser cobrado. Nada é cobrado ainda. Quem vende é a sua empresa (a dona da chave de API); não há campo de vendedor no pedido.
- Cartão: a resposta traz
cardTokenization(ticket + chave de cifra + endereço do cofre). StatusREQUIRES_TOKEN. - Pix / boleto: status
REQUIRES_CONFIRMATION. Vá direto aoconfirm. Boleto exigebuyer.address. - Pix / boleto numa chamada só: mande
confirm: true. A cobrança já é gerada aqui: a resposta vem com statusCONFIRMED,transactionIde a transação inteira emtransaction(QR Code ou linha digitável emtransaction.paymentDetails). Não chame oconfirmdepois. Se a adquirente não responder →502 PROVIDER_ERROR, a intenção ficaFAILEDe oreferenceIdfica livre de novo. Com cartão,confirm: true→400 VALIDATION_ERROR.
A intenção expira em 5 minutos (expiresAt) se não for confirmada. Depois disso,
crie outra. referenceId, quando enviado, é único por empresa entre intenções em
andamento e transações; pode ser reusado depois que a intenção anterior expirar, for
cancelada ou falhar.
Chave de API da sua empresa. Por enquanto a SwitchPay gera a chave e entrega à sua empresa; em breve será possível criar pelo painel.
In: header
Header Parameters
Chave de idempotência. Obrigatória nesta rota (cria ou movimenta dinheiro). Use o id do pedido do seu lado.
length <= 255Valor total em centavos (mínimo R$ 1,00)
100 <= value <= 100000000"CREDIT_CARD" | "PIX" | "BOLETO"Só cartão
11 <= value <= 12Só Pix e boleto. true = cria e confirma na mesma chamada; a resposta já traz a transação em transaction. Com cartão → 400 VALIDATION_ERROR.
falseSeu id do pedido. Único por empresa entre intenções em andamento e transações. Consultável em GET /v2/transactions?referenceId=
length <= 128Aparece no extrato do comprador quando a adquirente permite
length <= 255Quem está pagando. Endereço obrigatório só pra boleto.
items <= 20Só quando paymentMethod é BOLETO. buyer.address obrigatório.
Até 20 pares chave/valor seus. Chave até 40 caracteres, valor até 500. Voltam na transação e no webhook.
properties <= 20Empty Object
Response Body
curl -X POST "https://api.sandbox.switchpay.app.br/v2/payment-intents" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "amountCents": 15000, "paymentMethod": "PIX", "referenceId": "pedido-8842", "description": "Pedido 8842 — Loja Exemplo", "buyer": { "name": "Maria Souza", "document": "12345678909", "email": "maria@exemplo.com", "phone": { "country": "55", "area": "11", "number": "987654321" } }, "splitRules": [ { "recipientDocument": "11222333000181", "type": "PERCENTAGE", "percentage": 10 } ], "metadata": { "orderId": "8842", "channel": "app" } }'{
"id": "pi_7b2f9c1e-4d3a-4c6b-9e1f-2a3b4c5d6e7f",
"status": "REQUIRES_CONFIRMATION",
"amountCents": 15000,
"paymentMethod": "PIX",
"installments": 1,
"sellerId": "cmp_8f2a1c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"referenceId": "pedido-8842",
"description": "Pedido 8842 — Loja Exemplo",
"buyer": {
"name": "Maria Souza",
"document": "12345678909",
"email": "maria@exemplo.com",
"phone": {
"country": "55",
"area": "11",
"number": "987654321"
}
},
"splitRules": [
{
"recipientDocument": "11222333000181",
"type": "PERCENTAGE",
"percentage": 10
}
],
"metadata": {
"orderId": "8842",
"channel": "app"
},
"expiresAt": "2026-10-06T14:05:00.000Z",
"createdAt": "2026-10-06T14:00:00.000Z",
"updatedAt": "2026-10-06T14:00:00.000Z"
}{
"code": "VALIDATION_ERROR",
"message": "Há campos inválidos na requisição.",
"details": [
{
"field": "buyer.document",
"message": "deve ter 11 ou 14 dígitos"
},
{
"field": "amountCents",
"message": "mínimo 100"
}
]
}{
"code": "UNAUTHORIZED",
"message": "Chave de API ausente, inválida ou de outro ambiente."
}{
"code": "FORBIDDEN",
"message": "Sua chave não tem permissão para esta operação."
}{
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "Esta Idempotency-Key já foi usada com outro corpo."
}{
"code": "SELLER_NOT_FOUND",
"message": "Sua empresa ainda não está habilitada como vendedora. Fale com a SwitchPay."
}{
"code": "RATE_LIMITED",
"message": "Limite de chamadas atingido. Aguarde e tente de novo."
}{
"code": "PROVIDER_ERROR",
"message": "A adquirente não respondeu. Tente novamente mais tarde."
}{
"code": "SERVICE_UNAVAILABLE",
"message": "Serviço de autorização indisponível. Tente novamente em instantes."
}