O objetivo desse SDK é facilitar a integração, abstraindo toda a complexidade envolvida com os protocolos de comunicação com a API. Com esse SDK, o desenvolvedor precisará apenas utilizar alguns métodos e fornecer os dados informados pelo cliente, para executar quaisquer operações suportadas pelo SDK.
Esse SDK utiliza licença livre MIT. A licença pode ser lida abaixo e no arquivo LICENSE, localizado na raiz desse SDK.
MIT License
Copyright (c) 2021 EntrePayments
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- Autorização com captura
- Autorização com captura e definição do softdescriptor
- Autorização sem captura - pré-autorização
- Autorização e tokenização do cartão
- Autorização com parcelamento
- Verificação de cartão - transação zero dolar
- Captura posterior
- Captura posterior parcial
- Cancelamento/reembolso
- Desfazimento/void
- Consulta
- 3DS
Tanto a autorização com captura quanto a autorização sem captura suportam parcelamentos.
A instância de EntrePayments é a base de todas as operações da API; por isso o desenvolvedor precisará informar suas chaves:
String merchantKey = "<sua-merchant-key>";
String merchantCode = "<seu-merchant-code>";
String terminal = "1";
EntrePayments entrePayments = EntrePayments.create(
new Merchant(
merchantKey,
merchantCode,
terminal
)
);Com a instância de EntrePayments criada, o processo é fluído; para autorizar e capturar uma transação, basta definir o parâmetro capture como true:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
$orderNumber,
$orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
)
);Softdescriptor é o nome que aparece na fatura do cartão do cliente. Definir esse nome é útil para facilitar que o cliente identifique a origem da transação, evitando, assim, eventuais chargebacks.
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
EntrePayments $payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
),
"LOJATESTE"
)
);Assim como a autorização com captura basta definir o parâmetro capture como true, a sem captura basta definir o parâmetro capture como false:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
),
false
);Durante o processo de autorização - com ou sem captura - é possível tokenizar o cartão para ser utilizado posteriormente. É o famoso one click payment, que permite que a loja armazene um token do cartão para compras futuras.
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
$orderNumber,
$orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
)
,
true,
true
);
String token = payment.getCard().getIdentifier();A tokenização funciona sem captura também:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
$orderNumber,
$orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
)
,
false,
true
);
String token = payment.getCard().getIdentifier();A variável $token conterá um hash que poderá ser armazenado de forma segura pela loja. Numa futura compra, será possível autorizar uma nova compra utilizando o token em vez dos dados do cartão do cliente:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.token("token-gerado-em-uma-transação-anterior")
)
);Também é possível definir o parcelamento de uma transação. O exemplo abaixo vai autorizar um pagamento em 12 vezes e vai gerar um token do cartão para ser utilizado em compras futuras.
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
).setInstallments(12),
true,
true
);
String token = payment.getCard().getIdentifier();Durante um processo de assinatura, é normal que a loja precise verificar o cartão do cliente. Para isso, é possível criar uma transação zeroDolar:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.zeroDolar(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
)
);Ao chamar o método zeroDolar, a classe EntrePayments vai definir o valor do pedido para 0 e vai enviar uma requisição para a API. Isso verificação se o cartão está ativo e se a loja poderá seguir com a venda, assinatura, etc. Um caso de uso para esse tipo de transação, é quando a loja está vendendo uma assinatura e só vai fazer a autorização ao final de um período; dessa forma, o cliente informa seus dados de cartão e é feita a verificação do cartão.
Um caso de uso comum para a pré-autorização, é em reservas. Por exemplo, o cliente reserva um quarto e faz checkin no hotel; nesse momento, o hotel faz a pré-autorização:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
),
false
);Perceba o capture: false, que garante apenas a autorização. Quando o cliente faz o checkout, o hotel verifica consumo e outros e faz a captura do valor:
Payment payment = entrePayments.capture(
new Payment(
new Order(
orderNumber,
orderAmount
)
)
);Na pré-autorização, o valor é apenas travado no limite do cartão do cliente; somente após a captura que o valor é deduzido do limite do cliente.
Pode ocorrer de o valor que se deseja capturar ser menor daquele que foi autorizado previamente. Nesse caso, o estabelecimento precisa informar o valor que deseja capturar:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4548812049400004",
"2023",
"12",
"Nome do portador",
"123"
)
),
false
);
// Em um segundo momento
payment = entryPayments.capture(
new Payment(
new Order(
orderNumber,
orderAmount - 100
)
)
);O cancelamento, ou reembolso, pode ocorrer após uma autorização ter sido capturada. Um detalhe importante aqui, é que a transação precisa ter sido capturada; caso a transação não tenha sido capturada, será necessário fazer um desfazimento/void.
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4761120000000148",
"34",
"12",
"Fulano de tal",
"123"
)
)
);
payment = entrePayments.cancel(
new Payment(
new Order(
orderNumber,
orderAmount
)
)
);O desfazimento ou void acontece quando é feita uma autorização sem que se tenha feito a captura.
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.voidPayment(
new Payment(
new Order(
orderNumber,
orderAmount
)
)
);Todas as transações e pagamentos de determinado pedido, podem ser consultados. Para isso, basta executar o método consult:
String orderNumber = "1234-pedido";
Integer orderAmount = 123;
Payment payment = entrePayments.authorize(
(new Payment(
new Order(
orderNumber,
orderAmount
),
Card.creditCard(
"4761120000000148",
"34",
"12",
"Fulano de tal",
"123"
)
))
);
payment = entrePayments.consult(
new Payment(
new Order(
orderNumber,
orderAmount
)
),
Payment.AUTHORIZATION_WITHOUT_3DS
);