1. SDK
rockty
  • Módulo predefinido
    • API
      • Autenticação
        • Token
      • Afiliados
        • Affiliations
        • Links
        • Search
      • Pagamentos
        • Consulta
        • Cartão
        • PIX
      • Pedidos
        • Orders
    • SDK
      • RockSDK — Métodos Headless
      • Documentação RockSDK v2.1
  • Apresentação
    • home
  • SDK
    • Introdução
  1. SDK

Documentação RockSDK v2.1

RockSDK — Guia do Desenvolvedor#

RockSDK é uma biblioteca de pagamentos client-side para checkouts web. Ela realiza a tokenização de cartões e gerencia o fluxo completo de pagamento para NuPay e PIX Parcelado.
Todos os métodos do SDK são acessados através do objeto global window.RockSdk.

Índice#

1.
Instalação
2.
Inicialização
3.
Casos de Uso
Tokenização de Cartão de Crédito
Pagamento por PIX Parcelado
Pagamento por NuPay
Consultar Status do Pagamento
4.
Referência da API
5.
Tipos TypeScript

Instalação#

Adicione a tag de script ao seu HTML, preferencialmente antes do fechamento do </body>. Após o carregamento, window.RockSdk estará disponível globalmente.

Configuração#

Defina sua chave pública antes de chamar init():

Inicialização#

Chame 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.
Para verificar o estado do SDK a qualquer momento:

Casos de Uso#

1. Tokenização de Cartão de Crédito#

Use este fluxo para tokenizar um ou dois cartões (pagamento dividido entre cartões) antes de enviar o pedido ao seu backend.
Pagamento único ou assinatura? Entenda o isSubscription
O valor de isSubscription determina 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.pricingModel dentro do formValues — certifique-se de que esse campo está correto antes de chamar generateTokenParams.

Montando o formValues para generateTokenParams#

generateTokenParams lê os dados do cartão e do cliente a partir de um objeto formValues plano. O formato esperado é:
Alternativamente, você pode construir o customerInfo separadamente com getCustomerData() e passar apenas os dados do cartão para generateTokenParams. Consulte getCustomerData abaixo.

2. Pagamento por PIX Parcelado#

O PIX Parcelado utiliza o fluxo gerenciado: o SDK abre um modal da Pagaleve, processa o pagamento e notifica sua aplicação via callbacks.
callbackUrl — obrigatório para PIX Parcelado
Durante 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 onPaymentSuccess
1ª chamada — ocorre após o pedido ser criado no backend. payload.paymentResponse.processCart está presente. Salve o id do 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.

Na página de retorno após o redirect#

Quando o usuário retorna do app da Pagaleve, chame recoverOrderFromRedirect + pollPaymentStatus para consultar o resultado:

3. Pagamento por NuPay#

O NuPay segue o mesmo fluxo gerenciado do PIX Parcelado. As únicas diferenças são o valor de paymentMethod ('nuPay') e que o redirecionamento externo vai para o app do Nubank.
callbackUrl — obrigatório para NuPay
O 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.
O comportamento de onPaymentSuccess e o padrão de recuperação após redirecionamento são idênticos ao do PIX Parcelado — consulte a seção 2.

4. Consultar Status do Pagamento#

Use checkPaymentStatus para verificar o estado final de um pedido. O método nunca lança exceção — erros de rede retornam 'PENDING'.
RetornoSignificado
'SUCCEEDED'Pagamento aprovado
'DECLINED'Pagamento recusado
'PENDING'Ainda processando, ou erro de rede — tente novamente

Polling nativo com pollPaymentStatus#

O SDK oferece polling nativo que gerencia intervalo, timeout e cleanup automaticamente. Os callbacks recebem o objeto orderStatus completo retornado pela API:
pollPaymentStatus também aceita { checkoutSession } como primeiro argumento, da mesma forma que checkPaymentStatus.

Recuperação após redirecionamento externo#

Quando o usuário retorna de um app externo (NuPay/Pagaleve), use 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 → preOrderId no localStorage durante o processPayment. Você não precisa fazer isso manualmente no callback onPaymentSuccess.

Consulta manual com getOrderStatus#

Use getOrderStatus 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.
Exemplo com botão após timeout:

Referência da API#

MétodoAssinaturaRetorno
init(): Promise<void>Resolve quando o SDK está pronto
getSDKStatus(): RockSdkSDKStatusEstado atual do SDK
getCustomerData(values: RockSdkCustomerDataValues): RockSdkCustomerInfoDados 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?): RockSdkPollingControllerPolling nativo com callbacks
getOrderStatus(params: string | { preOrderId?, checkoutSession? }): Promise<RockSdkOrderStatus>Consulta manual do status completo
recoverOrderFromRedirect(): RockSdkRecoveredOrder | nullRecupera pedido após redirect externo

getCustomerData#

Normaliza os dados do formulário do cliente no formato exigido pelos demais métodos do SDK. Também resolve metadados dinâmicos a partir dos query parameters da URL.
document, telephone e address aceitam tanto um objeto estruturado quanto uma string simples (ex: CPF diretamente como string).

Tipos TypeScript#

Como o SDK é carregado via CDN, os tipos abaixo servem como referência para autocompletar e documentar o contrato de cada método. Copie as definições necessárias para o seu projeto.

Definições de Tipos#

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
}
Modificado em 2026-05-02 14:36:24
Página anterior
RockSDK — Métodos Headless
Próxima página
home
Built with