Pix inteligente

Sweeping Accounts V2 - Payment Initiation PIX API

Visão Geral

A API de Sweeping Accounts V2 - Payment Initiation PIX permite a criação de pagamentos PIX recorrentes associados a um consentimento de sweeping accounts previamente autorizado. Este endpoint é utilizado para realizar transferências automáticas de fundos conforme os limites e configurações estabelecidos no consentimento.

Características Principais

Pagamentos Recorrentes: Permite criar pagamentos PIX associados a um consentimento de sweeping accounts autorizado
Validação de Consentimento: Verifica se o consentimento está autorizado antes de criar o pagamento
Sinais de Risco: Suporta coleta de sinais de risco manuais e automáticos
Idempotência: Utiliza chave de idempotência para evitar duplicação de pagamentos
Limites Configuráveis: Respeita os limites configurados no consentimento (por transação, totais e periódicos)

Endpoint

POST /open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation/{paymentInitiationId}/payments

Onde {paymentInitiationId} é o identificador único do payment initiation retornado na criação do consentimento.

Autenticação

A API requer autenticação OAuth2 com a seguinte permissão:

app: Para integrações diretas via API

O token de acesso deve ser enviado no header:

Authorization: Bearer {access_token}

Estrutura da Requisição

Payload Completo

{
    "data": {
        "date": "2025-01-15",
        "payment": {
            "amount": "150.00",
            "currency": "BRL"
        },
        "creditorAccount": {
            "accountType": "CACC",
            "ispb": "12345678",
            "issuer": "1774",
            "number": "1234567890"
        },
        "remittanceInformation": "Pagamento da nota XPTO035-002.",
        "ibgeTownCode": "5300108",
        "riskSignals": {
            "manual": {
                "deviceId": "00000000-54b3-e7c7-0000-000046bffd97",
                "isRootedDevice": false,
                "screenBrightness": 128,
                "elapsedTimeSinceBoot": 3600000,
                "osVersion": "Android 12",
                "userTimeZoneOffset": "-03:00",
                "language": "pt-BR",
                "screenDimensions": {
                    "height": 1920,
                    "width": 1080
                },
                "accountTenure": "2020-01-01",
                "geolocation": {
                    "latitude": -15.7942,
                    "longitude": -47.8822,
                    "type": "FINE"
                },
                "isCallInProgress": false,
                "isDevModeEnabled": false,
                "isMockGPS": false,
                "isEmulated": false,
                "isMonkeyRunner": false,
                "isCharging": true,
                "antennaInformation": "BRASILIA",
                "isUsbConnected": false,
                "integrity": {
                    "appRecognitionVerdict": "PLAY_RECOGNIZED",
                    "deviceRecognitionVerdict": "MEETS_STRONG_INTEGRITY"
                }
            }
        }
    }
}

Campos da Requisição

Nível Raiz

Campo	Tipo	Obrigatório	Descrição
`data`	Object	Sim	Objeto contendo os dados do pagamento PIX

Objeto `data`

Campo	Tipo	Obrigatório	Descrição
`date`	String	Sim	Data em que o pagamento será realizado (formato: YYYY-MM-DD)
`payment`	Object	Sim	Informações do pagamento
`creditorAccount`	Object	Não	Dados da conta do recebedor
`remittanceInformation`	String	Não	Informações adicionais do pagamento (máximo 140 caracteres)
`ibgeTownCode`	String	Não	Código IBGE do município (7 dígitos)
`riskSignals`	Object	Sim	Sinais de risco para iniciação de pagamentos automáticos

Objeto `payment`

Campo	Tipo	Obrigatório	Descrição
`amount`	String	Sim	Valor da transação com 2 casas decimais (formato: "XXXXX.XX")
`currency`	String	Sim	Código da moeda segundo ISO-4217 (valor fixo: "BRL")

Objeto `creditorAccount`

Campo	Tipo	Obrigatório	Descrição
`accountType`	Enum	Sim	Tipo de conta: `CACC` (Corrente), `SVGS` (Poupança), `TRAN` (Pagamento pré-paga)
`ispb`	String	Sim	ISPB do participante do SPI (8 dígitos)
`issuer`	String	Condicional	Código da agência sem dígito (obrigatório para CACC e SVGS)
`number`	String	Sim	Número da conta com dígito verificador (máximo 20 caracteres)

Objeto `riskSignals`

