Credenciais armazenadas

Dependendo de como e quando um payment é processado, ele pode se originar de transações iniciadas pelo cliente (CIT) ou transações iniciadas pelo comerciante (MIT).

Para garantir o armazenamento e o uso responsáveis das informações do titular do cartão, a Visa e a Mastercard estabeleceram diretrizes e regulamentos para credenciais armazenadas.

Simplificamos o processo para que você esteja em conformidade com essas regras do esquema, permitindo que você armazene com segurança os detalhes do cartão no Yuno para uso futuro e, ao mesmo tempo, mantenha a conformidade.

⚠️

Importante: Isso não é o mesmo que Assinaturas

Pense em quem está no controle da recorrência:

• Credenciais armazenadas: Você controla a recorrência e é responsável por enviar cada transação de acordo com sua própria programação e lógica de recorrência.
• API de assinatura: A Yuno a controla. Você fornece instruções uma vez e, em seguida, a Yuno envia automaticamente as transações em seu nome. Consulte Assinaturas.

• Categorização
• Considerações gerais
• Criar um payment
• ID do contrato de assinatura
• ID da transação de rede

Categorização

Determinar se uma transação é iniciada pelo comerciante ou pelo cliente tem implicações significativas para a segurança, a experiência do usuário, a prevenção de fraudes e a conformidade normativa. Isso garante um processo payment eficiente e seguro para todas as partes envolvidas.

Considerações gerais

• Responsabilidade: No contexto da autenticação forte do cliente (SCA) sob a regulamentação PSD2 na União Europeia, o CIT geralmente exige uma autenticação maior em comparação com o MIT.
• Frequência: As transações de MIT são geralmente recorrentes e periódicas, enquanto as de CIT são eventos mais ad hoc baseados nas ações do cliente.

Criar um pagamento com tipo de processamento

Para especificar um payment com um tipo de processamento, use o stored_credentials dentro da estrutura payment_method.detail.card ao criar um payment.

❗️

Crítico: Preencher todos os campos obrigatórios

• Ao trabalhar com transações de CIT e MIT, é essencial preencher corretamente o campo usage, reasone network_transaction_id campos. O não preenchimento correto desses campos pode resultar em redução das taxas de aprovação e perda de disputas de estorno.
• Alguns provedores (por exemplo, Adyen) exigem que o reason permanece consistente durante todo o ciclo de vida da transação. Se sua primeira transação (usage=FIRST) usa reason=SUBSCRIPTION, todas as transações subsequentes (usage=USED) também deve usar reason=SUBSCRIPTION.

Motivos da credencial de armazenamento

Exemplo de Request

curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "DE",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "EUR",
        "value": 5000
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
}
'

Contrato de assinatura

Para determinados mercados (MX, por exemplo) e processadores de pagamento, quando um pagamento relacionado à assinatura é feito, a ID do contrato com o cliente precisa ser especificada na solicitação de pagamento para garantir o processamento correto. Para facilitar isso, ativamos a opção subscription_agreement_id dentro do campo stored_credentials permitindo que você compartilhe o acordo feito com o cliente.

📘

Observação

O subscription_agreement_id e network_transaction_id são campos independentes. Incluindo um subscription_agreement_id não substitui a necessidade de um network_transaction_id. Ambos devem ser fornecidos quando aplicável para garantir taxas de aprovação ideais e proteção contra estornos.

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "subscription_agreement_id":"AA0001",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

ID da transação de rede

Uma ID de transação de rede é um identificador exclusivo atribuído a uma transação pela rede de cartões. É usado para rastrear e referenciar transações específicas, principalmente em cenários de payment recorrente, garantindo consistência e rastreabilidade em todo o ciclo de vida do payment .

Se a transação for iniciada pelo cliente (CIT), a referência da transação de rede estará disponível no card.stored_credentials.network_transaction_id campo. Esse campo representa a ID da transação para Visa e a ID de rastreamento para Mastercard, que são recomendadas para futuros pagamentos de assinatura.

"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }

Uso

Associamos o network_transaction_id com o vaulted_token para transações futuras, para que você não precise gerenciar a lógica para cada caso. Realizaremos a associação quando um payment for criado com:

• Método Payment:
  • Um cartão vaulted_tokenou
  • Dados do cartão com vault_on_success definido como true
• Credenciais armazenadas:
  • usage definido como FIRST

⚠️

Ao usar vault_on_success = true em uma integração direta, você deve primeiro criar o cliente e passar seu customer_payer.id na solicitação de pagamento. O envio dos dados do cliente em linha não cria o cliente no sistema da Yuno, portanto, o cartão não pode ser armazenado e nenhum vaulted_token será devolvido.

Se você já tiver o network_transaction_id para o cartão, você pode incluí-lo no payment no campo correspondente. Caso contrário, para pagamentos MIT (com stored_credentials.usage=USED), enviaremos o network_transaction_id associado ao vaulted_token para o provedor.

❗️

Lembre-se de especificar o uso no stored_credentials à medida que acionamos a seção network_transaction_id lógica com base nesses campos.