Adicionar informações a um pagamento

Envie-nos elementos de dados extras, como informações da aplicação, opções tender e dados adicionais.

Em uma solicitação básica de pagamento da API de terminais, você só precisa especificar o valor, a moeda, o ID e a data e hora da transação. Mas talvez você queira adicionar as informações que deseja aplicar à sua solicitação ou salvar na plataforma de pagamentos da Adyen. O campo SaleToAcquirerData permite que você faça isso. Nesse campo, você pode adicionar todos os tipos de elementos de dados:

Informações da aplicação que podemos usar para fins de solução de problemas.
Metadata de sua própria escolha que você deseja conectar ao pagamento.
Dados para permitir o reconhecimento do cliente e tokenização.
Opções Tender para influenciar como a transação é processada.
Dados adicionais para casos de uso comuns. Por exemplo, para pagamentos divididos e pré-autorização.

Consulte exemplos de SaleToAcquirerData para ver como são esses elementos de dados. Abaixo, os descrevemos com mais detalhes e explicamos como adicionar uma combinação de elementos de dados à sua solicitação de pagamento.

Informações da aplicação

As informações da aplicação consistem em elementos de dados que identificam o software usado para fazer solicitações de pagamento para a plataforma de pagamentos da Adyen. Quando você inclui informações da aplicação em suas solicitações de pagamento, podemos analisar e solucionar problemas de pagamentos com mais eficiência e fornecer uma melhor experiência de suporte.

FPara obter mais informações, consulte Enviar informações da aplicação.

Metadata

Metadata são elementos de dados que você mesmo cria. Quando você adiciona metadados à sua solicitação de pagamento, eles são ecoados na resposta para que você possa conectar a transação aos seus metadata. Por exemplo, para adicionar um número de turno e um ID de funcionário a um pagamento. Você pode criar até 20 campos metadata, onde o máximo do campo de nome é 20 caracteres e o valor máximo 80 caracteres.

Para também receber metadata em seus relatórios de liquidação, entre em contato com nossa Support Team.

Dados para permitir o reconhecimento do cliente e tokenização

Com base nos identificadores de clientes que você recebe na resposta de pagamento, é possível vincular o pagamento a um cliente. Isso permite que você personalize a experiência de compra ou faça pagamentos recorrentes usando um token em vez de detalhes reais do cartão. Mas primeiro você precisa criar esses identificadores de clientes e armazená-los na plataforma de pagamentos da Adyen. Para fazer isso, você inclui elementos de dados como shopperEmail, shopperReference, e recurringContract no campo SaleToAcquirerData de seu pedido de pagamento inicial.

Para obter mais informações, consulte Reconhecimento de clientes e tokenização.

Opções Tender

By adding one or more tender options to a payment request, you influence how that transaction is processed. Por exemplo, você pode enviar a opção tende AskGratuity para mostrar opções de gorjeta no terminal de pagamento.

Para obter mais informções, consulte Enviar opçõeas tender.

Dados adicionais

Existem muitos elementos de dados adicionais que você pode adicionar às suas solicitações de pagamento. A lista é longa e crescente, por isso não podemos mencionar todas elas aqui. Veja, por exemplo, Dados adicionais em nosso API Explorer. Muitos desses elementos também se aplicam a pagamentos na loja.

AIncluindo elementos de dados em sua solicitação

Existem duas maneiras de transmitir elementos de dados no campio SaleToAcquirerData da sua solicitação de pagamento:

Option 1: Como um objeto JSON convertido em uma sequência codificada em Base64.
Option 2: Como pares de valores-chave codificados em formulário (usando & como separador).

Consulte exemplos de SaleToAcquirerData para ver como são esses formatos.

O formato do SaleToAcquirerData determina o formato do AdditionalResponse que você recebe.

Recebendo a resposta adicional

A AdditionalResponse em sua resposta de pagamento retorna informações resultantes do processamento de sua solicitação de pagamento. Ele também ecoa algumas das informações que você adicionou à sua solicitação de pagamento, para que você possa usá-las na sua lógica de negócios.

A resposta adicional pode conter muitos campos de dados, mas talvez você não precise de todos eles. Para selecionar os dados que você deseja:

Na sua área de cliente, acesse Developers > API URLs.
Selecione as opções para o tipo de dados que você deseja receber.

O formato da AdditionalResponse corresponde ao formato da SaleToAcquirerData na solicitação de pagamento: Um objeto JSON codificado em Base64 ou pares de valores-chave codificados em formulário.
Se a solicitação não contiver nenhuma SaleToAcquirerData, a AdditionalResponse estará no formato de pares de valores-chave.

Opção 1: enviar elementos de dados como JSON codificado em Base64

Este exemplo mostra como adicionar elementos de dados à sua solicitação de pagamento como um objeto JSON convertido em uma sequência codificada em Base64:

Crie um objeto JSON com os elementos de dados que você deseja transmitir.

Neste exemplo, usamos um conjunto limitado de dados:

Todas as informações da aplicação.
E-mail e referência do cliente.
Duas opções tender : ReceiptHandler para imprimir o recibo na caixa registradora e AskGratuity para pedir uma gorjeta.

