PaymentIntents

Crie, confirme e acompanhe pagamentos Pix simulado e cartão de teste.

post /v1/payment-intents — Criar PaymentIntent
get /v1/payment-intents/{id} — Consultar PaymentIntent
get /v1/payment-intents/{id}/activity — Linha do tempo do PaymentIntent
post /v1/payment-intents/{id}/confirm — Confirmar PaymentIntent

post/v1/payment-intents

Criar PaymentIntent (createPaymentIntent)

Cria um PaymentIntent em requires_payment_method. payment_method_types define os métodos aceitos (padrão ["card"]); payer é opcional aqui e obrigatório no checkout hospedado. pix em payment_method_types com o Pix desligado no ambiente (kill switch PIX_SIMULATION_ENABLED) → 409 PAYMENT_METHOD_UNAVAILABLE. Repetir a requisição com a mesma Idempotency-Key e o mesmo corpo devolve o mesmo resultado, sem nova cobrança; corpo diferente → 409 IDEMPOTENCY_CONFLICT.

Idempotency-Key obrigatória rate limit: api_authenticatedrate limit: payment_intent_create

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:write
URL: https://api.v2.wolfpayteste.online/v1/payment-intents

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`Idempotency-Key`obrigatório	cabeçalho	string	Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = `409 IDEMPOTENCY_CONFLICT`. Guardada por 24 h. 8 a 255 caracteres
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

Idempotency-Keyobrigatório

cabeçalho

string

Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = 409 IDEMPOTENCY_CONFLICT. Guardada por 24 h.

8 a 255 caracteres

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Corpo da requisição

Objeto CreatePaymentIntentRequest

Corpo de createPaymentIntent
Campo	Tipo	Detalhes
`amount_minor` obrigatório	string	Padrão `^[1-9][0-9]*$`
`currency`	string	Padrão `^[A-Z]{3}$` Padrão: `"BRL"`
`payment_method_types`	string[]	Valores: `card`, `pix` 1 a 2 itens
`payer`	PayerInput
`description`	string	1 a 500 caracteres
`metadata`	mapa de string	Chaves: `^[A-Za-z0-9_.-]{1,40}$`

Exemplo de corpo json

{
  "amount_minor": "9900",
  "currency": "BRL",
  "payment_method_types": [
    "pix",
    "card"
  ],
  "payer": {
    "name": "Ana Compradora",
    "email": "ana@example.com",
    "phone": "(11) 98765-4321",
    "document": {
      "type": "cpf",
      "number": "529.982.247-25"
    }
  },
  "description": "Curso de fotografia",
  "metadata": {
    "pedido_interno": "A-1001"
  }
}

Resposta 201

PaymentIntent criado.

Objeto PaymentIntent

Resposta 201 de createPaymentIntent
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pi_`
`order_id` obrigatório	string \| null
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`provider_id` obrigatório	string
`latest_provider_attempt_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null
`payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_method_type` obrigatório	string \| null
`description` obrigatório	string \| null
`metadata` obrigatório	mapa de string
`payer` obrigatório	PayerView \| null
`next_action` obrigatório	PaymentNextAction \| null
`expires_at` obrigatório	string \| null
`cancellation_reason` obrigatório	string \| null

Exemplo de resposta 201 json

{
  "id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "order_id": null,
  "amount_minor": "9900",
  "currency": "BRL",
  "provider_id": "simulator",
  "failure_code": null,
  "payment_method_types": [
    "pix",
    "card"
  ],
  "description": "Curso de fotografia",
  "metadata": {
    "pedido_interno": "A-1001"
  },
  "payer": {
    "name": "Ana Compradora",
    "email": "ana@example.com",
    "phone": "+5511987654321",
    "document": {
      "type": "cpf",
      "last2": "25"
    }
  },
  "cancellation_reason": null,
  "status": "requires_payment_method",
  "latest_provider_attempt_id": null,
  "payment_method_type": null,
  "next_action": null,
  "expires_at": null
}

Erros

400 — IDEMPOTENCY_KEY_REQUIRED,VALIDATION_FAILED
401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN
409 — IDEMPOTENCY_CONFLICT,PAYMENT_LIMIT_EXCEEDED,PAYMENT_METHOD_UNAVAILABLE,TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR
503 — SERVICE_UNAVAILABLE

get/v1/payment-intents/{id}

Consultar PaymentIntent (getPaymentIntent)

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:read
URL: https://api.v2.wolfpayteste.online/v1/payment-intents/{id}

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do PaymentIntent (`pi_...`). mínimo 1 caractere(s)
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