Campo	Tipo	Obrigatório	Descrição
`manual`	Object	Condicional	Sinais de risco com presença do usuário (obrigatório quando transação ocorre na presença do usuário)
`automatic`	Object	Condicional	Sinais de risco sem presença do usuário (obrigatório quando transação não ocorre na presença do usuário)

Objeto `manual`

Campo	Tipo	Obrigatório	Descrição
`deviceId`	String	Sim	ID único do dispositivo gerado pela plataforma
`isRootedDevice`	Boolean	Sim	Indica se o dispositivo está com permissão de 'root'
`screenBrightness`	Number	Sim	Nível de brilho da tela (Android: 0-255, iOS: 0.0-1.0)
`elapsedTimeSinceBoot`	Number	Sim	Tempo desde a inicialização do dispositivo (milissegundos)
`osVersion`	String	Sim	Versão do sistema operacional
`userTimeZoneOffset`	String	Sim	Fuso horário do dispositivo (formato UTC offset: ±hh[:mm])
`language`	String	Sim	Idioma do dispositivo (formato ISO 639-1)
`screenDimensions`	Object	Sim	Dimensões da tela do dispositivo
`accountTenure`	String	Sim	Data de cadastro do cliente na iniciadora (YYYY-MM-DD)
`geolocation`	Object	Não	Dados de geolocalização do cliente
`isCallInProgress`	Boolean	Não	Indica chamada ativa no momento do vínculo
`isDevModeEnabled`	Boolean	Não	Indica se o dispositivo está em modo de desenvolvedor
`isMockGPS`	Boolean	Não	Indica se o dispositivo está usando GPS falso
`isEmulated`	Boolean	Não	Indica se o dispositivo é emulado ou real
`isMonkeyRunner`	Boolean	Não	Indica o uso do MonkeyRunner
`isCharging`	Boolean	Não	Indica se a bateria do dispositivo está sendo carregada
`antennaInformation`	String	Não	Indica em qual antena o dispositivo está conectado
`isUsbConnected`	Boolean	Não	Indica se o dispositivo está conectado via USB
`integrity`	Object	Não	Informa a integridade do dispositivo e app

Objeto `screenDimensions`

Campo	Tipo	Obrigatório	Descrição
`height`	Number	Sim	Altura da tela, em pixels
`width`	Number	Sim	Largura da tela, em pixels

Objeto `geolocation`

Campo	Tipo	Obrigatório	Descrição
`latitude`	Number	Não	Coordenada latitudinal do cliente
`longitude`	Number	Não	Coordenada longitudinal do cliente
`type`	Enum	Não	Tipo de mecanismo: `COARSE`, `FINE`, `INFERRED`

Objeto `integrity`

Campo	Tipo	Obrigatório	Descrição
`appRecognitionVerdict`	String	Não	Informa a integridade do app
`deviceRecognitionVerdict`	String	Não	Informa a integridade do dispositivo

Objeto `automatic`

Campo	Tipo	Obrigatório	Descrição
`lastLoginDateTime`	String	Sim	Data e hora do último login do cliente na iniciadora (RFC-3339)
`pixKeyRegistrationDateTime`	String	Condicional	Data e hora de cadastro da chave Pix do recebedor (obrigatório se localInstrument for DICT ou INIC)

Formato de Valores Monetários

Todos os valores monetários devem seguir o formato:

Padrão: ^((\d{1,16}.\d{2}))$
Exemplo: "150.00", "100000.12", "25.50"
Mínimo: 4 caracteres (ex: "0.01")
Máximo: 19 caracteres

Formato de Datas

As datas devem seguir os seguintes padrões:

Campo date: YYYY-MM-DD (exemplo: "2025-01-15")
Campo accountTenure: YYYY-MM-DD (exemplo: "2020-01-01")
Campo lastLoginDateTime: RFC-3339 (exemplo: "2025-12-03T17:49:26.626Z")
Campo pixKeyRegistrationDateTime: RFC-3339 (exemplo: "2025-12-03T17:49:26.626Z")

Validações Importantes

Payment Initiation ID: O paymentInitiationId informado na URL deve existir e pertencer à aplicação autenticada
Status do Consentimento: O consentimento associado deve estar no status AUTHORISED
Limites do Consentimento: O valor do pagamento deve respeitar os limites configurados no consentimento:
- Limite por transação (transactionLimit)
- Limite total (totalAllowedAmount)
- Limites periódicos (diário, semanal, mensal, anual)
Sinais de Risco: Deve ser enviado ao menos um dos objetos (manual ou automatic):
- manual: Obrigatório quando a transação ocorre na presença do usuário
- automatic: Obrigatório quando a transação não ocorre na presença do usuário
Creditor Account: Se informado, deve conter todos os campos obrigatórios conforme o tipo de conta
IBGE Town Code: Deve conter exatamente 7 dígitos numéricos