Portanto, o objeto JSON ficará assim:

{
    "applicationInfo": {
        "merchantApplication": {
            "name": "Acme Adyen Connector",
            "version": "2.0"
        },
        "externalPlatform": {
            "integrator": "Retail Consultancy Co.",
            "name": "Acme Corporate POS",
            "version": "1.0.2"
        },
        "merchantDevice": {
            "os": "Windows 10 Pro",
            "osVersion": "1909",
            "reference": "CASH_REGISTER_1234"
        }
    },
    "shopperEmail": "S.Hopper@gmail.com",
    "shopperReference": "CUST01_34582",
    "tenderOption": "ReceiptHandler,AskGratuity"
}

Codifique o objeto JSON para Base64.

ICAgIHsKICAgICAgICAiYXBwbGljYXRpb25JbmZvIjogewogICAgICAgICAgICAibWVyY2hhbnRBc
HBsaWNhdGlvbiI6IHsKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQWR5ZW4gQ29ubmVjdG
9yIiwKICAgICAgICAgICAgICAgICJ2ZXJzaW9uIjogIjIuMCIKICAgICAgICAgICAgfSwKICAgICA
gICAgICAgImV4dGVybmFsUGxhdGZvcm0iOiB7CiAgICAgICAgICAgICAgICAiaW50ZWdyYXRvciI6
ICJSZXRhaWwgQ29uc3VsdGFuY3kgQ28uIiwKICAgICAgICAgICAgICAgICJuYW1lIjogIkFjbWUgQ
29ycG9yYXRlIFBPUyIsCiAgICAgICAgICAgICAgICAidmVyc2lvbiI6ICIxLjAuMiIKICAgICAgIC
AgICAgfSwKICAgICAgICAgICAgIm1lcmNoYW50RGV2aWNlIjogewogICAgICAgICAgICAgICAgIm9
zIjogIldpbmRvd3MgMTAgUHJvIiwKICAgICAgICAgICAgICAgICJvc1ZlcnNpb24iOiAiMTkwOSIs
CiAgICAgICAgICAgICAgICAicmVmZXJlbmNlIjogIkNBU0hfUkVHSVNURVJfMTIzNCIKICAgICAgI
CAgICAgfQogICAgICAgIH0sCiAgICAgICAgInNob3BwZXJFbWFpbCI6ICJTLkhvcHBlckBnbWFpbC
5jb20iLAogICAgICAgICJzaG9wcGVyUmVmZXJlbmNlIjogIkNVU1QwMV8zNDU4MiIsCiAgICAgICA
gInRlbmRlck9wdGlvbiI6ICJSZWNlaXB0SGFuZGxlcixBc2tHcmF0dWl0eSIKICAgIH0=

Crie uma solicitação de pagamento contendo:
- SaleData.SaletoAcquirerData: O objeto JSON codificado em Base64.
Observe que a resposta de pagamento possui um AdditionalResponse no mesmo formato que o campo SaleToAcquirerData: Uma sequência codificada em Base64.

Decodifique a sequência Base64 no campo AdditionalResponseda resposta de pagamento.
Observe que este contém:

O shopperReference e shopperEmail enviados na solicitação.
Dados resultantes do processamento do pagamento.

