Pagamentos

Criar pagamento — cartão

POST /api/v1/payments — requer X-Client-ID + X-API-Key.

POST /api/v1/payments
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": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678909"
  },
  "card": {
    "number": "4111111111111111",
    "cvv": "123",
    "expiration_month": "12",
    "expiration_year": "2028",
    "installments": 1,
    "save_card": true
  }
}

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 process_on_gateway:

{
  "process_on_gateway": "pagarme"
}

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.

Resposta (201 ou 202)

{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "message": "Payment approved",
  "attempts": 1,
  "payment_method": "card",
  "vault_token": "tok_a1b2c3d4e5f6",
  "request_time": "1.23s",
  "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": "1.23s"
    }
  ],
  "card": {
    "brand": "visa",
    "last_4_digits": "1111",
    "authorization_nsu": "123456",
    "authorization_code": "654321",
    "soft_descriptor": null,
    "response_code": "00",
    "gateway_message": "Transação aprovada"
  },
  "webhooks": []
}

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",
  "customer": {
    "name": "Maria Santos",
    "email": "maria@example.com",
    "document": "98765432100"
  }
}

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,
  "payment_method": "pix",
  "pix": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_url": "data:image/png;base64,...",
    "qr_copy_paste": "00020126580014br.gov.bcb.pix...",
    "expiration_at": "2026-04-30T02:23:45+00:00"
  },
  "webhooks": []
}

Campo	Uso
`qr_code`	String EMV — copiar e colar
`qr_code_url`	Data URL da imagem do QR — renderizar com `<img>`
`qr_copy_paste`	Alias de `qr_code` para compatibilidade
`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 /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
`payment_method`	`pix\|card\|billet`	Método de pagamento
`gateway`	`pagarme\|safe2pay\|picpay`	Gateway processador
`amount_from`	inteiro (centavos)	Valor mínimo
`amount_to`	inteiro (centavos)	Valor máximo
`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

GET /api/v1/user/payments/{id} — requer Bearer JWT.

curl https://dev.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 array webhooks com as tentativas de entrega associadas à transação.