Únicopag - API de Pagamentos | Gateway

Documentação oficial da API v1 - Integre pagamentos em sua aplicação

Visão Geral

A API do Únicopag é uma solução completa de gateway de pagamentos que permite processar pagamentos com cartão de crédito, PIX e boleto bancário de forma simples e segura em sua aplicação ou e-commerce.

Base URL

https://api.cloud.unicopag.com.br

Autenticação

Todas as requisições requerem o parâmetro api_token

Autenticação

Todas as requisições para a API devem incluir o parâmetro api_tokencomo query parameter.

Exemplo de Autenticação

GET /public/v1/balance?api_token=YOUR_API_TOKEN

Headers Requeridos

Accept: application/json

Content-Type: application/json (para requisições POST)

Atenção: Antifraude Obrigatório

Para processar transações de cartão de crédito, é obrigatório implementar a integração com o sistema de antifraude da Únicopag.

Acesse a aba Antifraude para ler a documentação completa e implementar o ThreatMetrix no seu checkout.

POSTCriar Pagamento

/public/v1/payments

Cria uma nova transação de pagamento. Suporta cartão de crédito, boleto e PIX.

Métodos de Pagamento

credit_cardbilletpix

Exemplo de Requisição

{
  "amount": 116,
  "payment_method": "credit_card",
  "installments": 1,
  "card": {
    "number": "4729530000412666",
    "holdername": "Teste Holder name",
    "exp_month": "02",
    "exp_year": "2028",
    "cvv": "220"
  },
  "customer": {
    "name": "Customer name 1",
    "email": "customer@example.com",
    "phone_number": "21000000000",
    "document": "45675071008"
  },
  "cart": [
    {
      "hash": "id_product2",
      "title": "Nome do produto",
      "price": 116,
      "quantity": 1,
      "operation_type": 1
    }
  ],
  "expire_in_days": 1,
  "postback_url": "https://webhook.site/your-webhook"
}

GETListar Transações

/public/v1/transactions

Retorna uma lista de todas as transações da conta.

GETConsultar Transação

/public/v1/transactions/:hash

Consulta os detalhes de uma transação específica usando seu hash identificador.

Exemplo de Resposta

{
  "id": "example123",
  "hash": "example123",
  "payment_method": "pix",
  "payment_status": "waiting_payment",
  "installments": 1,
  "amount": 500,
  "amount_discount": 0,
  "amount_shipping": 0,
  "amount_interest": 0,
  "amount_total": 500,
  "customer": {
    "hash": "customerhash123",
    "name": "Fulano da Silva",
    "email": "email@example.com",
    "document": "00000000000",
    "document_type": "cpf",
    "phone_coutry_code": "55",
    "phone_number": "0000000000",
    "country": "br",
    "zip_code": "00000000",
    "street_name": "Rua Exemplo",
    "number": "123",
    "complement": null,
    "neighborhood": "Bairro Exemplo",
    "city": "Cidade Exemplo",
    "state": "SP",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "created_at": "2025-06-05T00:00:00.000000Z",
    "updated_at": "2025-06-09T00:00:00.000000Z",
    "antifraud_validated": 0,
    "last_ip": null
  },
  "pix": {
    "pix_url": null,
    "pix_qr_code": "00020126...<código fictício>...6304XXXX",
    "pix_base64": null
  },
  "billet": null,
  "src": "origem",
  "utm_source": "campanha",
  "utm_campaign": "teste",
  "utm_content": "conteudo",
  "utm_term": "termo",
  "utm_medium": "meio",
  "postback_url": "https://example.com/webhook",
  "paid_at": null,
  "created_at": "2025-06-09 00:00:00",
  "updated_at": "2025-06-10 00:00:00",
  "products": [
    {
      "hash": "producthash123",
      "custom_options": null,
      "price": 500,
      "quantity": 1,
      "operation_type": 1,
      "created_at": "2025-06-09T00:00:00.000000Z",
      "updated_at": "2025-06-09T00:00:00.000000Z",
      "title": "Produto Exemplo"
    }
  ],
  "gateway": {
    "hash": "gatewayhash123",
    "identifier": "GatewayExemplo"
  },
  "link_checkout": null,
  "tracking_code": null,
  "coupon": []
}

📋 Campos da Resposta

hash: Identificador único da transação

payment_status: Status atual do pagamento

amount_total: Valor total da transação

customer: Dados completos do cliente

pix: Dados específicos do PIX (QR Code, etc.)

products: Lista de produtos da transação

POSTReembolsar Transação

/public/v1/payments/:id/refund

Realiza o reembolso de uma transação já paga. O ID da transação deve ser enviado na URL.

⚠️ Importante

Apenas transações com status paid podem ser reembolsadas.

Resposta de Sucesso

{
  "message": "Transação reembolsada com sucesso",
  "transaction": {
    "id": "example123",
    "hash": "example123",
    "payment_method": "credit_card",
    "payment_status": "refunded",
    "amount_total": 500,
    "refunded_at": "2025-06-10T14:30:00.000000Z"
  }
}

Resposta de Erro (Status 400)

{
  "message": "Não foi possível reembolsar a transação",
  "transaction": {
    "id": "example123",
    "hash": "example123",
    "payment_status": "waiting_payment"
  }
}