{
    "tid": "46403161",
    "AID": "A000000004101002",
    "transactionType": "GOODS_SERVICES",
    "transactionLanguage": "fr",
    "backendGiftcardIndicator": "false",
    "posadditionalamounts.originalAmountValue": "1099",
    "expiryYear": "2028",
    "acquirerAccountCode": "TestPmmAcquirerAccount",
    "alias": "A373176724022941",
    "posAmountGratuityValue": "100",
    "gratuityAmount": "100",
    "giftcardIndicator": "false",
    "authorisedAmountValue": "1199",
    "pspReference": "8525863405367252",
    "cardHolderName": "TC04_MC_Approved_DCC",
    "paymentMethodVariant": "mc",
    "refusalReasonRaw": "APPROVED",
    "authorisationMid": "1000",
    "applicationPreferredName": "mc f",
    "acquirerCode": "TestPmmAcquirer",
    "store": "StoreOne",
    "txtime": "12:08:36",
    "iso8601TxDate": "2020-04-08T10:08:36.0000000+0000",
    "cardType": "mc",
    "posOriginalAmountValue": "1099",
    "offline": "false",
    "aliasType": "Default",
    "recurring.shopperReference": "CUST01_34582",
    "txdate": "08-04-2020",
    "paymentMethod": "mc",
    "cvcResult": "0 Unknown",
    "authorisedAmountCurrency": "EUR",
    "shopperReference": "CUST01_34582",
    "shopperEmail": "S.Hopper@gmail.com",
    "tc": "C7ADE47CED2E180D",
    "avsResult": "0 Unknown",
    "cardIssueNumber": "53",
    "mid": "1000",
    "merchantReference": "27908",
    "transactionReferenceNumber": "8525863405367252",
    "applicationLabel": "MCDCCFR",
    "expiryMonth": "02",
    "cardSummary": "9990",
    "posadditionalamounts.originalAmountCurrency": "EUR",
    "posAuthAmountCurrency": "EUR",
    "cardHolderVerificationMethodResults": "440002",
    "authCode": "123456",
    "cardIssuerCountryId": "840",
    "adjustAuthorisationData": "BQABAQB3u8msnEnODzDEMNkLKaNW4MuEMYxLUinFzM3a0t50kcEht\/yV2kkt1hxKpESSdAv0H2h1\/GwFZefCbCeCAtE3SrvPYlwtI1URWeTzci22YThkc\/JzUiPB0M3jf+f0FltPHnBFdsJB6wnKkXMlmdCZzHT209QWl4rgS1+Qq3T0Yuu8\/E2crOpg6VRfESWL8U4v5arASY5+p39Z43qjyuJFWIPbMGaMvGKBZGWZtmi8tr9aKUqsYyJ8jADFpuWyid3vo+XFL9LsW0pvc9MphiODyzfzi8azLosLNRuzZBf+B9yKByDKiGpV6CZ59ECi0nNGvM\/hYZtuhvHUnANYz6nzECD8IbBX\/4pGiYqJUBWd4n8AAAa8+DKQstiNIRJaSl+18GvUnYLpwoyEHsnJTdYQPMtK0RIVC0PZ5R5R\/XB9Yw5LfL5n7Owxau91lIiy5DQLUFN9eV2Q0MmTRJTj1jprHRnEIV1haoQqWJbeJVf4fRjmuPuJtg5HnwJXesC\/blC8lkvCZ9WIjsliLi2rlQ6HnOQjGyFVndV3a8AhZrkteJ1n8Ik6iaZdUjRUWGXIUpT2F2fvUXUyO4HdVilALhJRSzX+DMOK23NpExIRpUZFj9dJKjmZmIRTwmY6Cm2scR\/4hr7jXeFwHYRsDOSWfEy2ZvYlqtYaFoAjiLtq2ujb5kW93uYr1zf2EAHJqkHFFLX1A0QDOXbkx0Fj6Rl27IvYq72Mmzd6tbJFYLcJ73zEkcfFiVS8JEgwvr0\/+vdcAKNOhvt\/tRPWnfZO0sTD7dR7EvM567UDvxUEhtc2MUhYWlDeiMjkMhANl4Qf1ixMdhHnqvW0D8lKvlZFhKJLH0RmKsmX+ombCp5KlCbucAwUi\/Vetq3dGw==",
    "posAmountCashbackValue": "0",
    "posEntryMode": "ICC",
    "fundingSource": "CREDIT",
    "issuerCountry": "US",
    "cardScheme": "mc",
    "cardBin": "541333",
    "posAuthAmountValue": "1199",
    "posadditionalamounts.gratuityAmount": "100"
}

Opção 2: enviar elementos de dados como pares de valor-chave

Este exemplo mostra como adicionar elementos de dados à sua solicitação de pagamento como pares de valor-chave codificado em formulário.

Crie uma sequência com os elementos de dados que você deseja passar em pares de valores-chave, usando & como separador entre os pares.

Neste exemplo, usamos um conjunto limitado de dados:
- All application information:
  applicationInfo.merchantApplication.name=Acme Adyen Connector
  applicationInfo.merchantApplication.version=2.0
  applicationInfo.externalPlatform.integrator=Retail Consultancy Co.
  applicationInfo.externalPlatform.name=Acme Corporate POS
  applicationInfo.externalPlatform.version=1.0.2
  applicationInfo.merchantDevice.os=Windows 10 Pro
  applicationInfo.merchantDevice.osVersion=1990
  applicationInfo.merchantDevice.reference=CASH_REGISTER_1234
- Shopper email and shopper reference:
  shopperEmail=S.Hopper@gmail.com and shopperReference=CUST01_34582
- Two tender options to let the POS app handle printing or sending the receipt, and to ask for a tip:
  tenderOption=ReceiptHandler,AskGratuity
Portanto, a string ficará assim:
```
applicationInfo.merchantApplication.name=Acme Adyen Connector&applicationInfo
.merchantApplication.version=2.0&applicationInfo.externalPlatform.integrator=
Retail Consultancy Co.&applicationInfo.externalPlatform.name=Acme Corporate P
OS&applicationInfo.externalPlatform.version=1.0.2&applicationInfo.merchantDev
ice.os=Windows 10 Pro&applicationInfo.merchantDevice.osVersion=1990&applicati
onInfo.merchantDevice.reference=CASH_REGISTER_1234&shopperEmail=S.Hopper@gmai
l.com&shopperReference=CUST01_34582&tenderOption=ReceiptHandler,AskGratuity
```
Faça um pedido de pagamento com:
- SaleData.SaletoAcquirerData: Sua sequência de pares de valores-chave codificados em formulário.
Observe que a resposta do pagamento tem a AdditionalResponse no mesmo formato do SaleToAcquirerData: valores-chave codificados em formulário. Este contém:
- O shopperReference e shopperEmail enviados na solicitação.
- Dados resultantes do processamento do pagamento.