Pular para o conteúdo principal

Pagamentos

Métodos do PosPinpad para pagamentos com cartão, voucher, PIX e captura de cartão.

createPayment()​

suspend fun createPayment(
    type: TransactionType,
    amount: Long,
    paymentMethod: PaymentMethod?,
    installments: Int,
    installmentsInterest: Boolean? = false,
    metadata: TransactionMetadata = TransactionMetadata.EMPTY
)

Inicia o fluxo de pagamento completo (captura de cartão → PIN → processamento → resultado). O resultado chega em onTransactionCompleted.

Parâmetros:

ParâmetroTipoDescrição
typeTransactionTypeAUTHORIZATION (venda) ou PRE_AUTHORIZE (pré-autorização)
amountLongValor em centavos (1000 = R$ 10,00)
paymentMethodPaymentMethod?CREDIT, DEBIT ou VOUCHER. null deixa o tipo ser definido pelo cartão. PIX usa createPixPayment
installmentsIntNúmero de parcelas (1 = à vista). Ignorado em VOUCHER
installmentsInterestBoolean?true = parcelado com juros (emissor); false = sem juros (lojista). Ignorado em VOUCHER
metadataTransactionMetadataDados do app que seguem até o gateway. Veja Configuração

O terminal escolhe o adquirente pela bandeira e pelo produto do cartão. O nome de quem processou volta em receipt.acquirerName.

Sem terminalInitialization(), a chamada dispara onAppError(SdkErrorCode.TERMINAL_NOT_INITIALIZED, ...) e lança IllegalStateException.

Fluxo de callbacks (cartão):

  1. onStartGetCard() — aguardando cartão; instruções ao portador chegam por onUiNotify
  2. onRequestMenuSelection(...) / onRequestUserInput(...) — quando o cartão exige escolha ou dado do operador
  3. onStartGetPinCoordinates(setPinCoordinates) — só na primeira senha do processo: o app fornece as coordenadas do PIN
  4. onPinEntry(pinMask, message, amount) — atualização da máscara
  5. onPinError(...) — senha offline incorreta (se aplicável)
  6. onTransactionCompleted(result) — resultado final
  7. Se result.requiresCardRemoval for true (cartão lido pelo chip, em qualquer status), chame removeCard() e peça a retirada

Exemplos:

// Crédito à vista — R$ 50,00
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 5000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 1
)

// Crédito parcelado — R$ 300,00 em 3x sem juros
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 30000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 3,
    installmentsInterest = false
)

// Débito — R$ 25,00
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 2500L,
    paymentMethod = PaymentMethod.DEBIT,
    installments = 1
)

// Voucher — R$ 25,00 (sempre à vista)
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 2500L,
    paymentMethod = PaymentMethod.VOUCHER,
    installments = 1
)

// Pré-autorização — R$ 100,00
posPinpad.createPayment(
    type = TransactionType.PRE_AUTHORIZE,
    amount = 10000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 1
)

Voucher​

Voucher é sempre à vista: com paymentMethod = VOUCHER, o SDK força 1 parcela sem juros e ignora installments e installmentsInterest. Ofereça a opção só quando getAvailableProducts(PaymentMethod.VOUCHER) não vier vazia. O saldo, quando a adquirente informa, vem em result.voucherBalance, inclusive em vendas negadas.

createPixPayment()​

suspend fun createPixPayment(amount: Long, metadata: TransactionMetadata = TransactionMetadata.EMPTY)

Gera um pagamento PIX (QR Code). O payload chega por onPixQrCodeGenerated(qrCode, transactionId, amount, expiresInSeconds).

  • PIX aprovado chega em onTransactionCompleted.
  • QR Code expirado, inválido, não autorizado ou não pago dentro da validade chega como onAppError(SdkErrorCode.PP_CANCEL, mensagem), com o motivo em mensagem.
  • O terminal acompanha o pagamento enquanto o QR Code for válido (validade definida pelo backend, informada em expiresInSeconds; 2 minutos quando não informada), mais alguns segundos de folga.

Para cancelar um PIX, cancele o Job da coroutine que chamou createPixPayment (cancelPayment() não interrompe o PIX). O SDK continua consultando o status em segundo plano, para não perder um pagamento feito no último instante.

pixJob = lifecycleScope.launch { posPinpad.createPixPayment(2000L) }
// Operador desistiu
pixJob?.cancel()

cancelPayment()​

fun cancelPayment()

Cancela a leitura de cartão em andamento e libera qualquer espera por cartão, coordenadas ou senha. O fluxo termina com onAppError(SdkErrorCode.PP_CANCEL, ...). Não cancela o PIX (veja createPixPayment()) e não há o que cancelar depois que a transação foi enviada ao autorizador. Exige o terminal inicializado.

getTransactionLimits()​

fun getTransactionLimits(
    transactionType: TransactionType,
    paymentMethod: PaymentMethod,
    installments: Int = 1
): TransactionLimits?

Consulta os limites configurados para uma operação (valor mín./máx., parcelas, valor por parcela), derivados da inicialização. É local: sem rede e sem cartão. Use antes de iniciar o pagamento para validar localmente.

  • Retorna null quando a combinação não tem limite configurado ou a carga não foi feita. Apenas CREDIT/DEBIT retornam valores.
  • Nos limites retornados, campos com 0 significam "sem limite": compare só quando o limite for maior que zero.
val limites = posPinpad.getTransactionLimits(TransactionType.AUTHORIZATION, PaymentMethod.CREDIT, installments = 3)
val acimaDoMaximo = limites != null &&
    limites.maxTransactionValueCents > 0 && valor > limites.maxTransactionValueCents

Veja TransactionLimits e o exemplo completo em Exemplos.

getAvailableProducts()​

fun getAvailableProducts(paymentMethod: PaymentMethod): List<ProductInfo>

Produtos da carga de inicialização para o tipo informado. getAvailableProducts(PaymentMethod.VOUCHER) só devolve produtos quando a carga habilita voucher para o estabelecimento (merchant.voucherEnabled = true) e traz produtos voucher. Caso contrário, a lista vem vazia: não ofereça a opção.

Captura de Cartão​

waitForCard()​

suspend fun waitForCard(
    waitContact: Boolean,
    waitMagneticStripe: Boolean,
    waitContactless: Boolean,
    timeoutSeconds: Int
): CardReadType?

Aguarda um evento de cartão fora de um fluxo de pagamento por até timeoutSeconds. Retorna o tipo de leitura (CHIP, CONTACTLESS, MAGSTRIPE) ou null no timeout. Útil para melhorar a UX antes de iniciar a transação.

removeCard()​

suspend fun removeCard()

Aguarda a retirada do cartão de chip. Chame sempre que result.requiresCardRemoval for true — inclusive em transações negadas ou com erro.

O tempo de espera do cartão nos fluxos de pagamento é configurável com setCardReadTimeouts. Veja Configuração.

Nesta página