window.RockSdk.</body>. Após o carregamento, window.RockSdk estará disponível globalmente.init():init() uma vez antes de usar qualquer outro método do SDK. É seguro chamar múltiplas vezes — chamadas concorrentes compartilham a mesma promise de inicialização.Pagamento único ou assinatura? Entenda o isSubscriptionO valor de isSubscriptiondetermina o tipo de token gerado e deve refletir o modelo de cobrança do seu produto:false— token para pagamento único (compra avulsa)true— token para assinatura/recorrência (cobranças periódicas)Usar o valor incorreto fará com que o token seja recusado pelo processador. O SDK define esse valor automaticamente com base em primaryPrecification.pricingModeldentro doformValues— certifique-se de que esse campo está correto antes de chamargenerateTokenParams.
formValues para generateTokenParamsgenerateTokenParams lê os dados do cartão e do cliente a partir de um objeto formValues plano. O formato esperado é:customerInfo separadamente com getCustomerData() e passar apenas os dados do cartão para generateTokenParams. Consulte getCustomerData abaixo.callbackUrl— obrigatório para PIX ParceladoDurante o pagamento, o usuário é redirecionado para fora do seu site (app da Pagaleve). O callbackUrlé a URL para onde ele será devolvido após concluir ou cancelar o pagamento no app externo.Sem esse parâmetro definido corretamente, o usuário ficará preso no app da Pagaleve sem conseguir retornar ao seu site. Você pode passar qualquer URL que faça sentido para o seu fluxo, por exemplo: A própria página do checkout ( window.location.href)Uma página de status/pendente do seu sistema ( 'https://meusite.com/pedido/pendente')Uma URL padrão do seu e-commerce para retorno de pagamentos externos
Como funciona onPaymentSuccess1ª chamada — ocorre após o pedido ser criado no backend. payload.paymentResponse.processCartestá presente. Salve oiddo pedido aqui.2ª chamada — ocorre apenas se o pagamento for confirmado sem sair da página (ex: aprovação imediata). payload.status === 'SUCCEEDED'estará presente.No fluxo típico do PIX Parcelado, o usuário é redirecionado para o app da Pagaleve e a página é fechada — a 2ª chamada não ocorre. O resultado do pagamento é consultado na página de retorno com recoverOrderFromRedirect.
recoverOrderFromRedirect + pollPaymentStatus para consultar o resultado:paymentMethod ('nuPay') e que o redirecionamento externo vai para o app do Nubank.callbackUrl— obrigatório para NuPayO mesmo princípio do PIX Parcelado se aplica aqui: o usuário é redirecionado para o app do Nubank e precisa de uma URL para retornar ao seu site. Passe qualquer URL adequada ao seu fluxo — a página do checkout, uma página de status pendente ou uma URL padrão de retorno do seu e-commerce.
onPaymentSuccess e o padrão de recuperação após redirecionamento são idênticos ao do PIX Parcelado — consulte a seção 2.checkPaymentStatus para verificar o estado final de um pedido. O método nunca lança exceção — erros de rede retornam 'PENDING'.| Retorno | Significado |
|---|---|
'SUCCEEDED' | Pagamento aprovado |
'DECLINED' | Pagamento recusado |
'PENDING' | Ainda processando, ou erro de rede — tente novamente |
pollPaymentStatusorderStatus completo retornado pela API:pollPaymentStatus também aceita { checkoutSession } como primeiro argumento, da mesma forma que checkPaymentStatus.recoverOrderFromRedirect para recuperar o pedido automaticamente. O SDK lê pid e checkoutSession da URL e resolve o preOrderId via mapeamento interno (localStorage).Persistência automática: O SDK persiste automaticamente o mapeamento checkoutSession → preOrderIdno localStorage durante oprocessPayment. Você não precisa fazer isso manualmente no callbackonPaymentSuccess.
getOrderStatusgetOrderStatus para verificar o status a qualquer momento — após um timeout de polling, em um botão "Verificar novamente", ou em qualquer outro ponto do fluxo. Retorna o objeto orderStatus completo.| Método | Assinatura | Retorno |
|---|---|---|
init | (): Promise<void> | Resolve quando o SDK está pronto |
getSDKStatus | (): RockSdkSDKStatus | Estado atual do SDK |
getCustomerData | (values: RockSdkCustomerDataValues): RockSdkCustomerInfo | Dados normalizados do cliente |
createCheckoutSession | (customerInfo: RockSdkCustomerInfo): Promise<RockSdkSession> | { sessionId, customerId } |
generateTokenParams | (values: RockSdkTokenParamsValues, index?: 1 | 2): Promise<RockSdkTokenParams> | Parâmetros prontos para getCardToken |
getCardToken | (cardDetails, customerInfo, isSubscription?): Promise<RockSdkCardToken[]> | Array com um token |
processPayment | (data, paymentMethod, callbacks?, onLoading?, callbackUrl?): Promise<RockSdkPaymentResult> | Resultado do pagamento |
checkPaymentStatus | (params: string | { preOrderId?, checkoutSession? }): Promise<'SUCCEEDED' | 'DECLINED' | 'PENDING'> | Status do pedido |
pollPaymentStatus | (params: string | { preOrderId?, checkoutSession? }, options?): RockSdkPollingController | Polling nativo com callbacks |
getOrderStatus | (params: string | { preOrderId?, checkoutSession? }): Promise<RockSdkOrderStatus> | Consulta manual do status completo |
recoverOrderFromRedirect | (): RockSdkRecoveredOrder | null | Recupera pedido após redirect externo |
getCustomerDatadocument,telephoneeaddressaceitam tanto um objeto estruturado quanto uma string simples (ex: CPF diretamente como string).
type RockSdkPaymentMethod = 'creditCard' | 'pix' | 'nuPay' | 'pixParcelado'
type RockSdkCardDetails = {
expiration_month: number // ex: 3
expiration_year: number // ex: 2028
number: string // número completo do cartão, sem espaços
cvv: string
holder_name: string
}
type RockSdkCreditCard = {
card_expiration_month?: string // ex: '03'
card_expiration_year?: string // ex: '2028'
holder_name?: string
number?: string
cvv?: string
}
type RockSdkCustomerDocument = {
number: string
countryCode?: string // ex: 'br'
}
type RockSdkCustomerTelephone = {
number: string // ex: '11999999999'
dialCode: string // ex: '+55'
countryCode: string // ex: 'br'
}
type RockSdkCustomerAddress = {
street: string
number: string
district: string
city: string
state: string // ex: 'SP'
postalCode: string // ex: '01310000'
country: string // ex: 'BR'
}
type RockSdkMetadata = {
name?: string
key: string
value: string
isDynamic?: boolean // se true, lê o valor de window.location.search
}
type RockSdkCustomerDataValues = {
name?: string
email?: string
document?: RockSdkCustomerDocument | string
telephone?: RockSdkCustomerTelephone | string
address?: RockSdkCustomerAddress | string
metadata?: RockSdkMetadata[]
primaryProduct?: { metadata: RockSdkMetadata[] }
}
type RockSdkCustomerInfo = {
name: string
email: string
document: RockSdkCustomerDocument | string
telephone: RockSdkCustomerTelephone | string
address: RockSdkCustomerAddress | string
metadata: { key: string; value: string }[]
}
type RockSdkTokenParamsValues = {
creditCard1?: RockSdkCreditCard
creditCard2?: RockSdkCreditCard
primaryPrecification?: {
pricingModel: 'single' | 'subscription' // 'single' = pagamento único | 'subscription' = assinatura
}
}
type RockSdkTokenParams = {
cardDetails: RockSdkCardDetails
customerInfo: RockSdkCustomerInfo
isSubscription: boolean
}
type RockSdkCardToken = {
acquirer: string // 'yuno'
value: string // token do cartão
session: string // ID da sessão utilizada
customerId: string
}
type RockSdkSession = {
sessionId: string
customerId: string
}
type RockSdkSDKStatus = {
isLoaded: boolean
isLoading: boolean
hasInstance: boolean
}
type RockSdkPaymentResult = {
success: boolean
message?: string
status?: string
checkoutSession?: string
pending?: boolean
}
// onPaymentSuccess é chamado duas vezes no fluxo gerenciado (NuPay / PIX Parcelado)
type RockSdkPaymentSuccessPayload = {
// 1ª chamada — após o pedido ser criado
paymentResponse?: {
processCart?: {
id: string // ID do pedido — persista para redirecionar e consultar o status depois
status: string // 'success' | 'failed'
}
}
paymentInfo?: {
oneTimeToken: string
checkoutSession: string
customerId: string
paymentMethod: string
}
// 2ª chamada — após o pagamento ser confirmado
status?: string // 'SUCCEEDED'
checkoutSession?: string
paymentType?: string // ex: 'NU_PAY'
}
type RockSdkPaymentErrorPayload = {
type?: string
message?: string
error?: string
status?: string // ex: 'DECLINED'
}
type RockSdkPaymentCallbacks = {
onPaymentSuccess?: (data: RockSdkPaymentSuccessPayload) => void
onPaymentError?: (error: RockSdkPaymentErrorPayload) => void
onPaymentPending?: (data: { status: string; checkoutSession?: string }) => void
}
type RockSdkLoadingArgs = {
isLoading: boolean
type: 'DOCUMENT' | 'ONE_TIME_TOKEN'
}
type RockSdkProcessPaymentData = {
customerInfo: RockSdkCustomerInfo
[key: string]: unknown // campos adicionais do pedido (produtos, frete, etc.)
}
// Objeto retornado pela API de status do pedido
type RockSdkOrderStatus = {
id: string // preOrderId do pedido
status: string // status raw ('pending' | 'paid' | 'failed' | ...)
checkoutSession: string
paymentType: string // 'pixParcelado' | 'nuPay' | 'pix' | 'creditCard'
qrCode: string | null // dados do QR code (PIX)
qrCodeUrl: string | null // URL da imagem do QR code (PIX)
expiresAt: string | null // ISO 8601 — expiração do QR code (PIX)
createdAt: string // ISO 8601
}
type RockSdkPollingOptions = {
interval?: number // intervalo em ms (padrão: 3000)
maxDuration?: number // timeout em ms (padrão: 120000)
onSuccess?: (orderStatus: RockSdkOrderStatus) => void
onDeclined?: (orderStatus: RockSdkOrderStatus) => void
onPending?: (orderStatus: RockSdkOrderStatus) => void // chamado a cada check pendente
onTimeout?: () => void
}
type RockSdkPollingController = {
stop: () => void // para o polling
check: () => void // força verificação imediata
}
type RockSdkRecoveredOrder = {
preOrderId: string
checkoutSession: string | null
}