Conn2Flow
Docs
Navegação das docs

Referência / Bibliotecas

Biblioteca paypal.php

Cliente da API REST do PayPal: credenciais pelo .env ou pelo gateway, token OAuth com cache, pedidos, reembolsos, catálogo, planos, assinaturas, faturas, payouts, disputas e webhook.

Caminho no Gestor bibliotecas/paypal.php

Chamadas diretas à API REST do PayPal (api-m.paypal.com em produção, api-m.sandbox.paypal.com em sandbox), sem SDK. A versão registrada é 3.1.0 (paypal_info()).

Credenciais: dois modos

Modo De onde vêm as credenciais Onde o token OAuth é guardado
padrão .env: PAYPAL_MODE (sandbox/live), PAYPAL_CLIENT_ID, PAYPAL_SECRET, PAYPAL_WEBHOOK_ID Variáveis do módulo admin-environment (paypal-access-token…)
gateway Registro paypal da tabela gateways_pagamentos Colunas access_token, token_expires_at e token_data do próprio gateway

PAYPAL_DEFAULT (padrao ou gateway) escolhe o modo de paypal_auto_configurar(). Para um gateway específico: paypal_gateways_pagamentos_configurar(['id' => 7]). O .env só preenche as credenciais do ambiente de PAYPAL_MODE.

paypal_autenticar() reaproveita o token em $_GESTOR['paypal-token'] enquanto faltarem mais de 5 minutos para vencer, e pede outro (client_credentials) quando não. ['force_refresh' => true] força. No modo gateway, uma falha de autenticação marca o gateway como desconectado (paypal_gateway_atualizar_conexao()), e cada transação pode somar às estatísticas dele (paypal_gateway_registrar_transacao()).

Requisição

paypal_requisicao(['endpoint', 'method', 'data', 'headers', 'auth_basic', 'access_token']) devolve ['http_code', 'data', 'raw'] ou false. Como no Stripe, erro da API não é false: confira http_code. Erros vão para gestor/logs/paypal-<data>.log.

Operações

Área Funções
Pedidos (Orders v2) paypal_criar_pedido(), paypal_capturar_pedido(), paypal_consultar_pedido(), paypal_processar_pagamento_transparente(), paypal_gerar_client_token() e paypal_validar_payment_source() (cartão direto na página)
Reembolsos paypal_reembolsar(), paypal_consultar_reembolso()
Catálogo e planos paypal_criar_produto(), paypal_listar_produtos(), paypal_consultar_produto(), paypal_atualizar_produto(); paypal_criar_plano(), paypal_listar_planos(), paypal_consultar_plano(), paypal_ativar_plano(), paypal_desativar_plano(), paypal_atualizar_precos_plano()
Assinaturas paypal_criar_assinatura(), paypal_consultar_assinatura(), paypal_suspender_assinatura(), paypal_ativar_assinatura(), paypal_cancelar_assinatura(), paypal_capturar_assinatura(), paypal_listar_transacoes_assinatura()
Faturas (Invoicing v2) paypal_criar_fatura(), paypal_listar_faturas(), paypal_buscar_faturas(), paypal_consultar_fatura(), paypal_enviar_fatura(), paypal_lembrete_fatura(), paypal_cancelar_fatura(), paypal_deletar_fatura(), paypal_registrar_pagamento_fatura(), paypal_registrar_reembolso_fatura(), paypal_gerar_qrcode_fatura(), paypal_gerar_numero_fatura()
Payouts paypal_criar_payout(), paypal_consultar_payout(), paypal_consultar_item_payout(), paypal_cancelar_item_payout()
Links de pagamento paypal_gerar_link_pagamento(), paypal_verificar_link_pagamento()
Disputas paypal_listar_disputas(), paypal_consultar_disputa(), paypal_aceitar_disputa(), paypal_contestar_disputa(), paypal_mensagem_disputa(), paypal_escalar_disputa()
Relatórios paypal_listar_transacoes(), paypal_consultar_saldo()
Conferências paypal_pedido_pago(), paypal_assinatura_ativa(), paypal_fatura_paga()

