Esta documentação explica como integrar o RiskPayGo ao seu site ou aplicativo para criar pagamentos, redirecionar o comprador para a página de finalização da compra e receber a confirmação final do status via webhook.
A integração deve ser feita a partir do seu backend. Não é recomendável expor credenciais ou lógica sensível no frontend.
Antes de começarmos
Antes de começar, você precisa de uma conta comercial aprovada e ativa com a RiskPayGo. Você também precisa das suas credenciais de integração e garantir que o domínio do qual você coletará pagamentos esteja aprovado em sua conta.
Os dados de que você precisará são seus ID do comerciante, você Token da API, você Segredo do Webhook e a URL base da API.
A URL base é a seguinte:
https://riskpaygo.com/portal/api/pluginAutenticação
Todas as requisições à API devem ser autenticadas. Para isso, você precisa incluir o token privado no cabeçalho. Autorização e o identificador do comerciante no cabeçalho X-RPG-Merchant.
Os cabeçalhos necessários são os seguintes:
Accept: application/json
Content-Type: application/json
Authorization: Bearer TU_API_TOKEN
X-RPG-Merchant: TU_MERCHANT_IDEssas credenciais devem ser usadas apenas no servidor. Elas não devem ser visíveis no JavaScript do navegador ou em código público.
Domínio aprovado
O RiskPayGo valida o domínio que você envia no campo. site.urlIsso significa que ter credenciais válidas não é suficiente: o domínio a partir do qual você está criando o pagamento também deve estar registrado e aprovado em sua conta.
Se o domínio não corresponder a nenhum dos seus projetos aprovados, a API rejeitará a solicitação, mesmo que o token esteja correto.
Portanto, antes de iniciar a produção, é aconselhável verificar se o URL exato da sua loja ou aplicativo está registrado no painel.
Criar um pagamento
Para iniciar um pagamento, você precisa enviar uma solicitação. PUBLICAR para o ponto de extremidade de criação de pagamento.
POST https://riskpaygo.com/portal/api/plugin/payments/createNesse pedido, você deve enviar as principais informações do pedido: o valor, a moeda, suas referências internas, os dados do comprador e os URLs de devolução e notificação.
Uma solicitação típica incluirá campos como: id_do_pedido_do_comerciante, id_do_pedido, chave_de_ordem, quantia, moeda, cliente, site, notify_url, URL de retorno e url_de_cancelamento.
Abaixo segue um exemplo completo do corpo da mensagem que você pode enviar:
{
"merchant_order_id": "PED-1001",
"order_id": 1001,
"order_key": "pedido_1001_key",
"amount": "149.99",
"currency": "USD",
"customer": {
"email": "cliente@ejemplo.com",
"first_name": "Nombre",
"last_name": "Apellido",
"phone": "+34123456789",
"country": "ES",
"date_of_birth": "1990-05-20"
},
"site": {
"url": "https://tu-dominio.com/",
"name": "Mi tienda",
"platform": "custom",
"plugin": "integracion-propia"
},
"notify_url": "https://tu-dominio.com/api/riskpaygo/webhook",
"return_url": "https://tu-dominio.com/pago/completado",
"cancel_url": "https://tu-dominio.com/pago/cancelado"
}O campo quantia Deve ser maior que zero. A moeda é enviada em moeda. Em cliente É recomendável enviar, pelo menos, o endereço de e-mail do comprador. site.url Você deve enviar o domínio aprovado. notify_url Você indica onde deseja receber a notificação sobre o status do pagamento.
Resposta da API
Se a solicitação for bem-sucedida, o RiskPayGo retorna uma resposta com a referência de pagamento interna e o URL de finalização da compra. Essa referência permite que você vincule o pagamento ao seu pedido e o acompanhe posteriormente.
A resposta esperada tem a seguinte forma:
{
"success": true,
"data": {
"payment_ref": "RPG-20260313-ABC12345",
"checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260313-ABC12345",
"fee_percent": 20,
"plan_slug": "free"
}
}Assim que você receber URL de finalização de compraVocê deve redirecionar o comprador para esse endereço para que ele possa concluir o pagamento.
O que fazer em relação ao caixa
O pagamento é processado através de um sistema de finalização de compra hospedado pela RiskPayGo. Seu sistema não deve considerar o pedido como pago simplesmente porque você obteve o URL da finalização da compra ou porque o usuário retornou ao site.
Recomenda-se salvar a referência. referência_de_pagamentoRedirecione o comprador e aguarde a confirmação final via webhook.
O URL de retorno Serve para redirecionar o usuário ao seu site após o pagamento, mas o status final deve ser baseado na notificação que você recebe em notify_url.
Webhook de confirmação
Quando o status do pagamento mudar, o RiskPayGo enviará uma solicitação. PUBLICAR para o URL indicado em notify_urlEssa notificação inclui uma assinatura no topo. Assinatura X-RPG.
Você deve validar essa assinatura usando o seu Segredo do WebhookA validação deve ser feita no corpo original exato da solicitação, não em um JSON reserializado.
O cabeçalho que você precisa verificar é este:
X-RPG-Signature:A notificação do RiskPayGo pode incluir informações como o nome do comerciante, a referência do pedido, a referência do pagamento, o status e o ID da transação. Um exemplo seria este:
{
"merchant_id": "TU_MERCHANT_ID",
"order_id": 1001,
"order_key": "pedido_1001_key",
"payment_ref": "RPG-20260313-ABC12345",
"transaction_id": "RPG-20260313-ABC12345",
"status": "paid",
"provider_status": "success",
"provider_event": "payment_succeeded",
"source": "payera_webhook"
}O importante aqui é validar a assinatura e depois usar o valor de status Para atualizar o pedido em seu sistema.
Status de pagamento
Durante a integração, você deve considerar quatro estados principais.
pendente Isso indica que o pagamento foi iniciado, mas ainda não foi confirmado.
pago Isso indica que o pagamento foi confirmado com sucesso. Normalmente, esse é o status que você deve usar para marcar o pedido como pago.
fracassado Indica que o pagamento falhou ou foi rejeitado.
cancelado Indica que o pagamento foi cancelado ou expirou.
A recomendação geral é usar o webhook como fonte primária de informações e considerar o pedido pago somente após o recebimento. status = pago.
Erros comuns
Comerciante não autorizado
Se a API responder com um erro de autorização, a primeira coisa que você deve verificar é se o valor enviado em Autorização estar correto e que o comerciante enviou em X-RPG-Merchant O token deve corresponder. Você também precisa confirmar se a conta foi aprovada e está ativa.
Domínio não aprovado
Se o problema estiver no domínio, verifique o valor enviado. site.url e verifique se o domínio existe como um projeto aprovado no painel RiskPayGo.
Valor inválido
Se a API rejeitar o valor, certifique-se de que quantia Foi enviado corretamente e possui um valor maior que zero.
Assinatura de webhook inválida
Se o seu sistema não conseguir validar a notificação, verifique se você está usando o Segredo do Webhook Correto e que o cálculo da assinatura seja feito exatamente no corpo original da solicitação.
Compatível com WooCommerce
Se você estiver usando o plugin oficial do WooCommerce, os mesmos detalhes de integração ainda serão necessários. Você precisará configurar a URL base, o comerciante, o token e o segredo do webhook.
Os principais valores a serem inseridos são estes:
API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRETA URL do webhook no WordPress geralmente tem este formato:
https://tu-dominio.com/wp-json/riskpaygo/v1/webhookRecomendações finais
Antes de iniciar a produção, é aconselhável verificar se o domínio está aprovado e se o seu notify_url Ele responde corretamente via HTTPS, o que você salva. referência_de_pagamento em seu sistema e que você só marque os pedidos como pagos quando a confirmação final chegar via webhook.
Com essa estrutura, você já possui uma base sólida para integrar o RiskPayGo ao seu próprio site, a um aplicativo personalizado ou a uma loja WooCommerce.