APIs

Interface Paykit

A interface Paykit define os métodos que cada adquirente deve implementar para realizar transações de pagamento.

Métodos

Método	Descrição	Parâmetros	Retorno
activate	Ativa o SDK com os parâmetros fornecidos. Executar apenas 1 (uma) vez ou quando o terminal é realocado para outra loja.	activationParameters	ActivationResult
credit	Realiza uma transação de crédito.	creditParameters	PaymentResult
debit	Realiza uma transação de débito.	debitParameters	PaymentResult
voucher	Processa um pagamento por meio de voucher.	voucherParameters	PaymentResult
pix	Processa um pagamento via PIX.	paymentParameters	PaymentResult
wallet*	Processa um pagamento utilizando carteira digital.	paymentParameters	PaymentResult
qrCode*	Processa um pagamento utilizando QR Code.	paymentParameters	PaymentResult
fleet*	Realiza uma transação com cartão frotas.	fleetParameters	PaymentResult
cancel	Cancela uma transação.	cancelParameter	CancelResult
preAuthorize*	Realiza uma transação de pré-autorização.	creditParameters	PaymentResult
capturePreAuthorization*	Captura o valor de uma pré-autorização.	pendingPreParameters	PaymentResult
cancelPreAuthorization*	Cancela uma transação de pré-autorização.	pendingPreParameters	CancelResult
confirmPendingTransaction*	Confirma uma transação. Chamar manualmente quando autoConfirm = false.	pendingTransactionParameters	Boolean
undoPendingTransaction*	Desfaz uma transação. Chamar manualmente quando autoConfirm = false.	pendingTransactionParameters	Boolean
printLastReceipt	Imprime o último recibo.	receiptType	PrintResult
printReceipt*	Imprime recibo específico.	printReceiptParameters	PrintResult
print	Imprime uma imagem bitmap.	bitmap	PrintResult
retrieveSdkInfo	Recupera informações sobre o SDK.	-	Map<String, String>
startPayment	Executa o fluxo genérico de pagamentos do SDK.	paymentParameters	PaymentResult
getLastTransaction*	Recupera informações da última transação.	-	TransactionQueryResult
getTransaction*	Recupera informações de uma transação.	transactionParameters	TransactionQueryResult
executeAdminOperation*	Abre menu com operações administrativas.	operation	AdminOperationResult

nota

*Alguns provedores/adquirentes não possuem essas operações.

Exemplo de uso básico

import com.linx.paykit.core.Paykit
import com.linx.paykit.core.PaykitFactory
import com.linx.paykit.common.builder.Parameters
import com.linx.paykit.common.parameter.PaykitId

class MainActivity : AppCompatActivity() {
    private lateinit var paykit: Paykit

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Inicializa o SDK
        paykit = PaykitFactory().build(
            Parameters(
                this,
                "Nome da Aplicação",
                PaykitId("SEU_PAYKIT_ID")
            )
        )
    }
}

Ativação do Terminal

Parâmetros de Ativação

Campo	Tipo	Descrição
storeCnpj	String	Documento da loja que está sendo feita a ativação
tef	TefActivationParameters	Parâmetros de ativação para o provedor TEF
pagSeguro	PagSeguroActivationParameters	Parâmetros de ativação para o provedor PagSeguro
sitef	SitefActivationParameters	Parâmetros de ativação para o provedor SiTef
tipoServidor	TipoServidor	Tipo servidor TEF que está sendo utilizado na ativação (LinxTef ou SiTef). Define o comportamento do provedor TEF se é Linx TEF ou SiTef.
isSubAcquirer	Boolean	Ativação da loja está sendo modelo de subadquirência ou não
subAcquirer	SubAcquirerParameters	Parâmetros de subadquirência

val activationParams = ActivationParameters(
    storeCnpj = "123456789"
    tef = TefActivationParameters(
        production = false,
        token = "XXXX" // Token de ativação do TEF fornecido no processo de integração.
    )
)

paykit.activate(activationParams, object : Callback<ActivationResult> {
    override fun execute(result: ActivationResult?) {
        if (result?.success == true) {
            // Terminal ativado com sucesso
            Log.i("Activation", "Terminal ativado")
        } else {
            // Erro na ativação
            Log.e("Activation", "Erro: ${result?.message}")
        }
    }
})

