Sandbox
Simular falha ou cancelamento (só sandbox)
Marca a transação PENDING como CANCELED e dispara transaction.canceled. Em produção esta rota não existe (404 SANDBOX_ONLY).
AuthorizationBearer <token>
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
Path Parameters
idstring
Id com prefixo, exatamente como a API devolveu.
Length
length <= 64Response Body
curl -X POST "https://api.sandbox.switchpay.app.br/v2/sandbox/transactions/string/fail"{
"id": "trx_6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"status": "CANCELED",
"paymentMethod": "PIX",
"installments": 1,
"amountCents": 15000,
"feeCents": 0,
"netAmountCents": 0,
"currency": "BRL",
"sellerId": "cmp_8f2a1c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"sellerName": "Loja Exemplo",
"paymentIntentId": "pi_7b2f9c1e-4d3a-4c6b-9e1f-2a3b4c5d6e7f",
"referenceId": "pedido-8842",
"buyer": {
"name": "Maria Souza",
"document": "12345678909",
"email": "maria@exemplo.com",
"phone": {
"country": "55",
"area": "11",
"number": "987654321"
}
},
"paymentDetails": {
"pix": {
"qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304ABCD",
"expiresAt": "2026-10-06T17:00:00.000Z"
}
},
"split": {
"receivables": [
{
"recipientDocument": "11222333000181",
"role": "CUSTOM_SPLIT_RECIPIENT",
"installment": 1,
"grossAmountCents": 1500,
"feeCents": 0,
"amountCents": 1500,
"expectedOn": "2026-10-07",
"status": "CANCELED"
},
{
"recipientDocument": "99888777000166",
"role": "SELLER",
"installment": 1,
"grossAmountCents": 13500,
"feeCents": 149,
"amountCents": 13351,
"expectedOn": "2026-10-07",
"status": "CANCELED"
}
]
},
"canceledAt": "2026-10-06T17:00:05.000Z",
"createdAt": "2026-10-06T14:01:10.000Z",
"updatedAt": "2026-10-06T17:00:05.000Z"
}{
"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": "NOT_FOUND",
"message": "Recurso não encontrado."
}{
"code": "TRANSACTION_NOT_PENDING",
"message": "Só transações PENDING podem ser simuladas."
}{
"code": "RATE_LIMITED",
"message": "Limite de chamadas atingido. Aguarde e tente de novo."
}{
"code": "SERVICE_UNAVAILABLE",
"message": "Serviço de autorização indisponível. Tente novamente em instantes."
}