Plataformas de Bet
Para plataformas de apostas que usarão o PIX como método de pagamento, a integração geralmente consistirá em 5 etapas:
- Solicitar um endpoint de depósito
- Solicitar um endpoint de saque
- Receber um webhook de depósito bem-sucedido
- Receber um webhook de saque bem-sucedido
- Receber um webhook de falha de saque
Abaixo, encontre uma explicação detalhada de cada etapa.
Trabalhando com os Depósitos
O endpoint de depósitos é o que será usado para solicitar um código QR para o pagamento PIX. Você pode utilizar este endpoint conforme descrito nos detalhes da solicitação seguindo este link.
Este é o fluxo de trabalho esperado para os depósitos:
sequenceDiagram
autonumber
actor Customer
Customer ->> Plataformas de Bet: Solicita um depósito para
Plataformas de Bet ->> Gateway: [POST] /api/pix/cash_in
alt Compliance / Problema com Chave Pix
rect rgba(0, 0, 255, .1)
Gateway ->> Plataformas de Bet: Retorno de erro 422
Plataformas de Bet ->> Customer: Exibir mensagem de erro
end
else Sucesso
Gateway ->> Banco parceiro: Solicita o código QR
Banco parceiro ->> Gateway: Retorna o código QR
Gateway ->> Plataformas de Bet: Retorna o código QR
Plataformas de Bet ->> Customer: Exibe o código QR
Customer -->> Banco parceiro: Realiza o pagamento PIX
Banco parceiro ->> Gateway: Retorna a confirmação de pagamento
Gateway ->> Plataformas de Bet: [Webhook] Depósito bem-sucedido
Plataformas de Bet ->> Customer: Credita a conta do cliente
endNo Passo 2, ao fazer uma solicitação para o endpoint [POST] /api/pix/cash_in você receberá um erro 422 se o cliente não estiver em conformidade ou se a chave PIX não for válida. Nesse caso, você deve mostrar uma mensagem de erro ao cliente. Essa transação não será processada e será marcada com um status de falha do nosso lado.
Se tudo estiver correto, o gateway solicitará o código QR ao parceiro bancário e o retornará para a plataforma de apostas. A plataforma de apostas mostrará o código QR ao cliente (Passos 5 a 8).
No Passo 9, o cliente fará o pagamento PIX e o banco parceiro retornará a confirmação do pagamento para o gateway. O gateway então enviará um webhook de depósito bem-sucedido para a plataforma de apostas. A plataforma de apostas então creditará a conta do cliente com o valor do depósito.
Importante
A conta do usuário deve ser creditada apenas após receber o webhook de depósito bem-sucedido. Esta é a única maneira de garantir que o pagamento foi processado e a conta do cliente deve ser creditada.
Trabalhando com os Saques
O endpoint de saques é aquele que será usado para solicitar um saque da plataforma de apostas para a conta bancária do cliente. Você pode usar este endpoint conforme descrito nos detalhes da solicitação seguindo este link.
Este é o fluxo de trabalho esperado para os saques:
sequenceDiagram
autonumber
actor Customer
Customer ->> Plataformas de Bet: Solicita um saque para
Plataformas de Bet ->> Gateway: [POST] /api/pix/cash_out
alt Compliance / Problema de saldo
rect rgba(0, 0, 255, .1)
Gateway ->> Plataformas de Bet: Retorna um erro 422
Plataformas de Bet->> Customer: Exibir mensagem de erro
end
else Sucesso
Gateway ->> Banco parceiro: Solicita o saque
Banco parceiro ->> Gateway: Confirmação da solicitação de saque
Gateway ->> Plataformas de Bet: Confirmação da solicitação de saque
Plataformas de Bet ->> Customer: Bloqueia o valor desejado para saque
alt Falha bancária
rect rgba(0, 0, 255, .1)
Banco parceiro -->> Gateway: Retorna a falha do saque
Gateway ->> Plataformas de Bet: [Webhook] Reembolso
Plataformas de Bet ->> Customer: Reembolsa o valor bloqueado
end
else Sucesso
Banco parceiro -->> Gateway: Retorna a confirmação do pagamento
Gateway ->> Plataformas de Bet: [Webhook] Saque bem-sucedido
Plataformas de Bet ->> Customer: Realiza o saque do valor bloqueado
end
endNo Passo 2, ao fazer uma solicitação para o endpoint [POST] /api/pix/cash_out você receberá um erro 422 se o cliente não estiver em conformidade ou se sua conta estiver sem fundos. Nesse caso, você deve mostrar uma mensagem de erro ao cliente. Essa transação não será processada e será marcada com um status de falha em nosso lado.
Se tudo estiver correto, o gateway solicitará o saque ao parceiro bancário e retornará a confirmação da solicitação de saque para a plataforma de apostas. Neste ponto, recomendamos que a plataforma de apostas bloqueie o valor desejado para saque na conta do cliente (Passos 5 a 8).
Nos Passos 12 a 14, o parceiro bancário retornará a confirmação do pagamento para o gateway. O gateway então enviará um webhook de saque bem-sucedido para a plataforma de apostas. A plataforma de apostas então irá retirar o valor bloqueado da conta do cliente.
Importante
A conta do usuário deve ser debitada (para o caso de sucesso) ou reembolsada (para falha no saque) apenas após receber os webhooks correspondentes. Esta é a única maneira de garantir a consistência do pagamento entre nosso gateway e sua plataforma.
Webhooks
Nossos webhooks são a forma como nos comunicamos com sua plataforma. Eles são acionados para cada evento relacionado a uma transação e podem ser habilitados ou desabilitados em nossa plataforma. Cada evento pode apontar para um endpoint diferente em sua aplicação. As solicitações de webhook são enviadas como uma solicitação POST com um payload JSON.
Nossa plataforma considera um webhook bem-sucedido se receber um código de status 2xx da sua plataforma no endpoint especificado. Quando uma chamada de webhook falha, faremos três tentativas com uma estratégia de espera exponencial (10, 100 e 1000 segundos de diferença entre cada nova tentativa).
Os webhooks que serão acionados para as plataformas de apostas são:
| Evento de Transação | Descrição |
|---|---|
capture |
Depósito bem-sucedido: Acionado quando um depósito é bem-sucedido |
transfer |
Saque bem-sucedido: Acionado quando um saque é bem-sucedido |
refund |
Saque sem sucesso: Acionado quando um saque não é bem-sucedido |
captura, o webhook de depósito bem-sucedido
Sempre que um código QR PIX é gerado e pago com sucesso, nosso sistema enviará um webhook POST no seguinte formato:
{
"event": "capture",
"transaction": {
"created_at": "2022-02-02T21:34:07+0000",
"document_number": "****067****",
"e2e_id": "e00500002120220200000048r0xxv9wwww0l",
"email": "foo.bar@mail.net",
"error": null,
"events": [
{
"amount": "1.00",
"created_at": "2022-02-02T21:36:03+0000",
"event_type": "capture",
"id": "123-456-789",
"pix_key_type": null,
"pix_key_value": null,
"pix_message": null,
"qrcode": null,
"qrcode_image": null,
"success": true,
"updated_at": "2022-02-02T21:36:03+0000"
},
{
"amount": "1.00",
"created_at": "2022-02-02T21:34:07+0000",
"event_type": "auth",
"id": "123-456-789",
"pix_key_type": null,
"pix_key_value": null,
"pix_message": null,
"processor_code": "1",
"processor_message": "pending",
"processor_transaction_id": "123-456-789",
"qrcode": "COPYPASTEPIXCODE",
"qrcode_image": "data:image/png;base64,123123456546789789",
"success": true,
"updated_at": "2022-02-02T21:34:10+0000"
}
],
"first_name": "Foo",
"id": "123-456-789",
"last_name": "Bar",
"merchant_id": "123-456-789",
"merchant_transaction_id": "0000001",
"processor_id": "123-456-789",
"statement": {
"acc_info": {
"acc_number": "1122333",
"acc_type": "checking",
"bank_agency": "0001",
"bank_code": "33333",
"document": "***067***",
"ispb": "12312311",
"name": "Foo Bar"
},
"amount": "100.00",
"created_at": "2022-02-02T17:48:27.000000Z",
"date": "2022-02-02 17:48:26",
"e2e_id": "e10573521202202121748r0xxv9anj0l"
},
"transaction_type": "pix",
"updated_at": "2022-02-02T21:36:03+0000",
"user_id": "123-456-789"
}
}
Para mais detalhes, você pode verificar a página do Webhook de Captura.
transferência, o webhook de saque bem-sucedido
{
"event": "transfer",
"transaction": {
"created_at": "2022-02-02T21:34:07+0000",
"e2e_id": "e0000400202020404040kswkks020202",
"email": "foo.bar@mail.net",
"error": null,
"events": [
{
"amount": "1.00",
"created_at": "2022-02-02T21:36:03+0000",
"event_type": "transfer",
"id": "321-654-987",
"pix_key_type": null,
"pix_key_value": null,
"pix_message": null,
"qrcode": null,
"qrcode_image": null,
"success": true,
"updated_at": "2022-02-02T21:36:03+0000"
},
{
"amount": "1.00",
"created_at": "2022-02-02T21:34:07+0000",
"event_type": "payment",
"id": "123-456-789",
"pix_key_type": "email",
"pix_key_value": "email@server.com",
"pix_message": "This is NOT a test",
"processor_code": "1",
"processor_message": "pending",
"processor_transaction_id": "123-456-789",
"qrcode": null,
"qrcode_image": null,
"success": true,
"updated_at": "2022-02-02T21:34:10+0000"
}
],
"first_name": "Foo",
"flow_type": "cashout",
"id": "123-456-789",
"last_name": "Bar",
"merchant_id": "123-456-789",
"merchant_transaction_id": "0000001",
"processor_id": "123-456-789",
"statement": {
"acc_info": {
"acc_number": "112233",
"acc_type": "checking",
"bank_agency": "00001",
"bank_code": "888",
"document": "****232****",
"ispb": "123321",
"name": "Foo Bar"
},
"amount": "450.00",
"created_at": "2022-02-12T18:00:42.000000Z",
"date": "2022-02-12 18:00:35",
"e2e_id": "e0000400202020404040kswkks020202"
},
"status": "success",
"transaction_type": "pix",
"updated_at": "2022-02-02T21:36:03+0000",
"user_id": "123-456-789"
}
}
Para mais detalhes, você pode conferir a página de Webhook de Transferência.
reembolso, o webhook de falha de saque
Sempre que um saque não for bem-sucedido por motivos bancários, ocorrendo um saque mal-sucedido, nosso sistema enviará um webhook POST no seguinte formato:
{
"event": "refund",
"transaction": {
"created_at": "2022-02-02T21:34:07+0000",
"document_number": "****435****",
"e2e_id": null,
"email": "foo.bar@mail.net",
"error": {
"code": 4,
"message": "The transfer was rejected by the receiving bank",
"meta": [],
"type": "ERROR_BANK_CASH_OUT"
},
"events": [
{
"amount": "1.00",
"created_at": "2022-02-02T21:36:03+0000",
"event_type": "refund",
"id": "321-654-987",
"pix_key_type": null,
"pix_key_value": null,
"pix_message": null,
"qrcode": null,
"qrcode_image": null,
"success": true,
"updated_at": "2022-02-02T21:36:03+0000"
},
{
"amount": "1.00",
"created_at": "2022-02-02T21:34:07+0000",
"event_type": "payment",
"id": "123-456-789",
"pix_key_type": "email",
"pix_key_value": "email@server.com",
"pix_message": "This is NOT a test",
"processor_code": "1",
"processor_message": "pending",
"processor_transaction_id": "123-456-789",
"qrcode": null,
"qrcode_image": null,
"success": false,
"updated_at": "2022-02-02T21:34:10+0000"
}
],
"first_name": "Foo",
"flow_type": "cashout",
"id": "123-456-789",
"last_name": "Bar",
"merchant_id": "123-456-789",
"merchant_transaction_id": "0000001",
"processor_id": "123-456-789",
"statement": null,
"status": "failed",
"transaction_type": "pix",
"updated_at": "2022-02-02T21:36:03+0000",
"user_id": "123-456-789"
}
}
Para mais detalhes, você pode conferir a página de Webhook de Reembolso.