Skip to main content
POST
/
payments
Criar pagamento com cartão
curl --request POST \
  --url https://dev.plugtopay.com/api/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --data '
{
  "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
  }
}
'
{
  "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": []
}

Authorizations

​
X-Client-ID
string
header
required

Identificador público do cliente (integração servidor-a-servidor). Usado em conjunto com X-API-Key.

​
X-API-Key
string
header
required

Chave secreta de API (integração servidor-a-servidor). Usada em conjunto com X-Client-ID.

Headers

​
Idempotency-Key
string

Chave única por intenção de pagamento (tipicamente o ID do pedido). Reenviar a mesma requisição com a mesma chave nunca resulta em cobrança duplicada. Escopada por empresa.

Example:

"ORD-2026-12345"

Body

application/json

Corpo da criação de pagamento com cartão.

​
merchant_order_id
string
required

ID do pedido no seu sistema.

Example:

"ORD-2026-12345"

​
amount
integer
required

Valor total, em centavos.

Example:

15000

​
currency
string
required

Código ISO 4217.

Example:

"BRL"

​
payment_method
enum<string>
required
Available options:
card
Example:

"card"

​
customer
object
required

Dados do cliente pagador.

​
card
object
required

Dados do cartão. Use os campos de cartão cru (number, cvv, expiration_month, expiration_year) OU um token previamente vaultado. Ao usar cartão cru, installments é obrigatório.

​
process_on_gateway
enum<string>

Opcional. Força o processamento em um gateway específico, ignorando o roteamento padrão.

Available options:
pagarme,
safe2pay,
picpay
Example:

"pagarme"

​
splits
object[]

Opcional. Distribui parte do valor entre sub-contas. Suportado apenas em gateways com has_split: true.

Response

Aprovado dentro do time_to_wait_sync configurado.

Recurso de pagamento. O status raiz reflete o resultado final após todas as tentativas. Cada tentativa de fallback fica registrada em transactions[].

​
status
enum<string>
required

Estado do pagamento na resposta HTTP. processing é transitório, retornado apenas no 202 enquanto a resolução assíncrona está em andamento.

Available options:
pending,
approved,
failed,
refunded,
processing
Example:

"approved"

​
transaction_id
string<uuid> | null
required
Example:

"019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73"

​
amount
integer | null
required

Valor, em centavos.

Example:

15000

​
message
string
required
Example:

"Payment approved"

​
attempts
integer
required
Example:

1

​
payment_method
enum<string> | null
required

Método de pagamento.

Available options:
pix,
card,
billet
Example:

"card"

​
transactions
object[]
required
​
webhooks
object[]
required

Tentativas de entrega de webhook associadas à transação.

​
vault_token
string | null

Token do cartão vaultado, quando save_card: true.

Example:

"tok_a1b2c3d4e5f6"

​
request_time
string | null
Example:

"1.23s"

​
created_at
string<date-time> | null
Example:

"2026-04-30T01:23:45+00:00"

​
updated_at
string<date-time> | null
Example:

"2026-04-30T01:23:46+00:00"

​
card
object

Resumo do cartão na resposta de pagamento.

​
pix
object

Dados do QR PIX. Contém tudo que é necessário para renderizar o QR ao cliente.