Resultado da Ativação

Campo	Tipo	Descrição
processor	PaymentProcessor?	Indica o processador da transação (STONE, TEF, REDE, GETNET, PAGSEGURO, VERO, CIELO, SICOOB, SITEF).
dateTime	Date?	Representa data e hora da transação.
success	Boolean	Indica se a ativação foi bem-sucedida
message	String	Mensagem de retorno (sucesso ou erro)
rawData	String	Número de série do terminal

Pagamento

Parâmetros de Pagamento

O objeto PaymentParameters, utilizado em transações de pagamento. Algumas transações possuem parâmetro específicos: CreditParameters, DebitParameters, VoucherParameters ou FleetParameters. Veja sua respectiva documentação em cada transação.

Campo	Tipo	Descrição
amount	BigDecimal	O valor total da transação.
installments	Int?	O número de parcelas para pagamento. Este campo é opcional de acordo com o tipo e modalidade do pagamento.
cpf	String?	CPF do cliente, se aplicável. Este campo é opcional.
billOfSale	String?	Documento de venda associado à transação. Este campo é opcional.
dateTimeOfSale	Date?	Data e hora em que a venda foi realizada. Este campo é opcional.
externalId	String?	Identificador externo para a transação. Este campo é opcional.
items	List<OrderItem>?	Lista dos items de venda, relacionados a transação a ser realizada. Este campo é opcional.
autoPrintReceipt	Boolean	Imprime automaticamente o comprovante do lojista quando o processador da transação é o TEF.
printMerchantReceipt	Boolean	Imprime (ou não) o recibo do lojista. Utilizar apenas em totens de auto atendimento.
autoConfirm	Boolean?	Envia a confirmação automaticamente. Só utilizada quando o processador da transação é o TEF
postCreditDays	Int?	Prazo para a primeira parcela, em dias. Este campo é opcional.
creditType	CreditTransactionType?	Modalidade da transação de crédito.
autoConfirm	Boolean?	Envia a confirmação automaticamente. Só utilizada quando o processador da transação é o TEF

val paymentParams = PaymentParameters(
    amount = BigDecimal("10.00"),
    externalId = "ORDER_123456"
)

paykit.pix(paymentParams, object : Callback<PaymentResult> {
    override fun execute(result: PaymentResult) {
        if (result?.status == TransactionStatus.APPROVED) {
            Log.i("Payment", "Pagamento aprovado: ${result.id}")
        } else {
            Log.e("Payment", "Pagamento negado: ${result?.message}")
        }
    }
})

Tipos de Pagamento

Tipo	Descrição
CREDIT	Pagamento com cartão de crédito
DEBIT	Pagamento com cartão de débito
VOUCHER	Pagamento com cartão benefício
PIX	Pagamento via Pix
WALLET	Pagamento com carteira digital
FLEET	Pagamento com cartão frotas
QR_CODE	Pagamento com QR Code

Resultado do Pagamento

Campo	Tipo	Descrição
id	String?	Identificador único da transação.
externalId	String?	Identificador externo para a transação.
processor	PaymentProcessor?	Indica o processador da transação (STONE, TEF, REDE, GETNET, PAGSEGURO, VERO, CIELO, SICOOB, SITEF).
status	TransactionStatus	Status da transação (PENDING, APPROVED, CANCELLED, PARTIALLY_CANCELLED, ERROR, DECLINED).
amount	BigDecimal?	Representa o valor da transação original.
message	String?	Mensagem de sucesso ou erro, caso aplicável.
dateTime	Date?	Representa data e hora da transação.
nsuInfo	NsuInfo?	Representa dados de NSU do retorno transacional do provedor de pagamentos.
transactionInfo	TransactionInfo?	Representa dados de retorno transacional do provedor de pagamentos.
rawData	Map<String, String>?	Retorno estilo chave/valor recebido do provedor de pagamentos.
paymentType	PaymentType?	Tipo da transação de pagamento (Crédito, Débito, Voucher, Pix, etc.).
transactionType	TransactionType?	Modalidade da transação de crédito, débito, ou voucher, quando disponível.

Cancelamento

Parâmetros de Cancelamento

O objeto CancelParameter, utilizado em transações de cancelamento.

