Caso de uso

Segue uma lista não abrangente dos casos de uso com a criação do formToken (ao chamar o serviço web Charge/createPayment ).

Enviar o número de pedido

Para enviar o número de pedido, usar o campo orderId :

{
    "orderId" : "CX-1254"
}

Enviar os dados do comprador

O EC pode comunicar o endereço de faturamento e os dados do comprador (e-mail, telefone, etc).

Estes dados serão:

• exibidos no Back Office EC, no detalhe da transação (aba Comprador ),
• retornadas na IPN, sem modificação.

Para isso, use o campo customer :

Exemplo

{
    "customer": {
        "reference":"C2383333540",
        "email" : " <sample@example.net>",
        "billingDetails" : {
            "category" : "PRIVATE",
            "title" : "M",
            "firstName" : "Laurent",
            "lastName" : "DURANT",
            "streetNumber" : "109",
            "address" : "rue de l'innovation",
            "zipCode" : "31670",
            "city" : "LABEGE",
            "country" : "FR",
            "phoneNumber" : "0123456789",
            "cellPhoneNumber" :"0623456789"
        }
    }
}

Enviar os dados de entrega

O Estabelecimento Comercial pode enviar os dados de entrega do comprador (endereço, estado civil, número de telefone, etc.).

Estes dados serão:

• exibidos no Back Office EC, no detalhe da transação (aba Entrega ),
• retornadas na IPN, sem modificação.

Exemplo para uma entrega de tipo "Retirada na loja"

O endereço de entrega é o endereço da loja.

O endereço de faturamento é diferente do endereço de entrega.

O nome do destinatário da entrega é o mesmo que do endereço de faturação.

{
    "customer": {
        "shippingDetails": {
            "shippingMethod": "RECLAIM_IN_SHOP",
            "shippingSpeed": "STANDARD",
            "streetNumber": "230",
            "address": "avenue des Champs Elysées",
            "zipCode": "59170",
            "city": "CROIX",
            "country": "FR",
            "firstName": "Marie-Charlotte",
            "lastName": "GRIMALDI",
            "phoneNumber": "0328386789"
        }
    }
}

Exemplo para uma entrega de tipo "ponto de retirada"

O endereço de entrega é o endereço do ponto de retirada.

O nome do ponto de retirada é enviado na segunda linha do endereço de entrega.

O endereço do ponto de retirada é enviado na primeira linha de endereço de entrega.

O nome do destinatário é o nome do endereço de faturamento.

O endereço de faturamento é diferente do endereço de entrega.

{
    "customer": {
        "shippingDetails": {
            "shippingMethod": "RELAY_POINT",
            "shippingSpeed": "STANDARD",
            "streetNumber": "100",
            "address": "avenue du parc Barbieux",
      "address2": "Pressing du Parc",
            "zipCode": "59170",
            "city": "CROIX",
            "country": "FR",
            "firstName": "Martine",
            "lastName": "DURAND",
            "phoneNumber": "0328386789",
      "deliveryCompanyName":"Chronospost"
        }
    }
}

Enviar o conteúdo do carrinho

Ao criar um pagamento, o EC pode enviar o conteúdo do carrinho do comprador.

Estes dados serão exibidos no Back Office EC quando consultar o detalhe da transação (aba Carrinho ).

Para isso, use o campo cartItemInfo (tabela de objeto json) na chamada ao Web Service Charge/CreatePayment.

Exemplo para definir 2 artigos no carrinho

{
"customer": {

     "shoppingCart": {
       "cartItemInfo": [
       {
        "productRef": "myRef1",
        "productAmount": "1200",
        "productLabel": "myLabel1",
        "productQty" : "1"
       },
       {
        "productRef": "myRef2",
        "productAmount": "2400",
        "productLabel": "myLabel2",
        "productQty" : "1"
       }
       ]
     }
    }

}

Observações:

• O campo cartItemInfo é sempre retornado vazio na resposta.
• Para que a exibição da aba Carrinho seja correta no Back Office EC, deve enviar pelo menos o campo productAmount de cada produto.

Enviar os dados do revendedor

O facilitador de pagamento pode enviar os dados do revendedor que participa à transação.

Esses dados serão:

• exibidos no Back Office EC, no detalhe da transação (aba Sub-EC ),
• retornadas na IPN, sem modificação.

O quadro apresenta os campos comuns disponíveis com os dados sobre o revendedor.

Propor salvar o meio de pagamento.

O EC pode propor ao comprador facilitar suas compras ofertando o armazenamento dos dados de cartão pela plataforma de pagamento.

