Documentação API PradaPay

PRODUÇÃO: https://api.pradapay.com

Autenticação

BODY JSON

As requisições do gateway enviam a API Key no corpo JSON, no campo api-key:

{
    "api-key": "sua_chave_aqui"
}

Respostas reais do gateway

Formato de sucesso

{
    "status": "success",
    "message": "ok",
    "idTransaction": "ID_DA_TRANSACAO",
    "flowType": "qrcode"
}
Campo Quando aparece Descrição
paymentCode Pix Código copia e cola do Pix
paymentCodeBase64 Pix QR Code em Base64
paymentUrl Fluxo redirect URL externa para continuação do pagamento
retorno_cartao Cartão Status retornado pela adquirente
barcode Boleto Linha digitável
pdf_url Boleto Link do boleto em PDF

Formato de erro

{
    "status": "error",
    "message": "Campo obrigatório ausente: client.userPhone"
}

Possíveis mensagens de erro do gateway:

Observação: em rejeições específicas da adquirente, o gateway pode repassar a resposta bruta do provedor para preservar o motivo do erro.
  • JSON inválido na solicitação.
  • Falha na solicitação: dados incompletos.
  • Campo obrigatório ausente: client, amount, card ou campos internos.
  • E-mail do cliente inválido.
  • Documento ou telefone do cliente inválido.
  • Recaptcha inválido.
  • Forma de pagamento não autorizada.
  • Moeda inválida.
  • Forma de pagamento desabilitada para o cliente.
  • Combinação de moeda/método de entrada não habilitada para este cliente.
  • Chave da API inválida.
  • Erro ao solicitar à API secundária.
  • Erro interno ao processar a solicitação.

Pagamento via Pix

POST https://api.pradapay.com/v1/gateway/

Cria uma nova transação Pix

Parâmetros

Parâmetro Tipo Descrição
requestNumber String ID único da transação
amount Decimal Valor da transação
client Object Dados do cliente

Request

{
    "id_produto": [222], //Opcional array
    "requestNumber": "12356",
    "amount": 1.50,
    "frete_valor": 0,   //Opcional
    "frete_nome": "",   //Opcional
    "quantidade": [1],  //Opcional array
    "api-key": "SUA_CHAVE",
    "postback": "https://seusite.com/callback", // Opcional
    "client": {
        "name": "João Silva",
        "document": "999.999.999-99",
        "email": "[email protected]",
        "userPhone": "(99) 99999-9999",
        "cep": "99999999",  //Opcional
        "estado": "SP", //Opcional
        "cidade": "São Paulo",  //Opcional
        "bairro": "Centro", //Opcional
        "rua": "Rua josé fernandes",  //Opcional
        "numeroEnd": "123", //Opcional
        "complemento": "AP 01"  //Opcional
    }
}

Response

{
    "status": "success",
    "message": "ok",
    "flowType": "qrcode",
    "paymentCode": "000201010212267...",
    "idTransaction": "52fc5262-4063-4900...",
    "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
}

Pagamento via Cartão

POST https://api.pradapay.com/v1/gateway/

Processa pagamento com cartão de crédito

Request

{
    "id_produto": [222], //Opcional array
    "requestNumber": "12356",
    "amount": 1.50,
    "frete_valor": 0,   //Opcional
    "frete_nome": "",   //Opcional
    "quantidade": [1],  //Opcional array
    "forma_pagamento": "cartao",
    "parcela": 1,
    "api-key": "SUA_CHAVE",
    "postback": "https://seusite.com/callback", // Opcional
    "client": {
        "name": "João Silva",
        "document": "999.999.999-99",
        "email": "[email protected]",
        "userPhone": "(99) 99999-9999",
        "cep": "99999999",  //Opcional
        "estado": "SP", //Opcional
        "cidade": "São Paulo",  //Opcional
        "bairro": "Centro", //Opcional
        "rua": "Rua josé fernandes",  //Opcional
        "numeroEnd": "123", //Opcional
        "complemento": "AP 01"  //Opcional
    },
    "card": {
        "nome": "João Silva",
        "numero": "4111111111111111",
        "mes": "12",
        "ano": "26",
        "cvv": "123"
    }
}

Response

{
    "idTransaction": "ORDE_1A0406EF...",
    "message": "ok",
    "status": "success",
    "flowType": "redirect",
    "paymentUrl": "https://checkout-adquirente.exemplo/pagamento",
    "retorno_cartao": "PAID"
}

Pagamento via Boleto

POST https://api.pradapay.com/v1/gateway/

Processa pagamento via boleto bancário

Request