idobrigatório

caminho

string

Id do PaymentIntent (pi_...).

mínimo 1 caractere(s)

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Resposta 200

PaymentIntent.

Objeto PaymentIntent

Resposta 200 de getPaymentIntent
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pi_`
`order_id` obrigatório	string \| null
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`provider_id` obrigatório	string
`latest_provider_attempt_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null
`payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_method_type` obrigatório	string \| null
`description` obrigatório	string \| null
`metadata` obrigatório	mapa de string
`payer` obrigatório	PayerView \| null
`next_action` obrigatório	PaymentNextAction \| null
`expires_at` obrigatório	string \| null
`cancellation_reason` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "order_id": null,
  "amount_minor": "9900",
  "currency": "BRL",
  "provider_id": "simulator",
  "failure_code": null,
  "payment_method_types": [
    "pix",
    "card"
  ],
  "description": "Curso de fotografia",
  "metadata": {
    "pedido_interno": "A-1001"
  },
  "payer": {
    "name": "Ana Compradora",
    "email": "ana@example.com",
    "phone": "+5511987654321",
    "document": {
      "type": "cpf",
      "last2": "25"
    }
  },
  "cancellation_reason": null,
  "status": "succeeded",
  "latest_provider_attempt_id": "pat_5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
  "payment_method_type": "pix",
  "next_action": null,
  "expires_at": "2026-11-06T12:30:00.000Z"
}

Erros

401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN
404 — RESOURCE_NOT_FOUND
409 — TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR

get/v1/payment-intents/{id}/activity

Linha do tempo do PaymentIntent (getPaymentIntentActivity)

Tentativas no provedor simulado, reembolsos e disputas do PaymentIntent (listas limitadas; truncated indica corte).

rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:read
URL: https://api.v2.wolfpayteste.online/v1/payment-intents/{id}/activity

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do PaymentIntent (`pi_...`). mínimo 1 caractere(s)
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

idobrigatório

caminho

string

Id do PaymentIntent (pi_...).

mínimo 1 caractere(s)

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Resposta 200

Linha do tempo.

Objeto PaymentActivity

