Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Verifique o saldo de um cartão vale presente

Consulte o saldo de um cartão vale presente em seu terminal.

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:

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.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"BalanceInquiry",
                "MessageType":"Request",
                "ServiceID":"9266",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "BalanceInquiryRequest":{
                "PaymentAccountReq":{
                    "PaymentInstrumentData":{
                        "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);

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 sua integração usar comunicações em nuvem assíncronas, você receberá o resultado em uma notificação de exibição TENDER_FINAL

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