Integração de Pagamento Personalizada

Tópicos neste documento:

• Processamento de pagamentos de terceiros no Monetization
• Processamento de pagamento assíncrono
  • Exportação de faturas
    • Exporting job – Arquivo CSV para SFTP
    • Notificação - método webhook
  • Importação de pagamentos
    • Importação de arquivo CSV via SFTP
    • Importação via chamada de API
      • Autenticação
      • Solicitação de importação de pagamento
• Processamento de pagamento síncrono
  • Configuração do provedor de pagamento de terceiros
  • Operações de cliente
    • Criar cliente (sem cartão)
    • Atualizar cliente
    • Ler cliente
    • Excluir cliente
  • Operações de cartão
    • Configuração (solicitação de configuração de cartão)
    • Excluir cartão
  • Operações de transação
    • Autorização
    • Captura
    • Cobrança
    • Estorno
    • Reembolso
  • Tratamento de erros

Processamento de pagamentos de terceiros no Monetization

O processamento de pagamentos de terceiros é realizável através de dois métodos: síncrono e assíncrono. O método síncrono requer respostas imediatas do seu componente de integração de pagamento, enquanto o método assíncrono combina a extração de faturas do Monetization e a posterior importação dos pagamentos.

Processamento de pagamento assíncrono

Para o processamento de pagamento assíncrono, você exporta faturas do Monetization e os pagamentos são processados inteiramente fora do Monetization. Quando você tiver os resultados do processamento de pagamento, você os importa via arquivos CSV ou pela API do Monetization.

Exportação de faturas

Você pode exportar faturas do Monetization configurando um mapeador de exportação de faturas e agendando um Exporting job, que exportará os arquivos para um local SFTP, ou assinando uma criação de fatura via Webhook, que acionará uma solicitação de fatura para o endereço URL fornecido sempre que uma nova fatura for criada.

Exporting job – Arquivo CSV para SFTP

Para exportar faturas como arquivos CSV, um mapeador de Invoice Export precisa ser configurado para mapear os parâmetros da fatura para as colunas do arquivo CSV. A interface do usuário do Monetization permite tal configuração em Business configuration Export Invoice mappers.

Figura 1: Exemplo de configuração de mapeador de exportação de fatura

As exportações de faturas são agendadas através de Exporting Jobs, que podem ser tarefas únicas ou automatizadas para rodar em períodos específicos. O Exporting Job salvará o arquivo CSV exportado no respectivo local SFTP storage/invoice/folder_name/file_name.csv.

Figura 2: Exemplo de trabalho de exportação de fatura

Notificação - método webhook

A exportação de faturas através de webhooks permite que você receba faturas imediatamente após a criação. Isso é alcançado configurando uma Invoice Notification Rule, que enviará cada fatura criada como uma solicitação de corpo JSON para o endereço URL fornecido, juntamente com quaisquer opções de cabeçalho pré-configuradas.

Figura 3: Exemplo de configuração de webhook de criação de fatura

Importação de pagamentos

Você pode importar transações de pagamento para o Monetization configurando um mapeador de importação de pagamento e carregando os arquivos CSV de pagamento para o local de entrada SFTP ou utilizando a API REST do Monetization.

Importação de arquivo CSV via SFTP

Para que o Monetization importe transações de pagamento via arquivos CSV, deve haver um Payment Import Mapper configurado. A configuração é possível através da interface do usuário do Monetization em Business configuration Import Payment mappers.

O mapeador de pagamento permite o mapeamento de colunas CSV para parâmetros de transação de pagamento e a definição de um prefixo de arquivo, que precisa estar presente nos arquivos carregados.

Os arquivos são carregados no servidor SFTP na pasta edl/input e serão movidos para as pastas edl/processed, edl/successful, edl/error e edl/rejected, dependendo dos resultados do processamento.

Figura 4: Exemplo de configuração de mapeador de importação de pagamento

Importação via chamada de API

Para importar uma transação de pagamento via API do Monetization, envie uma solicitação JSON contendo os detalhes da transação para a API REST do Monetization.

Autenticação

A API do Monetization utiliza autenticação Bearer Token:

1. Execute a solicitação de autenticação com nome de usuário, senha e código de site específico.
2. Obtenha o token da resposta.
3. Defina o cabeçalho Authorization como Bearer <token> nas próximas solicitações.
4. O token expira após 5 minutos.

URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}

Solicitação de importação de pagamento

URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Processamento de pagamento síncrono

O processamento de pagamento síncrono requer comunicação síncrona entre o Monetization e seu componente de integração de pagamento. Este método de processamento permite autorizações de cartão de crédito/débito e pagamentos imediatos.

Você configura o Monetization para especificar para onde as solicitações relacionadas ao processamento de pagamento devem ser enviadas, e o Monetization tem respostas predefinidas que espera em retorno. Este método de processamento permite o armazenamento de referências de método de pagamento nos clientes e suporta processos automatizados de coleta de pagamento.

Para o Monetization, o processo de integração é virtualmente o mesmo que uma integração nativa com um provedor existente (Stripe, Braintree, etc.). No entanto, a comunicação é executada através de um componente desenvolvido por você, que atua como um gateway para o seu provedor de pagamento local.