Resposta 200 de getPaymentIntentActivity
Campo	Tipo	Detalhes
`payment_intent` obrigatório	object
`payment_intent.id` obrigatório	string	Começa com `pi_`
`payment_intent.order_id` obrigatório	string \| null
`payment_intent.amount_minor` obrigatório	string
`payment_intent.currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`payment_intent.status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`payment_intent.provider_id` obrigatório	string
`payment_intent.latest_provider_attempt_id` obrigatório	string \| null
`payment_intent.failure_code` obrigatório	string \| null
`payment_intent.payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_intent.payment_method_type` obrigatório	string \| null
`payment_intent.description` obrigatório	string \| null
`payment_intent.metadata` obrigatório	mapa de string
`payment_intent.payer` obrigatório	PayerView \| null
`payment_intent.next_action` obrigatório	PaymentNextAction \| null
`payment_intent.expires_at` obrigatório	string \| null
`payment_intent.cancellation_reason` obrigatório	string \| null
`payment_intent.created_at` obrigatório	string
`payment_intent.updated_at` obrigatório	string
`attempts` obrigatório	object[]	0 a 25 itens
`attempts[].id` obrigatório	string	Começa com `pat_`
`attempts[].state` obrigatório	string	Valores: `created`, `submitted`, `succeeded`, `failed`, `unknown`, `reconciled_succeeded`, `reconciled_failed`
`attempts[].provider_id` obrigatório	string
`attempts[].external_id` obrigatório	string \| null
`attempts[].canonical_error_code` obrigatório	string \| null
`attempts[].created_at` obrigatório	string
`attempts[].updated_at` obrigatório	string
`refunds` obrigatório	object[]	0 a 50 itens
`refunds[].id` obrigatório	string	Começa com `rfd_`
`refunds[].payment_intent_id` obrigatório	string	Começa com `pi_`
`refunds[].charge_id` obrigatório	string	Começa com `chg_`
`refunds[].amount_minor` obrigatório	string
`refunds[].currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`refunds[].status` obrigatório	string	Valores: `created`, `processing`, `succeeded`, `failed`, `unknown`
`refunds[].provider_id` obrigatório	string
`refunds[].external_id` obrigatório	string \| null
`refunds[].failure_code` obrigatório	string \| null
`refunds[].created_at` obrigatório	string
`refunds[].updated_at` obrigatório	string
`disputes` obrigatório	Dispute[]	0 a 50 itens
`truncated` obrigatório	object
`truncated.attempts` obrigatório	boolean
`truncated.refunds` obrigatório	boolean
`truncated.disputes` obrigatório	boolean

Exemplo de resposta 200 json

{
  "payment_intent": {
    "id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
    "order_id": null,
    "amount_minor": "9900",
    "currency": "BRL",
    "provider_id": "simulator",
    "failure_code": null,
    "payment_method_types": [
      "pix",
      "card"
    ],
    "description": "Curso de fotografia",
    "metadata": {
      "pedido_interno": "A-1001"
    },
    "payer": {
      "name": "Ana Compradora",
      "email": "ana@example.com",
      "phone": "+5511987654321",
      "document": {
        "type": "cpf",
        "last2": "25"
      }
    },
    "cancellation_reason": null,
    "status": "succeeded",
    "latest_provider_attempt_id": "pat_5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
    "payment_method_type": "pix",
    "next_action": null,
    "expires_at": "2026-11-06T12:30:00.000Z",
    "created_at": "2026-11-06T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:05.000Z"
  },
  "attempts": [
    {
      "id": "pat_5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
      "state": "succeeded",
      "provider_id": "simulator",
      "external_id": "sim_pix_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
      "canonical_error_code": null,
      "created_at": "2026-11-06T12:00:00.000Z",
      "updated_at": "2026-11-06T12:00:05.000Z"
    }
  ],
  "refunds": [
    {
      "id": "rfd_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "payment_intent_id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
      "charge_id": "chg_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
      "amount_minor": "4900",
      "currency": "BRL",
      "status": "succeeded",
      "provider_id": "simulator",
      "external_id": "sim_ref_4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
      "failure_code": null,
      "created_at": "2026-11-06T12:00:05.000Z",
      "updated_at": "2026-11-06T12:00:05.000Z"
    }
  ],
  "disputes": [],
  "truncated": {
    "attempts": false,
    "refunds": false,
    "disputes": false
  }
}

Erros

401 — AUTHENTICATION_REQUIRED
403 — FORBIDDEN
404 — RESOURCE_NOT_FOUND
409 — TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR

post/v1/payment-intents/{id}/confirm

Confirmar PaymentIntent (confirmPaymentIntent)

Confirma com {"type":"pix"} (responde 202 com status: "processing" e next_action.pix_qr sintético) ou com um cartão de teste ({"type":"card","test_card":"approved"}). O método precisa estar em payment_method_types. Cartão unavailable_then_* gera estado desconhecido no provedor: a resposta é 202 processing e a reconciliação resolve depois. Recusa → 402 PAYMENT_DECLINED. Com o Pix desligado no ambiente (kill switch PIX_SIMULATION_ENABLED) → 409 PAYMENT_METHOD_UNAVAILABLE; cartão de teste não é afetado.

Idempotency-Key obrigatória rate limit: api_authenticated

Autenticação: API key (sk_test_...) ou sessão do app do seller
Escopos: payments:write
URL: https://api.v2.wolfpayteste.online/v1/payment-intents/{id}/confirm

Parâmetros

Nome Onde Tipo Detalhes

Nome	Onde	Tipo	Detalhes
`id`obrigatório	caminho	string	Id do PaymentIntent (`pi_...`). mínimo 1 caractere(s)
`Idempotency-Key`obrigatório	cabeçalho	string	Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = `409 IDEMPOTENCY_CONFLICT`. Guardada por 24 h. 8 a 255 caracteres
`wolf-organization-id`	cabeçalho	string	Só para sessão do app do seller com mais de uma organização (senão `409 TENANT_SELECTION_REQUIRED`). Ignorado para API keys. Padrão `^org_`

idobrigatório

caminho

string

Id do PaymentIntent (pi_...).

mínimo 1 caractere(s)

Idempotency-Keyobrigatório

cabeçalho

string

Chave escolhida pelo cliente (8 a 255 caracteres). Mesma chave + mesmo corpo = mesma resposta; corpo diferente = 409 IDEMPOTENCY_CONFLICT. Guardada por 24 h.

8 a 255 caracteres

wolf-organization-id

cabeçalho

string

Só para sessão do app do seller com mais de uma organização (senão 409 TENANT_SELECTION_REQUIRED). Ignorado para API keys.

Padrão ^org_

Corpo da requisição

Objeto ConfirmPaymentIntentRequest

Corpo de confirmPaymentIntent
Campo	Tipo	Detalhes
`payment_method` obrigatório	PaymentMethod

Exemplo de corpo json

{
  "payment_method": {
    "type": "pix"
  }
}

Resposta 200

Pagamento concluído (cartão de teste aprovado).

Objeto PaymentIntent

Resposta 200 de confirmPaymentIntent
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pi_`
`order_id` obrigatório	string \| null
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`provider_id` obrigatório	string
`latest_provider_attempt_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null
`payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_method_type` obrigatório	string \| null
`description` obrigatório	string \| null
`metadata` obrigatório	mapa de string
`payer` obrigatório	PayerView \| null
`next_action` obrigatório	PaymentNextAction \| null
`expires_at` obrigatório	string \| null
`cancellation_reason` obrigatório	string \| null

Exemplo de resposta 200 json

{
  "id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "order_id": null,
  "amount_minor": "9900",
  "currency": "BRL",
  "provider_id": "simulator",
  "failure_code": null,
  "payment_method_types": [
    "pix",
    "card"
  ],
  "description": "Curso de fotografia",
  "metadata": {
    "pedido_interno": "A-1001"
  },
  "payer": {
    "name": "Ana Compradora",
    "email": "ana@example.com",
    "phone": "+5511987654321",
    "document": {
      "type": "cpf",
      "last2": "25"
    }
  },
  "cancellation_reason": null,
  "status": "succeeded",
  "latest_provider_attempt_id": "pat_5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
  "payment_method_type": "card",
  "next_action": null,
  "expires_at": null
}

Resposta 202

Pagamento em processamento: Pix aguardando pagamento (com next_action) ou cartão em reconciliação.

Objeto PaymentIntent

Resposta 202 de confirmPaymentIntent
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `pi_`
`order_id` obrigatório	string \| null
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `requires_payment_method`, `requires_action`, `processing`, `succeeded`, `failed`, `canceled`
`provider_id` obrigatório	string
`latest_provider_attempt_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null
`payment_method_types` obrigatório	string[]	Valores: `card`, `pix` 1 a n itens
`payment_method_type` obrigatório	string \| null
`description` obrigatório	string \| null
`metadata` obrigatório	mapa de string
`payer` obrigatório	PayerView \| null
`next_action` obrigatório	PaymentNextAction \| null
`expires_at` obrigatório	string \| null
`cancellation_reason` obrigatório	string \| null