Campo	Tipo	Descrição
paymentId	String	Identificador da transação de pagamento que será cancelada.
externalId	String?	Identificador da automação comercial para a transação. Utilizado para posterior conciliação. Este campo é opcional.
amount	BigDecimal?	O valor total da transação de pagamento que será cancelada. Este campo é opcional.
originalPaymentType	PaymentType?	Modalidade (débito, crédito, voucher, Pix, etc.) da transação de pagamento. Este campo é opcional.
originalTransactionDate	Date?	Data em que a transação de pagamento foi realizada. Este campo é opcional.
cancelAmount	BigDecimal?	O valor que será cancelado da transação para cancelamento parcial. Este campo é opcional.
autoPrintReceipt	Boolean	Imprime automaticamente o comprovante do lojista quando o provedor de pagamento é o TEF.
printMerchantReceipt	Boolean	Imprime (ou não) o recibo do lojista. Utilizar apenas em totens de auto atendimento.
autoConfirm	Boolean?	Envia a confirmação automaticamente. Só utilizada quando o provedor de pagamento é o TEF. Este campo é opcional.

val cancelParams = CancelPaymentParameters(
    transactionId = "123456", // NSU da transação
    amount = BigDecimal("10.00") // Valor a ser cancelado
)

paykit.cancelPayment(cancelParams, object : Callback<CancelPaymentResult> {
    override fun execute(result: CancelPaymentResult?) {
        if (result?.success == true) {
            Log.i("Cancel", "Cancelamento aprovado")
        } else {
            Log.e("Cancel", "Erro no cancelamento: ${result?.message}")
        }
    }
})

Resultado do cancelamento

Campo	Tipo	Descrição
id	String?	Identificador único da transação.
externalId	String?	Identificador externo para a transação.
processor	PaymentProcessor?	Indica o processador da transação (STONE, TEF, REDE, GETNET, PAGSEGURO, VERO, CIELO, SICOOB, SITEF).
status	TransactionStatus	Status da transação (PENDING, APPROVED, CANCELLED, PARTIALLY_CANCELLED, ERROR, DECLINED).
amount	BigDecimal?	Representa o valor da transação original.
originalId	String?	Identificador da transação original.
canceledAmount	BigDecimal	Representa o valor da transação de cancelamento. Diferente de amount quando o cancelamento é parcial.
message	String?	Mensagem de sucesso ou erro, caso aplicável.
dateTime	Date?	Representa data e hora da transação.
nsuInfo	NsuInfo?	Representa dados de NSU do retorno transacional do provedor de pagamentos.
transactionInfo	TransactionInfo?	Representa dados de retorno transacional do provedor de pagamentos.
rawData	Map<String, String>?	Retorno estilo chave/valor recebido do provedor de pagamentos.
paymentType	PaymentType?	Tipo da transação de pagamento (Crédito, Débito, Voucher, Pix, etc.).
transactionType	TransactionType?	Modalidade da transação de crédito, débito, ou voucher, quando disponível.

Operações Administrativas

Tipos de Operações

Operação	Descrição
SHOW_MENU	Mostra menu com funções administrativas
GET_GIFT_CARD_BALANCE	Consulta saldo de cartão presente
REFUND_GIFT_CARD_AMOUNT	Resgate de cartão presente
BILL_PAYMENT	Pagamento de contas

Exemplo

paykit.executeAdminOperation(AdminOperation.SHOW_MENU, object : Callback<AdminOperationResult> {
    override fun execute(result: AdminOperationResult?) {
        if (result?.success == true) {
            Log.i("Admin", "Operação realizada com sucesso")
        }
    }
})

Resultado da operação administrativa

Campo	Tipo	Descrição
success	Boolean?	Indica se a operaçao foi bem-sucedida.
status	SitefErrorCode?	Status da operação.
operation	AdminOperation?	Operação administrativa que foi realizada.
processor	PaymentProcessor?	Indica o processador da transação (STONE, TEF, REDE, GETNET, PAGSEGURO, VERO, CIELO, SICOOB, SITEF).
dateTime	Date?	Representa data e hora da transação.
message	String?	Mensagem de sucesso ou erro, caso aplicável.
rawData	Map<String, String>?	Retorno estilo chave/valor recebido do provedor de pagamentos.