Pagamentos

Criar pagamento — cartão

POST /api/v1/payments/card — requer X-Client-ID + X-API-Key. Nenhum dado sensível de cartão fica salvo, somente os 4 últimos dígitos e as datas de expiração para controle do cliente. Todos os dados sensíveis de clientes, como CPF, são criptografados com o algoritmo AES-256-CBC com chave de 32 bytes, que não fica exposta em nenhum lugar, apenas nos cofres da AWS.

POST /api/v1/payments/card
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...
Idempotency-Key: ORD-2026-12345  (opcional, mas recomendado)

{
  "merchant_order_id": "ORD-2026-12345",
  "amount": 15000,
  "currency": "BRL",
  "payment_method": "card",
  "customer": {
    "token": "cus_7556...", // OU
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678909",
    "phone": "11987654321"       // opcional
  },
  "card": {
    "number": "4111111111111111",
    "cvv": "123",
    "expiration_month": "12",
    "expiration_year": "2028",
    "installments": 1,
    "holder": "Fulano da Silva",
    "holder_birthdate": "1990-05-25",
    "holder_document": "12345678909",
    "holder_phone": "11987542563",
    "save_card": true
  },
  "billing_address": {
    "street": "Rua dos advogados",
    "number": "321",
    "neighborhood": "Jardim",
    "zip_code": "35900000",
    "city": "Belo Horizonte",
    "state": "MG",
    "country": "Brasil"
  }
  // "splits": [...] — em breve
}

Para reutilizar um cartão tokenizado, substitua os campos do cartão pelo token:

{
  "card": {
    "token": "tok_a1b2c3d4e5f6",
    "installments": 1
  }
}

Para forçar um gateway específico, inclua gateway_first_try; ele será a prioridade 1 e, caso falhe, seguirá a regra definida na página de Orquestração:

{
  "gateway_first_try": "GATEWAY_SLUG"
}

Em ambiente sandbox é possível enviar a chave simulate_payment_fail para simular e testar a retentativa de pagamentos:

{
  "simulate_payment_fail": {
      "pagbank": "Motivo da falha",
      "asaas": ""
  }
}

Códigos de resposta

HTTP	Significado
`201 Created`	Aprovado dentro do `time_to_wait_sync` configurado
`202 Accepted`	Processamento em andamento — acompanhe via webhook ou polling
`500`	Falhou em todas as tentativas configuradas

O backend usa coroutines para processar o pagamento em paralelo à requisição. Se o gateway não responder dentro do time_to_wait_sync (padrão 5s), o status 202 é retornado imediatamente e o resultado final chega via webhook assim que o pagamento for finalizado.

Resposta (201 ou 202)

{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "message": "Payment approved",
  "attempts": 1,
  "payment_method": "card",
  "merchant_order_id": "ORD-2026-12345",
  "idempotency_key": "ORD-2026-12345",
  "plugtopay_request_time": "0.45s",
  "total_request_time": "1.23s",
  "gateways_request_time": "0.78s",
  "created_at": "2026-04-30T01:23:45+00:00",
  "updated_at": "2026-04-30T01:23:46+00:00",
  "transactions": [
    {
      "attempt": 1,
      "gateway": "pagarme",
      "status": "approved",
      "holder_name": "JOAO SILVA",
      "brand": "visa",
      "last_4_digits": "1111",
      "installments": 1,
      "response_code": "00",
      "gateway_message": "Transação aprovada",
      "soft_descriptor": null,
      "request_time": "0.78s"
    }
  ],
  "card": {
    "holder_name": "JOAO SILVA",
    "token": "card_86123...",
    "brand": "visa",
    "first_6_digits": "411111",
    "last_4_digits": "1111",
    "expire_month": "12",
    "expire_year": "2028",
    "status": "active",
    "response_code": "00",
    "soft_descriptor": null,
    "authorization_nsu": "123456",
    "gateway_message": "Transação aprovada",
    "created_at": "2026-04-30T01:23:45+00:00",
    "updated_at": "2026-04-30T01:23:46+00:00"
  },
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "token": "cus_7556...",
    "document_type": "cpf",
    "type": "individual",
    "phone": "11987654321",
    "phone_country_code": "55",
    "birthdate": "1990-05-25",
    "created_at": "2026-04-30T01:23:44+00:00",
    "updated_at": "2026-04-30T01:23:44+00:00"
  },
  "webhook": {
    "id": "wh_...",
    "status": "delivered",
    "url": "https://seu-servidor.com/webhooks",
    "retry_count": 0,
    "next_retry_at": null,
    "created_at": "2026-04-30T01:23:47+00:00",
    "attempts": []
  }
}

Pré-autorização, captura e cancelamento