Exemplo de resposta 202 json

{
  "id": "pi_3b9f0c2d1e4a5b6c7d8e9f0a1b2c3d4e",
  "order_id": null,
  "amount_minor": "9900",
  "currency": "BRL",
  "provider_id": "simulator",
  "failure_code": null,
  "payment_method_types": [
    "pix",
    "card"
  ],
  "description": "Curso de fotografia",
  "metadata": {
    "pedido_interno": "A-1001"
  },
  "payer": {
    "name": "Ana Compradora",
    "email": "ana@example.com",
    "phone": "+5511987654321",
    "document": {
      "type": "cpf",
      "last2": "25"
    }
  },
  "cancellation_reason": null,
  "status": "processing",
  "latest_provider_attempt_id": "pat_5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
  "payment_method_type": "pix",
  "next_action": {
    "type": "pix_qr",
    "qr_code_payload": "00020101021226780014br.gov.bcb.pix0120SIMULADO-NAO-PAGAVEL0232SIMULADO - NENHUMA COBRANCA REAL520400005303986540599.005802BR5921WOLF SANDBOX SIMULADO6009SAO PAULO62290525SIMULADO3b9f0c2d1e4a5b6c76304726B",
    "expires_at": "2026-11-06T12:30:00.000Z"
  },
  "expires_at": "2026-11-06T12:30:00.000Z"
}

Erros

400 — IDEMPOTENCY_KEY_REQUIRED,VALIDATION_FAILED
401 — AUTHENTICATION_REQUIRED
402 — PAYMENT_DECLINED
403 — FORBIDDEN
404 — RESOURCE_NOT_FOUND
409 — IDEMPOTENCY_CONFLICT,INVALID_STATE_TRANSITION,PAYMENT_LIMIT_EXCEEDED,PAYMENT_METHOD_UNAVAILABLE,PROVIDER_STATE_UNKNOWN,TENANT_SELECTION_REQUIRED
429 — RATE_LIMITED
500 — INTERNAL_ERROR