Integração da API RiskPayGo

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 de compra correta 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/plugin

Autenticaçã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_ID

Essas 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.

Como funciona a seleção de finalização da compra

A RiskPayGo utiliza dois processos de finalização de compra diferentes, dependendo do país do comprador:

  • Se o país enviou cliente.país é NÓS o QUEO comprador será direcionado para a página de finalização da compra dos EUA/Canadá.
  • Se o país for outro, o comprador será redirecionado para a página de finalização de compra internacional.

Você não precisa preencher um campo adicional para selecionar manualmente a opção de finalização da compra. A seleção é feita automaticamente usando o valor de cliente.país.

Por isso, é importante que o país do comprador seja inserido corretamente em cada pedido.

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/create

Nesse pedido, você deve enviar as principais informações do pedido: o valor, a moeda, suas referências internas, os dados básicos 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.

Atualmente, no bloco cliente Você só precisa enviar estas informações do comprador:

  • primeiro nome: nome
  • sobrenomesobrenomes
  • e-mail: e-mail
  • país: país

Não é mais necessário enviar telefone em data_de_nascimento.

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",
    "country": "US"
  },
  "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"
}

Observe o seguinte:

  • O campo quantia deve ser maior que zero.
  • A moeda é enviada em moeda.
  • Em cliente É obrigatório enviar primeiro nome, sobrenome, e-mail e país.
  • O valor de cliente.país É esse que determina qual página de finalização de compra será exibida para o comprador.
  • Em site.url Você deve enviar um domínio que já tenha sido aprovado anteriormente em sua conta.
  • Em notify_url Você especifica a URL onde deseja receber a confirmação do status do pagamento.

Exemplos de comportamento por país

Se você estiver enviando de um país fora dos EUA/Canadá:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "John",
    "last_name": "Smith",
    "country": "US"
  }
}

O comprador será direcionado para a página de finalização da compra dos EUA/Canadá.

Se você enviar de um país diferente:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Carlos",
    "last_name": "García",
    "country": "ES"
  }
}

O comprador será direcionado para a página de finalização da compra internacional.

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.

Mesmo que a finalização da compra seja selecionada com base no país do comprador, o fluxo para sua integração é o mesmo: você deve sempre usar o URL de finalização de compra retornado pela API.

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.

A abordagem recomendada é seguir este fluxo:

  1. Crie o pagamento a partir do seu painel administrativo.
  2. Salve a referência referência_de_pagamento no seu sistema.
  3. Redirecione o comprador para URL de finalização de compra.
  4. 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 sempre 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: <firma_base64_hmac_sha256>

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 é que:

  • Primeiro, valide a assinatura.
  • Em seguida, verifique o valor de status.
  • E, por fim, atualize o pedido em seu sistema com esse status.

Você não deve marcar um pedido como pago apenas porque o usuário retornou ao site ou acessou a página de sucesso. A principal fonte de informação deve ser o webhook.

Status de pagamento

Durante a integração, você deve considerar quatro estados principais:

  • pendenteO pagamento foi iniciado, mas ainda não foi confirmado.
  • pagoO pagamento foi confirmado com sucesso. Este é o status que você normalmente deve usar para marcar o pedido como pago.
  • fracassadoO pagamento falhou ou foi rejeitado.
  • canceladoO 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 retornar um erro de autorização, verifique os seguintes pontos:

  • Que o valor enviado em Autorização estar correto.
  • Que o valor enviado em X-RPG-Merchant corresponda a esse token.
  • Que a conta do comerciante esteja aprovada e 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.

País incorreto ou finalização de compra inesperada

Se o comprador se deparar com uma página de finalização de compra diferente da esperada, verifique o valor enviado. cliente.país.

  • Se você enviar NÓS o QUEO sistema de finalização de compra dos EUA/Canadá será utilizado.
  • Se o envio for para outro país, será utilizado o sistema de pagamento internacional.

Um valor de país incorreto pode fazer com que o comprador seja direcionado para a página de finalização de compra errada.

Valor inválido

Se a API rejeitar o valor, certifique-se de que quantia Foi enviado corretamente e possui um valor maior que zero.

Informações incompletas do comprador

Se a solicitação falhar devido a dados do cliente, verifique se em cliente Você deve enviar pelo menos estes campos:

first_name
last_name
email
country

Lembre-se disso telefone e data_de_nascimento Eles não são mais necessários nesta integração.

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.

Usando o 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_SECRET

A URL do webhook no WordPress geralmente tem este formato:

https://tu-dominio.com/wp-json/riskpaygo/v1/webhook

Se o fluxo do plugin usar o país do comprador para gerar o pagamento, a seleção entre finalização de compra nos EUA/Canadá e finalização de compra internacional seguirá a mesma lógica descrita acima.

Recomendações finais

Antes de iniciar a produção, é aconselhável verificar todos os seguintes itens:

  • Que o domínio enviou em site.url Está aprovado no RiskPayGo.
  • Que você notify_url Responde corretamente via HTTPS.
  • Que guardas referência_de_pagamento Em seu sistema, para que seja possível vincular o pagamento ao pedido.
  • Que você envie corretamente cliente.paísPorque esse valor determina qual opção de finalização de compra será exibida para o comprador.
  • Você só marca os pedidos como pagos quando a confirmação final chega via webhook. status = pago.

Com essa estrutura, você já possui uma base clara e segura para integrar o RiskPayGo ao seu próprio site, a um aplicativo personalizado ou a uma loja WooCommerce.

Voltar ao topo