Por padrão a cobrança é autorizada e capturada na mesma requisição. Enviando capture: false no corpo do pagamento com cartão, a PlugToPay apenas reserva o valor no cartão do cliente: a transação volta com status authorized e o dinheiro só sai quando você capturar. É o fluxo usado quando a cobrança final só se confirma depois — reserva de hospedagem, pedido que ainda vai ser separado no estoque, aluguel com caução.

{
  "merchant_order_id": "ORD-2026-12345",
  "amount": 15000,
  "currency": "BRL",
  "payment_method": "card",
  "capture": false,
  "customer": { "...": "..." },
  "card": { "...": "..." }
}

A pré-autorização depende do gateway que processar a transação. Hoje é suportada por Pagar.me, PagBank, Stripe e e-Rede. Nos demais, capture: false é ignorado e a cobrança sai capturada.

Capturar

POST /api/v1/payments/{id}/capture — confirma a cobrança de uma transação authorized.

POST /api/v1/payments/019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73/capture
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...

O corpo é opcional. Omitir captura o valor total; informar amount faz uma captura parcial.

{
  "amount": 5000
}

Resposta 200:

{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "captured_amount": 5000,
  "message": "Capture processed successfully."
}

Campo	Tipo	Obrigatório	Descrição
`amount`	inteiro (centavos, min 1)	não	Valor a capturar. Omitir captura o total. Não pode ultrapassar o valor autorizado

Cancelar a pré-autorização

POST /api/v1/payments/{id}/cancel — libera o valor reservado. Não tem corpo.

POST /api/v1/payments/019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73/cancel
X-Client-ID: client_...
X-API-Key: sk_...

Resposta 200:

{
  "status": "cancelled",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "message": "Authorization cancelled successfully."
}

Regras

Situação	Resultado
Transação não está em `authorized`	`422`
Transação não é de cartão	`422`
Valor da captura maior que o autorizado	`422`
Transação inexistente ou de outra empresa	`404`

Um 200 não garante que deu certo. Se o gateway recusar a captura ou o cancelamento, a resposta ainda é 200 — o que muda é o status do corpo, que vem como failed em vez de approved/cancelled. O 422 cobre só os casos da tabela acima. Sempre confira o status da resposta antes de considerar a operação concluída. O mesmo vale para o estorno.

Capturar e cancelar são operações finais e opostas: depois de capturar, use o estorno para devolver o valor; depois de cancelar, a transação não pode mais ser capturada.

Ainda não é possível assinar um webhook para as transições authorized e cancelled — a lista de eventos aceitos no cadastro de webhooks não inclui esses dois. Até que isso mude, acompanhe o resultado da captura e do cancelamento pela própria resposta da requisição ou consultando GET /payments/{id}.

Ambas as rotas também existem sob /api/v1/user/payments/{id}/capture e /cancel para uso do painel, autenticadas com Authorization: Bearer <jwt>.

Estornar pagamento

POST /api/v1/payments/{id}/refund — devolve ao cliente o valor de uma transação já aprovada (capturada). Para desfazer uma pré-autorização que ainda não foi capturada, use o cancelamento acima.

POST /api/v1/payments/019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73/refund
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...

O corpo é opcional. Omitir estorna o valor total; informar amount faz um estorno parcial.

{
  "amount": 5000
}

Resposta 200:

{
  "status": "refunded",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "refunded_amount": 5000,
  "message": "Refund processed successfully."
}

Situação	Resultado
Transação não está em `approved`	`422`
Transação não é de cartão	`422`
Valor do estorno maior que o da transação	`422`
Transação inexistente ou de outra empresa	`404`

Também disponível em /api/v1/user/payments/{id}/refund para o painel.

Criar pagamento — PIX

POST /api/v1/payments/pix — requer X-Client-ID + X-API-Key. O campo payment_method é injetado automaticamente pelo backend.

POST /api/v1/payments/pix
Content-Type: application/json
X-Client-ID: client_...
X-API-Key: sk_...
Idempotency-Key: ORD-PIX-2026-999  (opcional)

{
  "merchant_order_id": "ORD-PIX-2026-999",
  "amount": 5000,
  "currency": "BRL",
  "expires_in": 3600,                  // opcional — segundos até o QR expirar (mín. 60)
  "gateway_first_try": "GATEWAY_SLUG", // opcional
  "customer": {
    "name": "Maria Santos",
    "email": "maria@example.com",
    "document": "98765432100"
  }
  // "splits": [...] — em breve
}

Resposta PIX

O objeto pix contém tudo que é necessário para renderizar o QR ao cliente:

