Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Realizar pagamentos com cartão vale presente

Faça pagamentos com cartão vale presente no terminal.

Depois de ativar um cartão vale presente, você poderá efetuar pagamentos com o cartão.

Efetuar um pagamento com cartão vale presente é semelhante a um pagamento com cartão de crédito ou débito, mas você precisará fornecer alguns detalhes adicionais relacionados ao cartão vale presente. Você pode coletar essas informações fazendo a leitura do cartão vale presente ou inserindo as informações manualmente em sua caixa registradora ou terminal. Quando essa solicitação de pagamento for processada, você receberá o resultado do pagamento.
Se o saldo do cartão vale presente não cobrir o valor integral do pagamento, você poderá fazer pagamentos parciais.

Antes de começar

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

Etapa 1: faça a solicitação de pagamento

Para iniciar um pagamento com 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: StoredValue
      • 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.
    • StoredValueRequest: O corpo da solicitação enviada para a solicitação de pagamento deve incluir:

      • SaleData.SaleTransactionID.TransactionID: Sua referência exclusiva para esta solicitação.
      • SaleData.SaleTransactionID.TimeStamp: Data e hora da solicitação, no formato UTC.
      • SaleData.SaleReferenceID: Parâmetro opcional para fornecer o número do seu pedido. Você pode usar isso para conectar transações diferentes de um cartão vale presente no mesmo pedido. Na Customer Area, este aparecerá como Merchant Order para a transação.
      • PaymentTransaction.AmountsReq.Currency: A moeda escolhdia para a transação.
      • PaymentTransaction.AmountsReq.RequestedAmount: O valor da transação.
      • PaymentData.PaymentInstrumentData.PaymentInstrumentType: StoredValue
      • PaymentData.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.

          Entrada 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ê iniciaria um pagamento de 10.99 GBP com 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":"Payment",
                "MessageType":"Request",
                "ServiceID":"9267",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44740",
                        "TimeStamp":"2019-03-26T09:13:41+00:00"
                    }
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"GBP",
                        "RequestedAmount":10.99
                    }
                },
                "PaymentData":{
                    "PaymentInstrumentData":{
                        "PaymentInstrumentType":"StoredValue",
                        "StoredValueAccountID":{
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "ExpiryDate":"1122"
                        }
                    }
                }
            }
        }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    PaymentRequest paymentRequest = new PaymentRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("GBP");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(100.99) );
    paymentTransaction.setAmountsReq(amountsReq);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    PaymentData paymentData = new PaymentData();
    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);
    paymentData.setPaymentInstrumentData(paymentInstrumentData);
    paymentRequest.setPaymentData(paymentData);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

A solicitação de pagamento é enviada à plataforma de pagamentos da Adyen para processamento.

Etapa 2: recebendo o resultado do pagamento

Depois de processada, sua integração recebe o resultado do pagamento. Isso é 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 o pagamento com cartão vale presente for bem-sucedido:

  • Approved será exibido na tela do terminal.
  • Você recebe uma resposta que contém um objeto PaymentResponse. Isso inclui:

    O exemplo abaixo indica que o pagamento com cartão vale presente foi bem-sucedido.

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

    {
        "SaleToPOIResponse":{
            "PaymentResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-03-26T09:22:16.000Z",
                        "TransactionID":"oLkO001522056136000.9815220561432452"
                    }
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2019-03-26T09:22:21.000Z",
                        "TransactionID":"44740"
                    }
                },
                "PaymentReceipt":[...],
                "PaymentResult":{
                    "PaymentAcquirerData":{
                        "AcquirerPOIID":"V400m-324688179",
                        "AcquirerTransactionID":{
                            "TimeStamp":"2019-03-26T09:22:16.000Z",
                            "TransactionID":"9815220561432452"
                        },
                        "MerchantID":"TestMerchantPOS"
                    },
                    "PaymentInstrumentData":{
                        "StoredValueAccountID":{
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "Scanned"
                            ],
                            "StoredValueID":"9826150911219687",
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "ExpiryDate":"1122"
                        },
                        "PaymentInstrumentType":"StoredValue"
                    },
                    "AmountsResp":{
                        "AuthorizedAmount":10.99,
                        "Currency":"GBP"
                    },
                    "PaymentType":"Normal"
                },
                "Response":{
                    "Result":"Success",
                    "AdditionalResponse":"..."
                }
            },
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "ServiceID":"9267",
                "POIID":"V400m-324688179",
                "MessageType":"Response"
            }
        }
    }

Você pode visualizar os detalhes dos pagamentos com cartão vale presente na sua Customer Area, em, Transactions > Payments.

Realizando pagamentos parciais

Se o saldo do cartão vale presente for menor que o valor da compra, você poderá permitir que o cliente pague uma parte com o cartão vale presente e a outra parte com outro cartão ou em dinheiro. Em cada solicitação de pagamento parcial, você adiciona uma tender option, para indicar que é um pagamento parcial e uma referência que permite conectar os pagamentos parciais ao mesmo pedido.

Para efetuar pagamentos parciais pora uma única venda:

  1. Verifique o saldo do cartão vale presente.
  2. Faça uma solicitação de pagamento com cartão vale presente para o saldo existente no cartão, e uma solicitação de pagamento regular para restante do valor da compra. Em cada uma dessas solicitações, especifique adicionalmente:

    • SaleData.SaleToAcquirerData: tenderOption=AllowPartialAuthorisation
    • SaleData.SaleReferenceID: Referência exclusiva, como o número de um pedido mais um número de sequência, que permite identificar pagamentos parciais que serão realizados juntos. Por exemplo, se o número do pedido for Order12345, especifique Order12345-1 na primeira solicitação de pagamento parcial e Order12345-2 na segunda solicitação de pagamento parcial. Em sua Customer Area, isso aparecerá como Merchant Order para o pagamento.

    Este exemplo mostra esses parâmetros adicionais em uma solicitação de pagamento parcial com cartão vale presente.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
            ...
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"44740",
                        "TimeStamp":"2019-03-26T09:13:41+00:00"
                    },
                    "SaleToAcquirerData":"tenderOption=AllowPartialAuthorisation",
                    "SaleReferenceID":"YOUR_ORDER_REFERENCE"
                },
                "PaymentTransaction":{
                    ...
                },
                "PaymentData":{
                    "PaymentInstrumentData":{
                        "PaymentInstrumentType":"StoredValue",
                        "StoredValueAccountID":{
                            ...
                        }
                    }
                }
            }
        }
    }

Os pedidos de pagamento são enviados para a plataforma de pagamentos da Adyen para processamento. Depois de processada, sua integração recebe o resultado do pagamento.

Próximos passos

Veja também