Operações essenciais para suportar o processamento de pagamento síncrono:

• Setup Intent
• Authorize
• Capture
• Charge

Configuração do provedor de pagamento de terceiros

Para configurar uma integração de provedor de pagamento de terceiros, configure um perfil de gateway de pagamento de terceiros e forneça a URL para onde o Monetization deve enviar solicitações.

Isso é realizável através da interface do usuário em System configuration Payment gateways, ou criando um Payment Gateway Profile via API REST do Monetization.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

Operações de cliente

As operações de cliente aplicam-se apenas nos casos em que o provedor de pagamento de terceiros suporta a gestão de clientes. Se o provedor de pagamento não suportar a gestão de clientes, então os ids de cliente podem ser substituídos por qualquer valor (por exemplo, timestamp Unix da solicitação).

Criar cliente (sem cartão)

Cria um cliente como um objeto no serviço do provedor de pagamento.

Solicitação enviada pelo Monetization:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Resposta esperada:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Atualizar cliente

Atualiza um objeto de cliente no serviço do provedor de pagamento.

Solicitação enviada pelo Monetization:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Resposta esperada:

HTTP Status: 204 No Content

Nenhum Corpo de Resposta

Ler cliente

Lê um objeto de cliente do serviço do provedor de pagamento.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Resposta esperada:

HTTP Status: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Excluir cliente

Exclui um objeto de cliente do serviço do provedor de pagamento.

Solicitação enviada pelo Monetization:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Resposta esperada:

HTTP Status: 204 No Content

Nenhum Corpo de Resposta

Operações de cartão

As operações de cartão referem-se à configuração ou remoção de cartões de crédito e débito.

Configuração (solicitação de configuração de cartão)

Aciona um processo onde um cliente pode fornecer detalhes do cartão de crédito, que são tokenizados e armazenados no Monetization. Mediante uma solicitação para adicionar um novo cartão de crédito, o Monetization enviará uma solicitação de configuração para o seu componente de integração.

Seu componente de integração precisa lidar com qualquer lógica relacionada aos serviços do provedor de pagamento e retornar uma URL de redirecionamento para o Monetization como resposta. O cliente será então redirecionado para a URL fornecida, onde o formulário hospedado pelo seu provedor de pagamento coletará e tokenizará os detalhes do cartão do cliente.

Figura 5: Configuração do cartão de crédito

Solicitação enviada pelo Monetization:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Resposta esperada:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Excluir cartão

Envia uma solicitação ao seu componente de integração para lidar com a lógica de remoção de referência de cartão de crédito via serviços do provedor de pagamento e, em seguida, remove a referência do Monetization após o sucesso.

Solicitação enviada pelo Monetization:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Resposta esperada:

HTTP Status: 204 No Content

Nenhum Corpo de Resposta

Operações de transação

As operações de transação referem-se a ações transacionais executadas em tokens de método de pagamento armazenados (cartão de crédito/débito). Estas ações incluem:

• Autorização
• Captura
• Cobrança
• Estorno
• Reembolso

Autorização

A autorização é usada para autorizar (bloquear) fundos no método de pagamento de um cliente. As autorizações podem ser Capturadas ou Estornadas posteriormente. A solicitação abaixo é enviada para o seu componente de integração, que deve lidar com a lógica do serviço do provedor de pagamento e retornar uma resposta.

Solicitação enviada pelo Monetization:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Resposta esperada:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Captura

A captura refere-se à coleta de fundos autorizados de uma solicitação de Autorização anterior. O valor a ser coletado pode ser igual ou inferior ao valor autorizado.

Quaisquer fundos autorizados não coletados serão liberados de volta para o cliente pelo serviço do provedor de pagamento. A solicitação abaixo é enviada para o seu componente de integração, que deve lidar com a lógica do serviço do provedor de pagamento e retornar uma resposta.

Solicitação enviada pelo Monetization:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Resposta esperada:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Cobrança

A cobrança autoriza e captura fundos como uma única transação imediata. A solicitação abaixo é enviada para o seu componente de integração, que deve lidar com a lógica do serviço do provedor de pagamento e retornar uma resposta.

Solicitação enviada pelo Monetization:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Resposta esperada:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Estorno

A operação de estorno (Void) anula uma transação de Autorização, liberando os fundos autorizados. A solicitação abaixo é enviada para o seu componente de integração, que deve lidar com a lógica do serviço do provedor de pagamento e retornar uma resposta.

Solicitação enviada pelo Monetization:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Resposta esperada:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Reembolso

O reembolso devolve fundos ao cliente e faz referência a uma transação de Cobrança ou Captura anterior. A solicitação abaixo é enviada para o seu componente de integração, que deve lidar com a lógica do serviço do provedor de pagamento e retornar uma resposta.

Solicitação enviada pelo Monetization:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Resposta esperada:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Tratamento de erros

Caso uma operação não seja bem-sucedida no seu componente de integração, retorne qualquer status fora da faixa 200-300 e a mensagem de erro no corpo da resposta.