You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

Generic Pay Connector

O Generic Pay Connector da Twilio permite que você aceite pagamentos com segurança por telefone por meio de autoatendimento (com o verbo <Pay>) ou assistência de agente sem precisar se tornar compatível com PCI. Ao contrário dos outros Pay Connectors da marca Twilio, o Generic Pay Connector permite que você se conecte ao processador de pagamento de sua escolha.

O Generic Pay Connector atua como uma ponte entre você e o processador de pagamento. Seu processador de pagamento é responsável por processar a transação e relatar o resultado à Twilio.

Você deve usar o Generic Pay Connector da Twilio se o processador de pagamento de sua escolha não estiver incluído na lista de Pay Connectors de marca da Twilio (Stripe, CardConnect, Base Commerce, Chase Paymentech ou Braintree).

Esta página mostrará:

  • como o Generic Pay Connector funciona com a Twilio e seu processador de pagamento para lidar com transações de pagamento
  • como configurar um Generic Pay Connector para receber pagamentos
  • a forma dos objetos de solicitação e resposta esperados pela Twilio ao se comunicar com seu processador de pagamento

Arquitetura do Generic Pay Connector

Screen Shot 2022-03-28 at 3.04.53 PM.png

Se um Generic Pay Connector estiver instalado e configurado com um processador de pagamento, o fluxo de informações gerais ao coletar informações de pagamento é o seguinte:

  1. Uma chamada é estabelecida com seu número de telefone da Twilio e seu cliente.
  2. A Twilio executa um verbo <Pay>. O cliente ouvirá solicitações para inserir o número do cartão de crédito, data de validade, CEP e CVV. (Como alternativa, um agente do call center pode coletar detalhes de pagamento usando o Agent Assist.)
  3. A Twilio passa essas informações de pagamento para o seu Generic Pay Connector.
  4. O Generic Pay Connector passa as informações de pagamento para seu processador de pagamento especificado usando uma solicitação HTTPS POST.
  5. O processador de pagamento facilita a transação de pagamento real e passa o resultado da transação de volta para o Generic Pay Connector.
  6. A Twilio envia essas informações como uma solicitação HTTP para o URL de ação especificada no verbo <Pay> (ou para o URL statusCallback se estiver usando a API Payments)


O Generic Pay Connector só passa informações para o seu processador de pagamento. O processamento real da transação pelo processador de pagamento está fora do escopo do Generic Pay Connector.

Nota sobre processadores de pagamento em comparação a gateways de pagamento

Um processador de pagamento executa a transação transmitindo dados entre você, o comerciante; o banco emissor (ou seja, o banco que emitiu o cartão de crédito do seu cliente); e o banco adquirente (ou seja, seu banco).


Um gateway de pagamento é uma ferramenta que transmite com segurança os dados de pagamento online ao processador para continuar o ciclo de vida da transação. Um gateway de pagamento também comunica a aprovação ou recusa ao estabelecimento ou ao cliente.

Instalar e configurar um Generic Pay Connector

Esta seção descreve os pré‐requisitos para usar um Generic Pay Connector e como instalar e configurar um Generic Pay Connector.

Pré‐requisitos

Comprar um número de telefone da Twilio habilitado para o Voice

Se você ainda não possui um número de telefone habilitado para Twilio Voice, conclua as etapas a seguir:

  1. No Twilio Console, navegue até a página Buy a Number (Comprar um número).
  2. Certifique‐se de que a caixa de seleção "Voice" (Voz) esteja marcada e clique no botão Search (Pesquisar).
  3. Você verá uma lista de números de telefone disponíveis e seus recursos. Escolha um número e clique no botão Buy (Comprar).
  4. No pop-up "Review Phone Number" (Revisar número de telefone), revise as informações e clique em Buy (xxx) xxx-xxxx para confirmar sua compra.

Ativar modo PCI

Para usar qualquer um dos conectores de pagamento da Twilio, você deve habilitar o modo PCI em sua conta da Twilio. Isso garante que a Twilio capture os detalhes de pagamento de seus clientes de maneira compatível com PCI e remova informações confidenciais de PCI de qualquer registro de chamadas.

Para habilitar o modo PCI, conclua as etapas a seguir:

  1. Navegue até Voice Settings (Configurações de voz) no console da Twilio. (No painel de navegação esquerdo, clique em Voice > Settings > General.)
  2. Clique no botão Enable PCI Mode (Ativar modo PCI).
    Enable PCI Mode
  3. Clique em I Agree (Concordo) no pop‐up para aceitar os Termos de Serviço da Twilio.
  4. Clique no botão Save (Salvar).

