Documentação RockSDK v2.1
O RockSDK é uma biblioteca de pagamentos projetada para simplificar a integração com métodos como Cartão de Crédito, PIX, NuPay e PIX Parcelado. Construído sobre o Yuno SDK v1.5, ele gerencia a complexidade da tokenização e processamento de pagamentos, oferecendo fluxos Headless (controle total da UI) e Lite (modais prontos).
Instalação#
Você pode integrar o RockSDK em sua aplicação web via CDN ou como um módulo ES (ESM).Via CDN (Script Tag)#
Ideal para aplicações simples ou que não utilizam bundlers modernos.Via NPM / ESM#
Ideal para aplicações React, Vue, Angular ou qualquer projeto com suporte a módulos.
Configuração#
Para funcionar corretamente, o SDK precisa de chaves de configuração. Você pode defini-las globalmente no objeto window.env antes ou depois de carregar o script.| Variável | Descrição |
|---|
ROCK_SDK_PUBLIC_KEY | Chave pública para comunicação com o provedor de pagamentos. |
ROCK_SDK_PAYMENT_BASE_URL | URL base da API de processamento de pagamentos. |
Guia de Uso#
1. Inicialização#
A inicialização carrega os scripts necessários do Yuno de forma assíncrona. É seguro chamar init() múltiplas vezes.2. Preparando os Dados do Cliente#
Antes de processar um pagamento, você precisa formatar os dados do cliente. Utilize o método getCustomerData para normalizar as informações recebidas do seu formulário.3. Processando Pagamentos#
O método processPayment é o coração da integração. Ele se adapta automaticamente conforme o método escolhido:Fluxo Headless (Cartão/PIX): O SDK processa os dados e retorna o resultado diretamente.
Fluxo Lite (NuPay/PIX Parcelado): O SDK abre um modal seguro gerenciado pelo Yuno para que o cliente finalize o pagamento.
Referência da API#
Métodos Principais#
| Método | Parâmetros | Retorno | Descrição |
|---|
init() | — | Promise<void | null> | Inicializa o SDK. Deve ser chamado antes de outras operações. |
getSDKStatus() | — | { isLoaded, isLoading, hasInstance, hasWindowYuno, sdkUrl, yunoInstance } | Retorna o status atual do SDK. |
getCustomerData(values) | values (Object) | RockSdkCustomerInfo | Normaliza os dados brutos do formulário para o formato esperado pelo SDK. |
processPayment(data, paymentMethod, callbacks?, onLoading?, callbackUrl?) | ver abaixo | { success: boolean, message?: string, status?: string, checkoutSession?: string, pending?: boolean } | Inicia o fluxo de pagamento. |
checkPaymentStatus(preOrderId) | preOrderId (String) | Promise<'SUCCEEDED' | 'DECLINED' | 'PENDING'> | Consulta o status final de uma transação. |
Retorno de getSDKStatus()#
{
"isLoaded": "<boolean>",
"isLoading": "<boolean>",
"hasInstance": "<boolean>",
"hasWindowYuno": "<boolean>",
"sdkUrl": "",
"yunoInstance": "<RockSdkYunoInstance>"
}
Métodos Auxiliares#
generateTokenParams(values, index)#
Gera os parâmetros necessários para tokenização de um cartão. Útil se você implementar seu próprio fluxo de tokenização separado.values = {
creditCard1?: RockSdkCreditCard // { card_expiration_month?, card_expiration_year?, holder_name?, number?, cvv? }
creditCard2?: RockSdkCreditCard
primaryPrecification?: { pricingModel: string }
}
index = 1 | 2
{
cardDetails: RockSdkCardDetails // { expiration_month, expiration_year, number, cvv, holder_name }
customerInfo: RockSdkCustomerInfo
isSubscription: boolean
}
getCardToken(cardDetails, customerInfo, isSubscription)#
Realiza a tokenização direta do cartão via Yuno Headless.cardDetails: {
expiration_month: number
expiration_year: number
number: string
cvv: string
holder_name: string
}
customerInfo: RockSdkCustomerInfo
isSubscription: boolean
{
acquirer: string
value: string
session: string
customerId: string
}[]
createCheckoutSession(customerInfo)#
Cria uma sessão de checkout no backend.customerInfo: RockSdkCustomerInfo
{
sessionId: string
customerId: string
}
Métodos de Pagamento Suportados#
O SDK suporta os seguintes valores para o parâmetro paymentMethod em processPayment:| Valor | Descrição |
|---|
creditCard | Pagamento padrão com cartão de crédito. O SDK realiza a tokenização segura dos dados do cartão. |
pix | Gera um código QR Pix para pagamento instantâneo. |
nuPay | Abre o modal de pagamento da Yuno, permitindo que o cliente use saldo ou cartões salvos na conta NuPay. |
pixParcelado | Abre o modal de pagamento da Yuno para permitir o parcelamento via PIX. |
TypeScript#
Se você estiver utilizando TypeScript, o SDK exporta tipos para ajudar na validação dos dados.import type {
RockSdkType,
RockSdkPaymentMethod,
RockSdkCustomerDataValues,
RockSdkPaymentResult
} from 'rock-sdk'
// Exemplo de tipagem de um handler
const handlePayment = async (values: RockSdkCustomerDataValues) => {
const sdk = window.RockSdk as RockSdkType
// ...
}
Tipos Principais#
type RockSdkCustomerInfo = {
name: string
email: string
document: RockSdkCustomerDocument | string
telephone: RockSdkCustomerTelephone | string
address: RockSdkCustomerAddress | string
metadata: RockSdkCustomerMetadataItem[]
visitorId: { fingerprint: string }
}
type RockSdkCardDetails = {
expiration_month: number
expiration_year: number
number: string
cvv: string
holder_name: string
}
type RockSdkCreditCard = {
card_expiration_month?: string
card_expiration_year?: string
holder_name?: string
number?: string
cvv?: string
}
Modificado em 2026-03-18 15:45:34