Webhook

paypal_validar_webhook(['headers' => getallheaders(), 'body' => $corpoCru]) pede ao próprio PayPal a verificação da assinatura (verify-webhook-signature, com o PAYPAL_WEBHOOK_ID) e só aceita verification_status = SUCCESS. paypal_processar_webhook(['body' => …, 'callback' => …]) decodifica o evento e chama o callback; ele não valida, então chame antes o paypal_validar_webhook().

O endpoint /_gateways/paypal/webhook (controlador plataforma-gateways) valida e dispara o hook paypal.webhook; há também as rotas de retorno e cancelamento do checkout.

Utilitários e armadilhas

  • paypal_formatar_valor(), paypal_traduzir_status() (para português), paypal_gerar_id(), paypal_validar_email() e paypal_log_registro().

  • paypal_formatar_data() gera AAAA-MM-DDTHH:MM:SSZ com date(), que usa o fuso do servidor: o Z (UTC) só é verdadeiro se o PHP estiver em UTC. O Gestor não define fuso horário.

  • paypal_calcular_taxa($valor, 'nacional'|'internacional') usa taxas fixas no código (4,99% + 0,60 e 5,99% + 0,60), que não acompanham a tabela real do PayPal. Serve só como estimativa.

  • O admin-environment usa a biblioteca para testar as credenciais.

Auxiliares internos: paypal_gateway_persistir_token(), paypal_is_modo_gateway(), paypal_obter_gateway_id(), paypal_obter_gateway_dados(), paypal_padrao_persistir_token(), paypal_padrao_restaurar_token(), paypal_obter_url_api(), paypal_obter_credenciais().

Funções

Gerado a partir de gestor/bibliotecas/paypal.php · 78 funções

78 de 78

paypal_gateway_persistir_token

ver no código · linha 169 ↗
paypal_gateway_persistir_token(array $token_data): bool

Persiste o token OAuth no banco de dados do gateway ativo.

Parâmetros

$token_dataarray
Dados do token (access_token, token_type, expires_at, etc)

Retorno

bool
True se persistido, false se não está em modo gateway

paypal_gateway_atualizar_conexao

ver no código · linha 242 ↗
paypal_gateway_atualizar_conexao(bool $sucesso, string $mensagem = ''): bool

Atualiza o status de conexão do gateway ativo.

Parâmetros

$sucessobool
Se a conexão foi bem-sucedida
$mensagemstring
Mensagem descritiva do resultado

Retorno

bool
True se atualizado, false se não está em modo gateway

paypal_padrao_persistir_token

ver no código · linha 313 ↗
paypal_padrao_persistir_token(array $token_data): bool

Persiste o token OAuth nas variáveis do sistema (modo padrão).

Parâmetros

$token_dataarray
Dados do token (access_token, token_type, expires_at, etc)

Retorno

bool
True se persistido com sucesso

paypal_requisicao

ver no código · linha 484 ↗
paypal_requisicao(array|false $params = false): array|false

Realiza requisição HTTP para a API do PayPal.

Parâmetros

$paramsarray|false
Parâmetros da requisição

Retorno

array|false
Array com resposta ou false em erro

paypal_autenticar

ver no código · linha 600 ↗
paypal_autenticar(array|false $params = false): array|false

Autentica com PayPal e obtém access token OAuth 2.0.

Parâmetros

$paramsarray|false
Parâmetros da função (opcional)

Retorno

array|false
return['expires_at'] Timestamp de expiração

paypal_gerar_client_token

ver no código · linha 673 ↗
paypal_gerar_client_token(array|false $params = false): string|false

Gera o client token usado pelos Card Fields/Hosted Fields no navegador.

Parâmetros

$paramsarray|false
Parâmetros opcionais

Retorno

string|false
Client token ou false em erro

paypal_validar_payment_source

ver no código · linha 731 ↗
paypal_validar_payment_source(mixed $payment_source): bool

Valida a estrutura mínima de uma fonte de pagamento aceita neste fluxo.

Parâmetros