Instalar o Generic Pay Connector

Para que a Twilio crie cobranças e tokens em seu nome, instale o Generic Pay Connector em sua conta Twilio.

  1. No Twilio Console, navegue até a página Pay Connectors (Conectores de pagamento). (No painel de navegação à esquerda, clique em Voice > Manage > Pay Connectors.)
  2. Clique no bloco Generic Pay Connector.

    Generic Pay Connector Console tile
  3. Clique em Install (Instalar).

Configurar o Generic Pay Connector

  1. Dê ao Generic Pay Connector um NOME ÚNICO. (Você pode dar a um Pay Connector por conta Twilio o nome "Default". Ao usar o Twilio Pay, se nenhum atributo paymentConnector for especificado, o Pay Connector padrão será usado.)
  2. Adicione as credenciais que você usa para seu processador de pagamentos no campo USERNAME (Nome de usuário) e PASSWORD (Senha).
  3. Insira o ENDPOINT URL (URL do endpoint) para a infraestrutura do seu processador de pagamento. É para onde a Twilio enviará as informações de pagamento de seus clientes.
    Configure Generic Pay Connector: Fill out unique name, username, password, and endpoint URL for your payment processor

Coletar dados de pagamento

Após instalar e configurar o Generic Pay Connector, você estará pronto para coletar informações de pagamento de seus clientes.

Você pode usar o verbo TwiML <Pay> ou o Agent Assist (usando a API Payments) para solicitar que os clientes insiram suas informações de pagamento. Usar <Pay> solicitará aos clientes que usem uma voz automatizada, enquanto o Agent Assist permite que um agente do call center solicite ao cliente que insira seus dados de pagamento.

A seção a seguir contém exemplos de código de como coletar informações de pagamento com o verbo <Pay>.

Tipos de transação suportados

A Twilio oferece suporte a dois tipos de transação: cobrar e tokenizar.

Transação de cobrança

Uma transação de cobrança significa que você deseja capturar imediatamente os fundos do método de pagamento fornecido pelo cliente (ou seja, cartão de crédito) em troca dos bens ou serviços que você oferece.