Implementação

Fluxo de Criação de Pagamento PIX

O sistema valida o paymentInitiationId e verifica se pertence à aplicação autenticada
Busca o payment initiation e o consentimento associado
Valida que o consentimento está no status AUTHORISED
Valida que a sessão de jornada está no status AUTHORISED
Gera um endToEndId único para o pagamento
Cria o registro do pagamento na base de dados
Envia a requisição para a detentora de conta criar o pagamento recorrente
Atualiza o registro do pagamento com a resposta da detentora
Atualiza o consentimento na detentora de conta
Dispara webhook para a aplicação
Retorna o payment initiation atualizado com o pagamento criado

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation/{paymentInitiationId}/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
        "date": "2025-01-15",
        "payment": {
            "amount": "150.00",
            "currency": "BRL"
        },
        "creditorAccount": {
            "accountType": "CACC",
            "ispb": "12345678",
            "issuer": "1774",
            "number": "1234567890"
        },
        "remittanceInformation": "Pagamento da nota XPTO035-002.",
        "ibgeTownCode": "5300108",
        "riskSignals": {
            "manual": {
                "deviceId": "00000000-54b3-e7c7-0000-000046bffd97",
                "isRootedDevice": false,
                "screenBrightness": 128,
                "elapsedTimeSinceBoot": 3600000,
                "osVersion": "Android 12",
                "userTimeZoneOffset": "-03:00",
                "language": "pt-BR",
                "screenDimensions": {
                    "height": 1920,
                    "width": 1080
                },
                "accountTenure": "2020-01-01"
            }
        }
    }
}'

Exemplo de Requisição (JavaScript/Node.js)

const axios = require("axios");

const createSweepingAccountsPixPayment = async (paymentInitiationId) => {
    try {
        const response = await axios.post(
            `https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation/${paymentInitiationId}/payments`,
            {
                data: {
                    date: "2025-01-15",
                    payment: {
                        amount: "150.00",
                        currency: "BRL",
                    },
                    creditorAccount: {
                        accountType: "CACC",
                        ispb: "12345678",
                        issuer: "1774",
                        number: "1234567890",
                    },
                    remittanceInformation: "Pagamento da nota XPTO035-002.",
                    ibgeTownCode: "5300108",
                    riskSignals: {
                        manual: {
                            deviceId: "00000000-54b3-e7c7-0000-000046bffd97",
                            isRootedDevice: false,
                            screenBrightness: 128,
                            elapsedTimeSinceBoot: 3600000,
                            osVersion: "Android 12",
                            userTimeZoneOffset: "-03:00",
                            language: "pt-BR",
                            screenDimensions: {
                                height: 1920,
                                width: 1080,
                            },
                            accountTenure: "2020-01-01",
                        },
                    },
                },
            },
            {
                headers: {
                    Authorization: "Bearer YOUR_ACCESS_TOKEN",
                    "Content-Type": "application/json",
                },
            },
        );

        console.log("Pagamento PIX criado:", response.data);
        return response.data;
    } catch (error) {
        console.error(
            "Erro ao criar pagamento PIX:",
            error.response?.data || error.message,
        );
        throw error;
    }
};

createSweepingAccountsPixPayment("uuid-do-payment-initiation");

Exemplo de Requisição (Python)

import requests

def create_sweeping_accounts_pix_payment(payment_initiation_id):
    url = f"https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation/{payment_initiation_id}/payments"

    headers = {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    }

    payload = {
        "data": {
            "date": "2025-01-15",
            "payment": {
                "amount": "150.00",
                "currency": "BRL"
            },
            "creditorAccount": {
                "accountType": "CACC",
                "ispb": "12345678",
                "issuer": "1774",
                "number": "1234567890"
            },
            "remittanceInformation": "Pagamento da nota XPTO035-002.",
            "ibgeTownCode": "5300108",
            "riskSignals": {
                "manual": {
                    "deviceId": "00000000-54b3-e7c7-0000-000046bffd97",
                    "isRootedDevice": False,
                    "screenBrightness": 128,
                    "elapsedTimeSinceBoot": 3600000,
                    "osVersion": "Android 12",
                    "userTimeZoneOffset": "-03:00",
                    "language": "pt-BR",
                    "screenDimensions": {
                        "height": 1920,
                        "width": 1080
                    },
                    "accountTenure": "2020-01-01"
                }
            }
        }
    }

    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()

    return response.json()