Graças a esta operação, a plataforma de pagamento atribui um token único ao meio de pagamento que será retornado para o site EC no campo paymentMethodToken.

Desta forma, e para futuras compras, o comprador não precisará digitar seus dados de cartão de novo.

Esta solução deixa os pagamentos ainda mais seguros já que é comunicado apenas o token e este é exclusivo à plataforma de pagamento.

Para dar a opção ao comprador de salvar seu meio de pagamento na hora do pagamento, use o campo formAction com o valor ASK_REGISTER_PAY

{
    "formAction" : "ASK_REGISTER_PAY",
    "customer": {
        "email": " <sample@example.net>"
    }
}

Observação

O campo email torna-se obrigatório quando salvar o meio de pagamento.

Na exibição do formulário, aparece uma caixinha a ser assinalada.

Por default, esta caixinha não está assinalada.

Se o pagador concordar em armazenar seu cartão, ele deve assinalar a caixinha.

Se o pagamento for recusado, o meio de pagamento não será salvo.

Forçar o armazenamento do meio de pagamento

Se o EC avisar o comprador antes no fluxo de compra, o EC poderá tokenizar sem exibir a caixinha.

Para isso, use o campo formAction com o valor REGISTER_PAY :

{
    "formAction" : "REGISTER_PAY",
    "customer": {
  "email": " <sample@example.net>"
    }
}

Usar um meio de pagamento salvo

O EC pode enviar o token que deve ser debitado quando o pagamento iniciar.

Durante a exibição do formulário, os campos kr-pan e kr-expiry são automaticamente preenchidos. Bastará ao comprador digitar seu CVV para finalizar a compra.

Para isso, basta enviar o token a ser debitado no campo paymentMethodToken e valorizar o campo formAction com PAYMENT.

Este valor sendo o valor por default, o campo formAction não é mais obrigatório.

{
    "formAction" : "PAYMENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Usar um meio de pagamento salvo sem exibir o formulário incorporado

Esse modo permite que você crie uma transação sem exibir o formulário de pagamento e sem autenticação (chamada de servidor para servidor).

{
    "formAction" : "SILENT",
    "paymentMethodToken":"d3d9cc0d24a4400e9d123e9e1b8f1793",
}

Observação

• Esse caso de uso não utiliza o cliente JavaScript, apenas uma chamada servidor a servidor. Não há redirecionamento para a url de volta especificada em kr-post-url-success.
• A resposta não contém formToken mas diretamente um objeto Transação.
• Use a referência em cadeia no campoinitialIssuerTransactionIdentifierCaso contrário os emissores podem recusar a transação no caso de ausência de encadeamento("Soft Decline").
• Ver : Pagamento em 0 clique

Enviar a preferência do Estabelecimento Comercial

Use o campo strongAuthentication (link para o playground: strongAuthentication).

Este campo indica a preferência do comerciante em relação à autenticação do comprador.

• Sem interação do portado ( frictionless ).
• Com interação do portador (autenticação forte ou challenge ).
• Nenhuma preferência do EC.

Tabela de isenções (valor DISABLED)

Aumentar as chances de frictionless em 3DS2

Transmita esses dados para aumentar as chances de frictionless durante o pagamento.

Lista dos campos para enviar

Enviar dados personalizados

Na criação de um pagamento, o EC pode pode comunicar informações específicas ao PayZen para atender regras de negócio.

Por exemplo, enviar um número de arquivo, um número de contrato etc...

Estas informações serão:

• exibidos no Back Office EC, no detalhe da transação (aba Extras ),
• presentes no e-mail de confirmação de pagamento enviado ao EC,
• retornadas na URL de notificação, sem modificação.

Para isso, use os campos metadata (no formato json) na chamada ao Web Service Charge/CreatePayment :

Exemplo para enviar o dado afiliação:

{
"metadata": {
"contract": "1245KL-78/ZE"
}
}

Sobrescrever a URL de notificação instantânea (não aconselhado)

Você pode sobrescrever a URL de notificação instantânea (também chamada IPN) no formulário se você usar uma só loja para diferentes canais de venda, diferentes tipologias de pagamento, diferentes idiomas etc...

Esta funcionalidade não é compatível com a execução, pelo Back Office EC, da solicitação enviada à url de notificação instantânea.

A URL chamada é aquela configurada nas regras de notificação (ver capítulo Configurar as notificações).

Use o campo ipnTargetUrl ao iniciar o pagamento para sobrescrever a URL da página que quer notificar.

Se o valor do campo ipnTargetUrl estiver errado, o formulário não será recusado.

{
    "ipnTargetUrl" : "<https://my.site/my-ipn>",
}