{
  "status": "pending",
  "transaction_id": "019ddb60-6f6e-72ee-99ff-a75b60ce6d87",
  "amount": 5000,
  "message": null,
  "attempts": 1,
  "payment_method": "pix",
  "merchant_order_id": "ORD-PIX-2026-999",
  "idempotency_key": null,
  "plugtopay_request_time": "0.12s",
  "total_request_time": "0.95s",
  "gateways_request_time": "0.83s",
  "created_at": "2026-04-30T01:23:45+00:00",
  "updated_at": "2026-04-30T01:23:45+00:00",
  "transactions": [
    {
      "gateway": "pagarme",
      "qr_code": "00020126580014br.gov.bcb.pix...",
      "qr_code_url": "data:image/png;base64,...",
      "expiration_at": "2026-04-30T02:23:45+00:00",
      "request_time": "0.83s"
    }
  ],
  "pix": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_url": "data:image/png;base64,...",
    "expiration_at": "2026-04-30T02:23:45+00:00"
  },
  "customer": {
    "name": "Maria Santos",
    "email": "maria@example.com",
    "token": "cus_9988...",
    "document_type": "cpf",
    "type": "individual",
    "phone": null,
    "phone_country_code": null,
    "birthdate": null,
    "created_at": "2026-04-30T01:23:44+00:00",
    "updated_at": "2026-04-30T01:23:44+00:00"
  },
  "webhook": null
}

Campo	Uso
`qr_code`	String EMV — copiar e colar
`qr_code_url`	Data URL da imagem do QR — renderizar com `<img>`
`expiration_at`	Quando o QR expira — exiba countdown ao usuário

Recomendamos aguardar o webhook de approved em vez de fazer polling. Se o usuário fechar a tela, armazene o transaction_id e consulte o status sob demanda via GET /api/v1/user/payments/{id}.

Listar pagamentos

Disponível em dois contextos com autenticação diferente:

Rota	Auth	Contexto
`GET /api/v1/payments`	`X-API-Key`	Integração servidor-a-servidor
`GET /api/v1/user/payments`	`Bearer JWT`	Painel administrativo

Ambas retornam o mesmo shape paginado e aceitam os mesmos filtros:

Parâmetro	Tipo	Descrição
`start_date`	`YYYY-MM-DD`	Data inicial (criação)
`end_date`	`YYYY-MM-DD`	Data final (criação)
`status`	`pending\|approved\|failed\|refunded`	Status da transação. `authorized` e `cancelled` ainda não são aceitos aqui e devolvem `422`
`payment_method`	`pix\|card\|billet`	Método de pagamento
`gateway`	`pagarme\|safe2pay\|asaas\|pagbank`	Gateway processador
`amount_from`	inteiro (centavos)	Valor mínimo
`amount_to`	inteiro (centavos)	Valor máximo
`transaction_id`	string (UUID)	ID exato da transação
`customer_email`	string (e-mail)	E-mail do cliente
`customer_document`	string	CPF ou CNPJ do cliente
`card_brand`	string	Bandeira do cartão (ex: `visa`)
`card_last_4`	string	Últimos 4 dígitos do cartão
`transaction_type`	`payment\|withdraw`	Tipo de transação
`per_page`	inteiro	Itens por página (padrão 15)
`page`	inteiro	Página atual

Resposta:

{
  "data": [ /* array de PaymentResource */ ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 142,
    "last_page": 10
  }
}

Buscar pagamento por ID

Disponível em dois contextos com autenticação diferente:

Rota	Auth	Contexto
`GET /api/v1/payments/{id}`	`X-API-Key`	Integração servidor-a-servidor
`GET /api/v1/user/payments/{id}`	`Bearer JWT`	Painel administrativo

curl https://sandbox-api.plugtopay.com/api/v1/user/payments/019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73 \
  -H "Authorization: Bearer eyJ..."

Retorna um único PaymentResource com o mesmo shape da listagem, incluindo o objeto webhook com as tentativas de entrega associadas à transação.

Introdução

Orquestração

Assinaturas

Recursos

Pagamentos

Criar pagamento — cartão

Códigos de resposta

Resposta (201 ou 202)

Pré-autorização, captura e cancelamento

Capturar

Cancelar a pré-autorização

Regras

Estornar pagamento

Criar pagamento — PIX

Resposta PIX

Listar pagamentos

Buscar pagamento por ID

​Criar pagamento — cartão

​Códigos de resposta

​Resposta (201 ou 202)

​Pré-autorização, captura e cancelamento

​Capturar

​Cancelar a pré-autorização

​Regras

​Estornar pagamento

​Criar pagamento — PIX

​Resposta PIX

​Listar pagamentos

​Buscar pagamento por ID

Criar pagamento — cartão

Códigos de resposta

Resposta (201 ou 202)

Pré-autorização, captura e cancelamento

Capturar

Cancelar a pré-autorização

Regras

Estornar pagamento

Criar pagamento — PIX

Resposta PIX

Listar pagamentos

Buscar pagamento por ID