{
    "id_produto": [222], //Opcional array
    "requestNumber": "12356",
    "amount": 1,
    "quantidade": [1], //Opcional array
    "frete_valor": 0, //Opcional
    "frete_nome": "", //Opcional
    "utm_content": "",
    "utm_medium": "",
    "utm_campaign": "",
    "utm_source": "",
    "utm_term": "",
    "forma_pagamento": "boleto",
    "api-key": "SUA_CHAVE",
    "postback": "https://seusite.com/callback", // Opcional
    "client": {
        "name": "joao silva",
        "document": "046.213.680-95",
        "email": "[email protected]",
        "userPhone": "(12) 31231-2313",
        "cep": "99999999",
        "estado": "SP",
        "cidade": "São Paulo",
        "bairro": "Centro",
        "rua": "Rua josé fernandes",
        "numeroEnd": "123",
        "complemento": "AP 01"
    }
}

Response

{
    "idTransaction": "CHAR_4CAA3F04-6C6E-4E00-BAFB-8377DDEDBDD3",
    "message": "ok",
    "status": "success",
    "flowType": "redirect",
    "barcode": "03399853012970000024227020901016278150000015630",
    "pdf_url": "https://example.com/fc6c8e8e-884a-439f-acfc-7fe42a631172.pdf"
}

Webhooks

POST https://api.pradapay.com/v1/webhook/

Endpoint para verificação de status de pagamento

Request

{
    "idtransaction": "81bb141a-1746-49a8..."
}

Response

{
    "status": "PAID_OUT"
}

Cashout

POST https://api.pradapay.com/c1/cashout/

Solicitação de saque

Request

{
    "api-key": "SUA_CHAVE",
    "name": "Adm",
    "cpf": "70291669232",
    "keypix": "7029132323",
    "amount": 410.95,
    "postback": "https://seusite.com/callback",
    "nonce": "a1b2c3d4e5f6g7h8" // Deve ser único para cada requisição
}

Response

{
    "amount": "409.95",
    "idTransaction": "CHAR_4CAA3F04-6C6E-4E00-BAFB-8377DDEDBDD3",
    "reference": "ref_1234",
    "status": "pago"
}
                        
{
    "amount": "409.95",
    "idTransaction": "CHAR_4CAA3F04-6C6E-4E00-BAFB-8377DDEDBDD3",
    "reference": "ref_1234",
    "status": "refunded"
}

Split de Pagamento

O split permite distribuir parte do valor de uma transação para outros usuários da plataforma. Pode ser utilizado em qualquer forma de pagamento (Pix, Cartão ou Boleto) adicionando o campo split ao corpo da requisição.

Importante: O campo user deve ser o identificador do usuário destinatário cadastrado na PradaPay. A soma dos splits não pode ultrapassar 95% do valor da transação e deve ser de no mínimo 1%. O usuário destinatário não pode ser o mesmo que o remetente.

Campo split (opcional)

Parâmetro Tipo Descrição
split Array Lista de destinatários do split (opcional)
split[].user String Identificador do usuário destinatário (deve existir na plataforma)
split[].porcentagem String (numérico) Percentual do valor da transação a ser repassado (ex: "10.00", "5"). Aceita até 2 casas decimais.

Exemplo de Request com Split (Pix)

{
    "requestNumber": "REQ_UNICO_123",
    "amount": 20,
    "api-key": "SUA_CHAVE",
    "postback": "https://seusite.com/callback",
    "client": {
        "name": "Nome do Cliente",
        "userPhone": "+5511999999999",
        "email": "[email protected]",
        "document": "999.999.999-99"
    },
    "split": [
        {
            "user": "USER_ID_DESTINO_A",
            "porcentagem": "1"
        },
        {
            "user": "USER_ID_DESTINO_B",
            "porcentagem": "30"
        }
    ]
}

Regras

  • A soma de todos os percentuais de split deve representar entre 1% e 95% do amount.
  • Entradas com percentual inválido ou usuário inexistente são silenciosamente ignoradas.
  • O saldo repassado via split é deduzido do saldo líquido do remetente após aprovação da transação.
  • O campo split é compatível com Pix, Cartão e Boleto.

Response (sucesso — igual ao método de pagamento utilizado)

{
    "status": "success",
    "message": "ok",
    "flowType": "qrcode",
    "paymentCode": "000201010212267...",
    "idTransaction": "52fc5262-4063-4900...",
    "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUg..."
}

Response (erro de split inválido)

{
    "status": "error",
    "message": "Valor de split inválido. Não pode ultrapassar 95% do valor da compra e deve ser no mínimo 1%."
}

FAQs

Como receber notificações de pagamento?

Configure o URL do callback no momento da requisição.

Onde encontrar a API Key?

A chave está disponível no painel administrativo do PradaPay.

Quais os status possíveis?

  • PAID_OUT: Pagamento concluído
  • WAITING_FOR_APPROVAL: Pagamento pendente
  • DECLINED: Pagamento recusado