Com o Pluggy Payments, você pode facilmente criar links de pagamento para cobrar seus clientes e rastrear automaticamente seus pagamentos, aproveitando integrações OAuth seguras com instituições que utilizam a infraestrutura de Iniciação de Pagamentos do Open Finance.
Você também pode realizar Pagamentos Agendados, que podem ser usados para coisas como cobrança mensal pré-acordada.
Nossa solução de Pagamentos lida com três conceitos principais:
- Destinatário do Pagamento: uma conta bancária que recebe pagamentos
- Solicitação de Pagamento: um pedido para pagar um determinado valor a um destinatário. Ele possui um link de pagamento que você pode enviar ao seu cliente para efetuar o pagamento.
- Intenção de Pagamento: uma tentativa de pagar uma Solicitação de Pagamento. É criada quando seu cliente clica em "Pagar" em nosso site de pagamento.
Recurso apenas por convite
Este recurso está em beta e deve ser habilitado especificamente para seu cliente. Se você estiver interessado em experimentá-lo, entre em contato com nossa equipe de Vendas!
Fluxo de exemplo#
- Primeiro, criamos um Destinatário do Pagamento para indicar qual conta bancária receberá o pagamento (você só precisará fazer isso uma vez por conta).
{
"taxNumber": "11111111111", // CPF ou CNPJ
"name": "John Doe",
"paymentInstitutionId": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
"account": {
"branch": "0001",
"number": "123456",
"type": "CHECKING_ACCOUNT"
}
}Resposta
{
"type": "BANK_ACCOUNT",
"id": "36fcb10f-825c-1111-b67c-93d0e47f4e77",
"name": "John Doe",
"taxNumber": "11111111111",
"isDefault": false,
"paymentInstitution": {
"id": "37f43fff-30cb-4cb5-8213-6662ac08a8c6",
"name": "SWAP MEIOS DE PAGAMENTOS INSTITUICAO DE PAGAMENTO S.A.",
"tradeName": "SWAP MP IP SA",
"ispb": "31680151",
"compe": null,
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "*******",
"number": "****56",
"branch": "0001"
},
"pixKey": null,
"createdAt": "2025-06-25T14:09:44.717Z",
"updatedAt": "2025-06-25T14:09:44.717Z"
}Nota: você pode obter os IDs das instituições neste endpoint.
- Crie uma Solicitação de Pagamento com o valor que deseja cobrar de seu cliente, juntamente com o ID do destinatário da etapa anterior.
{
"amount": 0.01,
"description": "Meu pedido de pagamento",
"recipientId": "ab276a3d-17ba-47eb-97bf-688475037ffe"
}Resposta
{
"id": "bb236f8d-caa5-47eb-97bf-688475037f3e",
"amount": 0.01,
"description": "Meu pedido de pagamento",
"status": "CREATED",
"createdAt": "2023-11-14T16:57:17.511Z",
"updatedAt": "2023-11-14T16:57:17.511Z",
"callbackUrls": null,
"paymentUrl": "https://pay.pluggy.ai/bb236f8d-caa5-47eb-97bf-688475037f3e"
}-
Envie o
paymentUrlda resposta para seu cliente. -
O cliente visitará nosso site Pluggy Pagamentos.
Reagindo a um pagamento#
Você pode indicar para onde redirecionar o usuário após ele concluir um pagamento usando o campo callbackUrls:
{
"amount": 0.01,
"description": "Transferência",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com",
"pending": "https://my-pending-url.com"
}
}Também é possível reagir a um pagamento concluído para criar automações úteis, usando webhooks.
Pré-preenchendo o CPF/CNPJ#
O CPF/CNPJ do pagador é exigido pelo Open Finance para iniciar um pagamento. Para PF, é necessário CPF, e para PJ, são ambos CPF e CNPJ. Para melhorar a experiência de pagamento e reduzir erros do usuário, você pode pré-preencher criando um Cliente de Pagamento:
Solicitação — PF
{
"type": "INDIVIDUAL",
"cpf": "123.456.789-12"
}Solicitação — PJ
{
"type": "BUSINESS",
"cpf": "123.456.789-12",
"cnpj": "12.345.678/9012-34"
}Agora, ao criar a Solicitação de Pagamento, inclua o campo customerId apontando para o Cliente de Pagamento criado anteriormente.
Pré-selecionando a instituição do pagador#
Você pode definir uma instituição pré-selecionada para o pagador ao iniciar o fluxo de iniciação de pagamento. Isso pode ser útil se você quiser guiar o usuário a usar uma instituição específica para efetuar o pagamento. Para fazer isso, você pode criar o cliente de pagamento fornecendo um connectorId:
{
"type": "INDIVIDUAL",
"cpf": "123.456.789-12",
"connectorId": 612
}Envolvendo um QR PIX existente#
Se você quiser usar o Pluggy para pagar um QR PIX para permitir o rastreamento de seu pagamento, pode criar um Destinatário a partir do QR PIX:
{
"pixQrCode": "00020126490014br.gov.bcb.pix0108dict-key0215additional-info52040000530398654031005802BR5912example-name6006Cidade62090505tx-id63045E20"
}Criando uma experiência de pagamento personalizada#
Se você não quiser usar nosso fluxo pay.pluggy.ai, pode implementar sua experiência de pagamento personalizada usando nossa API.
Primeiramente, você precisa criar uma Solicitação de Pagamento. Lá, você especificará quanto dinheiro deseja receber. Além disso, você pode configurar uma descrição (a ser exibida ao usuário final no momento em que ele autoriza o pagamento) e um conjunto de URLs de callback para onde o usuário será redirecionado após a autorização do pagamento ser concluída. Os campos description, callbackUrl e isSandbox são opcionais.
{
"amount": 100.50,
"description": "Transferência",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com",
"pending": "https://my-pending-url.com"
},
"isSandbox": true
}Resposta
{
"id": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"amount": 100.50,
"description": "Transferência",
"status": "CREATED",
"createdAt": "2023-11-06T13:03:45.689Z",
"updatedAt": "2023-11-06T13:03:45.689Z",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com"
},
"isSandbox": true
}Você pode encontrar os detalhes do endpoint aqui.
Criando uma Intenção de Pagamento#
Após criar uma solicitação de pagamento, você precisa criar uma Intenção de Pagamento. Isso representa a intenção de uma pessoa de fazer aquele pagamento. Por exemplo, se você quiser cobrar um cliente R$10, primeiro precisa criar uma Solicitação de Pagamento para esse valor e, em seguida, uma Intenção de Pagamento quando o usuário quiser pagar.
Para criar uma Intenção de Pagamento, você precisa enviar o ID da instituição (connectorId) que o usuário usará para efetuar o pagamento. Você pode encontrar a lista de conectores usando nosso endpoint de conectores e filtrar aqueles com a propriedade supportsPaymentInitiation com valor true. Além disso, você precisa enviar as credenciais exigidas da instituição no campo parameters. Essas credenciais também podem ser encontradas no endpoint de conectores.
Esta é a solicitação para criar uma Intenção de Pagamento.
Solicitação — Conector Pessoal
{
"paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"connectorId": 601,
"parameters": {
"cpf": "76109277673"
}
}Solicitação — Conector Empresarial
{
"paymentRequestId": "05c693bf-c196-47ea-a28c-8251d6bb8a06",
"connectorId": 618,
"parameters": {
"cpf": "76109277673",
"cnpj": "11111111111111"
}
}Resposta
{
"id": "4316602b-8fb5-4bfd-92dc-32921b7414f1",
"status": "CONSENT_AWAITING_AUTHORIZATION",
"createdAt": "2023-11-09T20:10:42.706Z",
"updatedAt": "2023-11-09T20:10:42.706Z",
"paymentRequest": {
"id": "f6696d02-3583-47ae-b195-148d71b8ae9b",
"amount": 100.50,
"description": null,
"status": "IN_PROGRESS",
"createdAt": "2023-11-09T20:10:25.084Z",
"updatedAt": "2023-11-09T20:10:42.706Z",
"callbackUrls": {
"success": "https://my-success-url.com",
"error": "https://my-error-url.com"
}
},
"connector": {
"id": 601,
"name": "Itaú",
"primaryColor": "48be9d",
"institutionUrl": "https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
"validationMessage": "CPF deve ter 11 números.",
"label": "CPF",
"name": "cpf",
"type": "number",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/itau.svg",
"hasMFA": false,
"oauth": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"IDENTITY",
"CREDIT_CARDS",
"PAYMENT_DATA",
"LOANS",
"INVESTMENTS"
],
"createdAt": "2023-07-24T14:29:32.140Z",
"isSandbox": true,
"isOpenFinance": true,
"updatedAt": "2023-11-09T19:17:08.495Z",
"supportsPaymentInitiation": true
},
"consentUrl": "https://consent-url.com"
}Existem propriedades importantes no objeto de resposta:
- status: Neste ponto, terá o valor
CONSENT_AWAITING_AUTHORIZATION. Isso significa que o usuário precisa autorizá-lo na instituição. Você pode verificar os outros valores possíveis aqui. - consentUrl: É a URL para onde você precisa redirecionar o usuário a fim de autorizar o pagamento (ela expira após 5 minutos). Após a conclusão do pagamento, o usuário será redirecionado para as URLs especificadas nos
callbackUrlsdefinidos anteriormente, ou para uma URL padrão fornecida pelo Pluggy se não tiver sido especificada.
Você pode encontrar os detalhes do endpoint aqui.
Testando pagamentos com o banco Sandbox#
Você pode usar nosso aplicativo de testes playground para testar o fluxo sem nenhuma configuração!
Usando sandbox sem playground
Para testar pagamentos Sandbox em nosso App, basta criar sua Solicitação de Pagamento com
isSandbox: true. Em seguida, acesse:
https://pay.pluggy.ai/<PAYMENT_REQUEST_ID>A página detectará automaticamente o ambiente sandbox e listará apenas conectores sandbox para você completar o fluxo. Use o conector Sandbox com as seguintes credenciais:
{
"cpf": "76109277673",
"user": "ralph.bragg@gmail.com",
"password": "P@ssword01"
}Use a credencial CPF na primeira entrada. Use user e password para fazer login no Mock Bank, e ele será redirecionado para a Página de Sucesso ou de Erro, dependendo do resultado do Pagamento.