Se você quiser processar uma transação de cobrança usando um Generic Pay Connector, será necessário incluir um atributo chargeAmount em seu verbo <Pay> ou ao iniciar uma sessão de pagamento com a API de pagamentos, e o valor de chargeAmount deve ser maior que 0.

        
        
        

        Solicitação de transação de cobrança ao processador de pagamento

        Após coletar os dados de pagamento de seu cliente, o Generic Pay Connector enviará uma solicitação HTTPS POST para o URL configurado do seu processador de pagamento. Veja abaixo um exemplo do corpo da solicitação POST que será enviada. Observe que há uma propriedade "method" com valor de "charge", que indica o tipo de transação.

        {
          "method" : "charge",
          "transaction_id" : "transaction_id",
          "cardnumber" : "4111111111111111",
          "cvv":"123",
          "amount":"10.0",
          "currency_code":"USD",
          "expiry_month":"08",
          "expiry_year":"2022",
          "description":"pizza",
          "postal_code":"94111",
          "parameters" : {
            "customer_defined_key_1" :  "customer_defined_value_1",
            "customer_defined_key_2" :  "customer_defined_value_2"
          }
        }
        

        Resposta da transação de cobrança do processador de pagamento para a Twilio

        Os processadores de pagamento pegarão o objeto de solicitação acima, lidarão com a transação de cobrança e retornarão um objeto à Twilio que contenha um número de ID para a transação de cobrança, qualquer código/mensagem de erro aplicável e quaisquer parâmetros personalizados, se necessário.

        Abaixo está um exemplo de objeto de resposta que a Twilio esperaria de um processador de pagamento depois de lidar com uma transação de cobrança. Observe que há uma propriedade "charge_id com um valor de algum número de identificação associado à transação de cobrança.

        {
            "charge_id":"some_id",
            "error_code":null,
            "error_message":null
        }
        

        Solicitação da Twilio para o URL de ação ou statusCallback URL (transação de cobrança)

        A Twilio receberá e formatará a resposta do processador de pagamento.

        Se você usou o verbo <Pay>, a Twilio enviará essa informação no corpo de uma solicitação POST para o URL da ação

        Se você usou a API de pagamento, a Twilio enviará essas informações no corpo de uma solicitação POST para o URL statusCallback especificado na criação da sessão de pagamento.

        Transação tokenizar

        Uma transação tokenizar significa que você deseja obter um token com base nas informações de pagamento fornecidas pelo usuário (por exemplo, informações de cartão de crédito ou débito ACH) do processador de pagamento em vez de lançar qualquer encargo. Os tokens são normalmente armazenados para que você possa cobrar o usuário no futuro sem precisar solicitar o pagamento novamente. Observe que os tokens são fornecidos pelo seu gateway ou processador de pagamento.

        Para fazer uma transação tokenizar, você deve definir o chargeAmount como "0" ou omitir o atributo chargeAmount do seu verbo <Pay> ou ao iniciar uma nova sessão do Pay usando a API de pagamento.

              
              
              

              Tokenize a solicitação de transação para o processador de pagamento

              Após coletar os detalhes de pagamento de seu cliente, seu Generic Pay Connector enviará uma solicitação POST para o URL configurado do seu processador de pagamento. Veja abaixo um exemplo do corpo da solicitação POST que será enviada. Observe que há uma propriedade "method" com valor de "tokenize", que indica o tipo de transação.

              {
                "method" : "tokenize",
                "transaction_id" : "transaction_id",
                "cardnumber" : "4111111111111111",
                "cvv":"123",
                "currency_code":"USD",
                "expiry_month":"08",
                "expiry_year":"2022",
                "description":"pizza",
                "postal_code":"94111",
                "parameters" : {
                  "customer_defined_key_1" :  "customer_defined_value_1",
                  "customer_defined_key_2" :  "customer_defined_value_2"
                }
              }
              

              Tokenize a resposta da transação do processador de pagamento para a Twilio

              Os processadores de pagamento pegarão o objeto de solicitação acima, lidarão com a transação tokenizar e retornarão um objeto à Twilio que contenha um número de ID para a transação tokenizar, qualquer código/mensagem de erro aplicável e quaisquer parâmetros personalizados, se necessário.

              Abaixo está um exemplo de objeto de resposta que a Twilio esperaria de um processador de pagamento depois de lidar com uma transação tokenizar. Observe que há uma propriedade "token_id com um valor de algum número de identificação associado à transação tokenizar (ou o próprio token, dependendo do processador de pagamento).

              {
                  "token_id":"any_token",
                  "error_code":null,
                  "error_message":null 
              }
              

              Resposta da Twilio ao seu aplicativo (transação tokenizar)

              A Twilio receberá e formatará a resposta do processador de pagamento.

              Se você usou o verbo <Pay>, a Twilio enviará essa informação no corpo de uma solicitação POST para o URL da ação

              Se você usou a API de pagamento, a Twilio enviará essas informações no corpo de uma solicitação POST para o URL statusCallback especificado na criação da sessão de pagamento.

              Parâmetros personalizados

              A Twilio permite enviar parâmetros personalizados na solicitação ao processador de pagamento, bem como receber parâmetros personalizados do processador de pagamento.

              Enviar parâmetros personalizados ao processador de pagamento

              Se você usar o verbo <Pay>, poderá enviar parâmetros personalizados ao seu processador de pagamento usando o substantivo <Parameter>. Essa funcionalidade pode ser usada para enviar informações contextuais adicionais sobre a transação. Por exemplo, você pode informar o processador de pagamento para renunciar a taxas, cobrar taxas, processar um reembolso etc. Seu caso de uso específico e o processador de pagamento escolhido determinarão quais devem ser esses parâmetros personalizados.

              O substantivo <Parameter> é aninhado nas tags de abertura e fechamento do verbo <Pay> e usa os atributos name e value para o nome e o valor do seu parâmetro personalizado. (Consulte a amostra de código "Pay charge transaction with Parameter noun" (Pagar transação de cobrança com nome de parâmetro) abaixo.)

              O exemplo abaixo mostra uma transação de cobrança usando o substantivo <Parameter> para passar parâmetros personalizados para o processador de pagamento.

              Você também pode passar parâmetros personalizados para transações tokenizar da mesma maneira.

              Não há limite para o número de parâmetros personalizados que você pode aninhar em um verbo <Pay>.

                    
                    
                    

                    O corpo da solicitação POST que seu Generic Pay Connector envia ao processador de pagamento incluirá os parâmetros personalizados em uma propriedade "parameters", conforme mostrado abaixo.

                    {
                      "method" : "charge",
                      "transaction_id" : "transaction_id",
                      "cardnumber" : "4111111111111111",
                      "cvv":"123",
                      "amount":"10.0",
                      "currency_code":"USD",
                      "expiry_month":"08",
                      "expiry_year":"2022",
                      "description":"pizza",
                      "postal_code":"94111",
                      "parameters" : {
                        "custom_parameter_1" :  "custom_value_1"
                      }
                    }
                    

                    Receber parâmetros personalizados do processador de pagamento

                    A Twilio também pode lidar com o recebimento de parâmetros personalizados do seu processador de pagamento.

                    Depois que seu processador de pagamento processa sua transação, o corpo da resposta que ele envia de volta pode conter uma propriedade parameters, conforme mostrado no exemplo abaixo.

                    No momento, não é possível receber parâmetros personalizados para o processador de pagamento com a API Payments/Agent Assist.

                    {
                        "charge_id":"any_id",
                        "error_code":null,
                        "error_message":null, 
                        "parameters" : {
                            "key1_from_payment_processor" :  "value1_from_payment_processor",
                            "key2_from_payment_processor" :  "value2_from_payment_processor"
                        }
                    }
                    

                    Esses parâmetros personalizados serão adicionados como propriedades (com seus nomes prefixados com PayConnector_) no corpo da solicitação POST para seu URL action. (Leia mais sobre a forma do corpo da solicitação POST na seção de ação do documento <Pay>.)

                    Por exemplo, dada a resposta de amostra do processador de pagamento acima, o corpo da solicitação Twilio POST para seu URL action de ação pode incluir as seguintes propriedades:

                    PayConnector_key1_from_payment_processor:  "value1_from_payment_processor",
                    PayConnector_key2_from_payment_processor:  "value2_from_payment_processor"

                    Tratamento de erros e mecanismo de repetição

                    Repetir lógica

                    Se o processador de pagamento não responder à solicitação da Twilio em 10 segundos, a Twilio tentará novamente a solicitação até cinco vezes, passando o mesmo transaction_id na solicitação repetida.

                    Cabe ao processador de pagamento lidar adequadamente com a nova solicitação. Se a transação ainda estiver em andamento e for bem‐sucedida após mais de 10 segundos da solicitação inicial, a Twilio esperará que a resposta bem‐sucedida seja retornada à solicitação repetida.

                    Por exemplo, no caso em que o processador de pagamento leva 11 segundos para processar uma transação bem‐sucedida, o charge_id deve ser devolvido à solicitação de nova tentativa feita pela Twilio.

                    Em outras palavras, se uma transação duplicada for tentada, um erro deverá ser retornado à Twilio informando que foi uma transação duplicada ou charge_id/token_id (da primeira tentativa de resposta do processador de pagamento à Twilio) deverá ser retornado.

                    Otransaction_id se comporta como um token de idempotência para evitar cobranças duplicadas feitas pelo processador de pagamento no caso de uma resposta ser descartada em trânsito para a Twilio.

                    Tratamento de erros

                    Qualquer código de erro não NULL retornado de um processador de pagamento ou da infraestrutura do cliente será retornado ao cliente no campo connectorError enviado como parte do payload para o URL action especificado no verbo <Pay>. (Leia mais sobre a forma do corpo da solicitação POST na seção de ação do documento <Pay>.)

                    Estrutura de resposta de erro esperada do processador de pagamento

                    Em caso de erro, a Twilio espera receber o campo charge_id na resposta para um erro de cobrança e o campo token_id na resposta para um erro de tokenização do processador de pagamento. O campo de parâmetros é opcional.

                    Próximas etapas

                    Confira este tutorial do Generic Pay Connector, que mostra como configurar um Generic Pay Connector e um TwiML Bin usando <Pay>.

                    Classifique esta página:

                    Precisa de ajuda?

                    Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

                          
                          
                          

                          Obrigado pelo seu feedback!

                          Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

                          Enviando seu feedback...
                          🎉 Obrigado pelo seu feedback!
                          Algo deu errado. Tente novamente.

                          Obrigado pelo seu feedback!

                          Indique‑nos e obtenha USD10 em 3 etapas simples!

                          Etapa 1

                          Obtenha o link

                          Obtenha um link de indicação pessoal gratuito aqui

                          Etapa 2

                          Dê USD10

                          Seu usuário se inscreve e faz a atualização usando o link

                          Etapa 3

                          Obtenha USD10

                          1.250 mensagens SMS grátis
                          OU 1.000 min de voz grátis
                          OU 12.000 chats
                          OU mais