Verifique o saldo de um cartão vale presente

Para verificar os fundos restantes em um cartão vale presente ativado, faça uma solicitação de saldo. Quando a solicitação de saldo é processada, você recebe uma resposta especificando os fundos restantes no cartão vale presente.

Antes de começar

Antes de realizar transações com cartão vale presente, certifique-se de:

• Ler e entender nossos fundamentos da API de terminais.
• Criar uma integração que pode efetuar um pagamento.
• Concluir o processo de integração com seu provedor de cartão vale presente.
• Adicionado o método de pagamento escolhido à sua conta Adyen .

Etapa 1: solicitar saldo do cartão vale presente

Para solicitar o saldo de um cartão vale presente:

• Faça uma solicitação POST para o endpoint da API de terminais , especificando:

  • MessageHeader: Segue a estrutura da MessageHeader padrão, explicada nos fundamentos da API de terminais, que incluem:

    • ProtocolVersion: 3.0
    • MessageCategory: BalanceInquiry
    • MessageType: Request
    • SaleID: Seu ID exclusivo para a caixa registradora.
    • ServiceID: Seu ID exclusivo para esta tentativa de transação. Este precisa ser único nas últimas 48 horas
    • POIID: ID exclusivo do terminal. Isso indica para qual terminal a transação será roteada.

  • BalanceInquiryRequest: O corpo da solicitação para a solicitação de saldo deve incluir:

    • PaymentAccountReq.PaymentInstrumentData.PaymentInstrumentType: StoredValue

    • PaymentAccountReq.PaymentInstrumentData.StoredValueAccountID: Os detalhes do cartão vale presente:

      • StoredValueAccountType: GiftCard
      • StoredValueProvider: O emissor do cartão vale presente: givex, svs, ou valuelink
      • IdentificationType: PAN

      • EntryMode, StoredValueID e ExpiryDate: Esses parâmetros dependem do metodo de leitura do cartão que você está usando.

        Leitura do cartão	Parâmetros
        Scan	EntryMode: Scanned StoredValueID: Número do cartão vale presente. ExpiryDate: Data de validade do cartão vale presente.
        Swipe or MKE	EntryMode: MagStripe StoredValueID: xxxxxxxxxxxxxxxxxxx. Não inclua o ExpiryDate parâmetro.

  O exemplo abaixo mostra como você solicitaria o saldo de um cartão vale presente que já teve suas informações digitalizadas.

  Para obter mais informações sobre a estrutura de solicitação da API de terminais, consulte os fundamentos da API de terminais.

  JSON Java

  JSON Java

  {
      "SaleToPOIRequest":{
          "MessageHeader":{
              "ProtocolVersion":"3.0",
              "MessageClass":"Service",
              "MessageCategory":"BalanceInquiry",
              "MessageType":"Request",
              "ServiceID":"9266",
              "SaleID":"POSSystemID12345",
              "POIID":"V400m-324688179"
          },
          "BalanceInquiryRequest":{
              "PaymentAccountReq":{
                  "PaymentInstrumentData":{
                      "ProtectedCardData": "1111",
                      "PaymentInstrumentType":"StoredValue",
                      "StoredValueAccountID":{
  
                          "StoredValueAccountType":"GiftCard",
                          "StoredValueProvider":"svs",
                          "IdentificationType":"PAN",
                          "EntryMode":[
                              "Scanned"
                          ],
                          "StoredValueID":"6006491260550218066",
                          "ExpiryDate":"1122"
                      }
                  }
              }
          }
      }
  }

  String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
  String saleID = "YOUR_CASH_REGISTER_ID";
  String POIID = "YOUR_TERMINAL_ID";
  
  SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
  MessageHeader messageHeader = new MessageHeader();
  messageHeader.setProtocolVersion("3.0");
  messageHeader.setMessageClass( MessageClassType.SERVICE );
  messageHeader.setMessageCategory( MessageCategoryType.BALANCE_INQUIRY );
  messageHeader.setMessageType( MessageType.REQUEST );
  messageHeader.setServiceID(serviceID);
  messageHeader.setSaleID(saleID);
  messageHeader.setPOIID(POIID);
  saleToPOIRequest.setMessageHeader(messageHeader);
  
  BalanceInquiryRequest balanceInquiryRequest = new BalanceInquiryRequest();
  PaymentAccountReq paymentAccountReq = new PaymentAccountReq();
  PaymentInstrumentData paymentInstrumentData = new PaymentInstrumentData();
  paymentInstrumentData.setPaymentInstrumentType( PaymentInstrumentType.STORED_VALUE );
  StoredValueAccountID storedValueAccountID = new StoredValueAccountID();
  storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );
  storedValueAccountID.setStoredValueProvider("svs");
  storedValueAccountID.setIdentificationType( IdentificationType.PAN );
  storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
  storedValueAccountID.setStoredValueID("6006491260550218066");
  storedValueAccountID.setExpiryDate("1122");
  paymentInstrumentData.setStoredValueAccountID(storedValueAccountID);
  paymentAccountReq.setPaymentInstrumentData(paymentInstrumentData);
  balanceInquiryRequest.setPaymentAccountReq(paymentAccountReq);
  saleToPOIRequest.setBalanceInquiryRequest(balanceInquiryRequest);
  terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

  https://docs.adyen.com/pt/pt/point-of-sale/gift-cards-terminal-api/query-the-balance#query-the-balance_0

Sua integração receberá o saldo do cartão vale presente na resposta.

Etapa 2: receber o saldo do cartão vale presente

Depois de processada, sua integração recebe uma resposta contendo o saldo do cartão vale presente. Esta é fornecido em uma resposta de API síncrona, a menos que sua integração use comunicações em nuvem assíncronas.

Se a solicitação de saldo for bem-sucedida:

• Você recebe uma resposta com um objeto BalanceInquiryResponse que inclui:

  • Response.Result: Success
  • PaymentAccountStatus.CurrentBalance: O valor do saldo do cartão vale presente.
  • PaymentAccountStatus.Currency: A moeda escolhida para a exibição do saldo do cartão vale presente.

  O exemplo abaixo indica um cartão vale presente que tem um saldo de 98.75 GBP.

  Para obter mais informações sobre a estrutura de solicitação da API de terminais, consulte os fundamentos da API de terminais.

  {
    "SaleToPOIResponse":{
      "BalanceInquiryResponse":{
        "Response":{
          "Result":"Success"
        },
        "PaymentAccountStatus":{
          "CurrentBalance":98.75,
            "PaymentAcquirerData":{
              "AcquirerPOIID":"V400m-324688179"
            },
          "Currency":"GBP"
        }
      },
      "MessageHeader":{
        "ProtocolVersion":"3.0",
        "SaleID":"POSSystemID12345",
        "MessageClass":"Service",
        "MessageCategory":"BalanceInquiry",
        "ServiceID":"9266",
        "POIID":"V400m-324688179",
        "MessageType":"Response"
      }
    }
  }

Próximos passos

Veja também