Pagamentos PIX

POST /payments/merchant/transaction/pix → 201

Cria uma cobrança PIX de valor arbitrário. Body .strict() (chaves desconhecidas são rejeitadas).

Body:

Campo	Tipo	Obrigatório	Regras / Default
amountCents	int	sim	inteiro positivo (centavos)
description	string	não	máx 255; vira título do item (default "Cobrança avulsa")
customer	object	sim	ver Customer
address	object	não	ver Address
expiresInDays	int	não	min 1, máx 365
idempotencyKey	string	sim	1–100 chars; único por empresa
metadata	object (record)	não	pares chave/valor arbitrários

Objeto Customer

Campo	Tipo	Obrigatório	Regras
name	string	sim	1–255
email	string	sim	email válido, máx 255
phone	string	não	dígitos ou formatado
documentNumber	string	sim	11–14 (CPF/CNPJ)
documentType	enum CPF | CNPJ	sim	—
externalRef	string	não	1–100

Objeto Address

Todos opcionais: street, streetNumber, complement, zipCode, neighborhood, city, state (strings), country (default "BR").

Resposta (201) — MerchantApiCreatePixResponseDto:

{
  "orderId": "uuid",
  "subTransactionId": "uuid",
  "transactionId": "string",
  "providerTransactionId": "string",
  "status": "PENDING",
  "amount": {
    "subtotalCents": 10000,
    "discountCents": 0,
    "totalCents": 10000,
    "currency": "BRL"
  },
  "pix": {
    "qrcode": "00020126...5204<copia-e-cola>",
    "expiresAt": "2026-07-16T12:00:00.000Z"
  }
}

Exemplo de request:

Criar cobrança PIX avulsa

curl -X POST https://goldpay-goldpay-api.f0czp0.easypanel.host/api/payments/merchant/transaction/pix \
  -H "X-Api-Key: <PUBLIC_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000,
    "description": "Pedido #123",
    "idempotencyKey": "pedido-123",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "documentNumber": "12345678909",
      "documentType": "CPF"
    }
  }'

POST /payments/merchant/transaction/pix/from-products → 201

Cria a cobrança a partir de produtos do catálogo (valor = preço × quantidade − cupom). Body .strict().

Body:

Campo	Tipo	Obrigatório	Regras / Default
items	array<Item>	sim	1–100 itens
couponCode	string	não	1–64
customer	object	sim	mesmo Customer
address	object	não	mesmo Address
expiresInDays	int	não	min 1, máx 365
idempotencyKey	string	sim	1–100
metadata	object	não	—

Item:

Campo	Tipo	Obrigatório	Regras
productId	string (uuid)	sim	—
quantity	int	sim	positivo
externalRef	string	não	referência de reconciliação

Resposta: idêntica à do endpoint anterior (MerchantApiCreatePixResponseDto), com amount.subtotalCents/discountCents/totalCents refletindo produtos e cupom.

GET /payments/merchant/transaction/:subTransactionId → 200

Consulta o status de uma cobrança. subTransactionId deve ser UUID (senão 400).

Resposta — MerchantApiChargeStatusResponseDto:

{
  "subTransactionId": "uuid",
  "transactionId": "string",
  "providerTransactionId": "string | null",
  "status": "PAID",
  "paidAt": "2026-07-16T12:03:00.000Z",
  "amount": {
    "totalCents": 10000,
    "refundedCents": 0,
    "currency": "BRL"
  }
}