result = create_sweeping_accounts_pix_payment("uuid-do-payment-initiation")
print("Pagamento PIX criado:", result)

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo o payment initiation atualizado com o pagamento criado:

{
    "id": "uuid-do-payment-initiation",
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "data": {
        // ... dados originais do consentimento
    },
    "journeySessionId": "uuid-da-journey-session",
    "applicationId": "uuid-da-aplicacao",
    "paymentInitiationApi": "SWEEPING_ACCOUNTS_V2",
    "ofConsentId": "id-do-consentimento-na-detentora",
    "ofConsent": {
        "status": "AUTHORISED",
        // ... outros dados do consentimento
    },
    "ofPayments": [
        {
            "recurringPaymentId": "id-do-pagamento-na-detentora",
            "endToEndId": "E12345678202501151200ABC12345678",
            "date": "2025-01-15",
            "payment": {
                "amount": "150.00",
                "currency": "BRL"
            },
            "status": "PENDING",
            // ... outros dados do pagamento
        }
    ],
    "status": "AUTHORISED",
    "createdAt": 1234567890,
    "updatedAt": 1234567890
}

Campos Importantes da Resposta

Campo	Tipo	Descrição
`id`	String	Identificador único do payment initiation
`ofConsent`	Object	Objeto contendo o estado atual do consentimento
`ofConsent.status`	String	Status do consentimento (geralmente `AUTHORISED`)
`ofPayments`	Array	Lista de pagamentos associados ao consentimento
`ofPayments[].recurringPaymentId`	String	ID do pagamento recorrente na detentora de conta
`ofPayments[].endToEndId`	String	Identificador end-to-end do pagamento PIX
`ofPayments[].status`	String	Status atual do pagamento

Erros Comuns

400 Bad Request

{
    "error": "Validation Error",
    "message": "Campo 'amount' é obrigatório"
}

Causas comuns:

Campos obrigatórios ausentes
Formato de dados inválido (datas, valores monetários)
Validação de schema falhou

401 Unauthorized

{
    "error": "Unauthorized",
    "message": "Token inválido ou expirado"
}

Solução: Verifique se o token de acesso é válido e possui a permissão app.

403 Forbidden

{
    "error": "Forbidden",
    "message": "cannot create itp for journey session with status: PENDING"
}

Solução: O consentimento deve estar autorizado (AUTHORISED) antes de criar pagamentos. Verifique o status do consentimento antes de tentar criar o pagamento.

404 Not Found

{
    "error": "Not Found",
    "message": "Payment initiation não encontrado"
}

Solução: Verifique se o paymentInitiationId informado na URL existe e pertence à aplicação autenticada.

422 Unprocessable Entity

{
    "error": "Unprocessable Entity",
    "message": "Payment amount exceeds transaction limit"
}

Solução: O valor do pagamento excede os limites configurados no consentimento. Verifique os limites e ajuste o valor do pagamento.

Boas Práticas

Validação de Consentimento: Sempre verifique se o consentimento está autorizado antes de criar pagamentos
Validação de Limites: Verifique se o valor do pagamento respeita os limites configurados no consentimento
Sinais de Risco: Envie sempre os sinais de risco apropriados (manual ou automatic) conforme o contexto da transação
Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
Segurança: Nunca exponha tokens de acesso no frontend ou logs
Idempotência: O sistema gera automaticamente uma chave de idempotência para evitar duplicação de pagamentos
Datas: Use sempre o formato correto para datas (YYYY-MM-DD para o campo date)
Valores Monetários: Valide o formato antes de enviar (mínimo 4 caracteres, máximo 19)

Limites e Restrições

Payment Initiation ID: Deve existir e pertencer à aplicação autenticada
Status do Consentimento: Deve estar em AUTHORISED
Valores Monetários: Formato XXXXX.XX (mínimo 4, máximo 19 caracteres)
Datas: Formato YYYY-MM-DD para o campo date
Remittance Information: Máximo 140 caracteres
IBGE Town Code: Exatamente 7 dígitos numéricos
Sinais de Risco: Ao menos um objeto (manual ou automatic) deve ser enviado

Updated 15 days ago