$payment_sourcemixed
Fonte de pagamento recebida pelo backend

Retorno

bool
True para payment_source.card ou payment_source.token não vazios

paypal_criar_pedido

ver no código · linha 770 ↗
paypal_criar_pedido(array|false $params = false): array|false

Cria um pedido (order) no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
return['approve_url'] URL para aprovação do pedido

paypal_capturar_pedido

ver no código · linha 944 ↗
paypal_capturar_pedido(array|false $params = false): array|false

Captura um pedido (order) aprovado no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
return['capture_data'] Dados completos da captura

paypal_reembolsar

ver no código · linha 1181 ↗
paypal_reembolsar(array|false $params = false): array|false

Processa reembolso de uma captura no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
return['status'] Status do reembolso

paypal_criar_produto

ver no código · linha 1482 ↗
paypal_criar_produto(array|false $params = false): array|false

Cria um produto no catálogo do PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com dados do produto ou false em erro

paypal_listar_produtos

ver no código · linha 1559 ↗
paypal_listar_produtos(array|false $params = false): array|false

Lista produtos do catálogo do PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com lista de produtos ou false em erro

paypal_criar_plano

ver no código · linha 1759 ↗
paypal_criar_plano(array|false $params = false): array|false

Cria um plano de assinatura no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com dados do plano ou false em erro

paypal_listar_planos

ver no código · linha 1881 ↗
paypal_listar_planos(array|false $params = false): array|false

Lista planos de assinatura do PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com lista de planos ou false em erro

paypal_capturar_assinatura

ver no código · linha 2465 ↗
paypal_capturar_assinatura(array|false $params = false): array|false

Captura pagamento autorizado de uma assinatura no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com dados da captura ou false em erro

paypal_criar_payout

ver no código · linha 3430 ↗
paypal_criar_payout(array|false $params = false): array|false

Cria um payout (pagamento em lote) no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com dados do payout ou false em erro

paypal_cancelar_item_payout

ver no código · linha 3642 ↗
paypal_cancelar_item_payout(array|false $params = false): array|false

Cancela um item de payout não reclamado no PayPal.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com dados do item cancelado ou false em erro

paypal_aceitar_disputa

ver no código · linha 3870 ↗
paypal_aceitar_disputa(array|false $params = false): array|false

Aceita reclamação e faz reembolso ao comprador.

Parâmetros

$paramsarray|false
Parâmetros da função

Retorno

array|false
Array com resultado ou false em erro

paypal_formatar_valor

ver no código · linha 4242 ↗
paypal_formatar_valor(float $valor, string $moeda = 'BRL'): string

Formata valor monetário para exibição.

Parâmetros

$valorfloat
Valor numérico
$moedastring
Código da moeda (padrão: BRL)

Retorno

string
Valor formatado

paypal_traduzir_status

ver no código · linha 4269 ↗
paypal_traduzir_status(string $status, string $tipo = 'order'): string

Traduz status do PayPal para português.

Parâmetros

$statusstring
Status em inglês
$tipostring
Tipo: order, subscription, invoice, dispute, payout

Retorno

string
Status traduzido

paypal_calcular_taxa

ver no código · linha 4405 ↗
paypal_calcular_taxa(float $valor, string $tipo = 'nacional'): array

Calcula taxa do PayPal para um valor.

Parâmetros

$valorfloat
Valor da transação
$tipostring
Tipo: nacional, internacional

Retorno

array
Array com valor líquido e taxa estimada

paypal_formatar_data

ver no código · linha 4463 ↗
paypal_formatar_data(string|int $data, bool $incluir_hora = true): string

Converte data para formato PayPal.

Parâmetros

$datastring|int
Data (timestamp ou string)
$incluir_horabool
Incluir hora no formato

Retorno

string
Data formatada

Verificado contra o código no commit ea442bea

Fontes:

O Futuro é Híbrido: Humano + IA.

O Conn2Flow é a ferramenta. Se você precisa do Arquiteto para desenhar a estratégia da sua empresa usando essa tecnologia...

Contrate Consultoria Especializada