NuPay

NuPay for Business — checkout Nubank/SpinPay: pagamentos, sessões, estornos, condições e beneficiários.

Authentication

This connector uses Token-based authentication.

info

Set up your connection in the Abstra Console before using it in your workflows.

How to use

Using the Smart Chat

Execute the action "CHOOSE_ONE_ACTION_BELOW" from my connector "YOUR_CONNECTOR_NAME" using the params "PARAMS_HERE".

Using the Web Editor

from abstra.connectors import run_connection_action

result = run_connection_action(
  connection_name="your_connection_name",
  action_name="your_action_name",
  params={
    "param1": "value1",
    "param2": "value2"
  })

Available Actions

This connector provides 19 actions:

Action	Purpose	Parameters
post_v1_checkouts_payments	Endpoint utilizado para criar um pedido de pagamento. O pedido de pagamento é criado via API com o status WAITING_PAYMENT_METHOD, aguardando o consumidor realizar o pagamento. Este status é atualizado de acordo com a ação do consumidor de pagar ou cancelar a compra. Por isso, é preciso adaptar a experiência para informar o consumidor sobre o status do pagamento e a ação a realizar. Para mais informações sobre alterações de status, consulte a seção de Notificações tag/Notificacoes.	data (undefined) required
get_v1_checkouts_payments_by_psp_reference_id_status	Consulta o status de um pedido. A resposta contém informações sobre o pagamento. Também pode retornar identificação dos estornos, caso exista.	pspReferenceId (string)
post_v1_checkouts_payments_by_psp_reference_id_cancel	Cancela um pagament criado, mas que ainda não foi pago, isto é, pagamentos com status WAITING_PAYMENT_METHOD. Para pedidos pagos, deve ser usado o endpoint para abrir estorno operation/PaymentsRefundByPspReferenceIdPost.	pspReferenceId (string)
post_v1_checkouts_payments_by_psp_reference_id_refunds	Endpoint utilizado para devolver o valor pago para o consumidor. É possível fazer estorno de valores parciais para NuPay, desde que a soma dos estornos parciais em abertos e concluídos não ultrapassem o valor total do pagamento original. O status de um estorno é alterado conforme o estorno é processado. É responsabilidade do e-commerce implementar mecanismos de acompanhamento das mudanças de status de um estorno, para isso, consulte a seção sobre Notificações tag/Notificacoes. Os comprovantes	pspReferenceId (string) data: { . amount . transactionRefundId (string) . notes (string) } (object) required
get_v1_checkouts_payments_by_psp_reference_id_refunds_by_refund_id	Este endpoint retorna as informações do estorno refundId de um pagamento pspReferenceId, especificados como parâmetros na requisição.	refundId (string) pspReferenceId (string)
put_v1_checkouts_payments_by_psp_reference_id_recipients	Substitui atomicamente todos os beneficiários finais de um pedido de pagamento existente. Os beneficiários anteriores são inativados e o novo conjunto é inserido em uma única transação. Em caso de falha, o pedido retorna ao estado anterior. Útil para modelos de negócio em que o beneficiário final não é definido no momento da criação do pedido — como transportadoras que atribuem o veículo ao frete após a venda do bilhete.	pspReferenceId (string) data: { . recipients (array) } (object) required
post_v1_checkouts_sessions	Cria uma sessão de pagamento. A sessão é criada com o status pending e a resposta traz os dados da sessão criada, incluindo id, reference, status, redirectUrl, createdAt e expiresAt. Use a redirectUrl para redirecionar o comprador ao app do Nubank, onde ele aprova o pagamento. Após a aprovação, o comprador volta para a returnUrl com approvalCode e sessionId como query params. Use o sessionId para consultar a sessão via GET /v1/checkouts/sessions/sessionId e recuperar approvalCode e selectedPayme	data: { . currency (string) . reference (string) . merchant (object) . amount (number) . shopper (object) . paymentOptions (array) . lineItems (array) . expiresInMinutes (integer) . returnUrl (string) . callbackUrl (string) } (object) required
get_v1_checkouts_sessions_by_session_id	Consulta o status de uma sessão pelo id retornado na criação. Quando o status é approved, a resposta inclui o approvalCode e a selectedPaymentOption para criar o pagamento.	sessionId (string)
get_v1_checkouts_sessions_by_reference_by_reference	Consulta o status de uma sessão pelo reference enviado na criação. A resposta é a mesma da consulta pelo id.	reference (string)
post_v1_checkouts_sessions_by_session_id_expire	Expira uma sessão pending antes do tempo de expiração automático; ela passa para expired e não pode mais ser aprovada. Sessões já approved, completed, canceled ou expired retornam 409.	sessionId (string)
get_v1_authorize	Endpoint para obter a URL de redirecionamento do cliente associada à tela de autorização dentro do aplicativo do Nubank.	client_id (string) required scope (array) required response_type (string) required redirect_uri (string) required state (string) required code_challenge (string) required code_challenge_method (string) required
post_v1_token	Endpoint para gerar um refresh_token a partir do code apenas para OAuth ou gerar um access_token a partir de um refresh_token OAuth ou CIBA. O endpoint é o mesmo para os protocolos OAuth e CIBA, porém os campos a serem enviados na requisição são diferentes, como mostra os exemplos ao lado. Access token O access_token possui validade de 5 minutos e sempre será invalidado quando um novo for solicitado. Refresh token O refresh_token deve ser armazenado. É utilizado toda vez que uma solicit	No parameters
post_v1_backchannel_authentication	Esse endpoint deve ser chamado para iniciar o processo de autenticação via CIBA Client-Initiated Backchannel Authentication ou OTP One-Time Password.	No parameters
post_v1_backchannel_authentication_complete	Esse endpoint deve ser chamado para completar o processo de autenticação via OTP One-Time Password, validando o código de autenticação recebido pelo cliente.	data (undefined) required
post_v1_backchannel_authentication_otp_resend	Esse endpoint deve ser chamado para reenviar o código OTP One-Time Password para o cliente.	data (undefined) required
post_v2_checkouts_payment_conditions	Este endpoint retorna as opções de pagamentos e de parcelamento disponíveis para uma determinada compra. A resposta do endpoint varia de acordo com o cliente e a compra. Importante: Para consultar as condições de pagamento, verifique se a autorização operation/GenerateAuthorizationUrl foi feita com o escopo payment_conditions. Comportamento com paymentMethods: - Se paymentMethods não for informado ou for uma lista vazia, será usado o valor de amount para todos os métodos de pagamento disponíve	data (undefined) required
post_v1_recipients	Endpoint utilizado para cadastrar os dados do Beneficiário Final Recebedor. O cadastro é realizado via API e retorna o referenceId do beneficiário criado. Este referenceId pode ser utilizado posteriormente no campo recipients ao criar um pagamento via /v1/checkouts/payments. Caso o merchant envie dados de um beneficiário que já está cadastrado mesmo referenceId, um novo registro será criado e a versão anterior será marcada como deletada soft delete.	data: { . referenceId (string) . country (string) . name (string) . document (string) . documentType (string) } (object) required
get_v1_recipients_by_reference_id	Endpoint utilizado para consultar os dados do Beneficiário Final Recebedor pelo referenceId informado pelo merchant. Retorna a versão ativa do beneficiário na raiz do JSON e o histórico de versões anteriores no campo history.	referenceId (string)
custom	Call any endpoint of the connected service while reusing the connection auth. Pass the full URL as _url. Other reserved keys: _method, _query, _body, _headers. Remaining params flow naturally — empty → GET, non-empty → POST JSON body.	_url (string) required _method (string) _query (object) _body (undefined) _headers (object)

Webhook Events

This connector emits 4 events back to your workflow. To receive one, create a hook whose path is <connection-name>/<event> — the connection name you configured plus the event from the table below.

Event	Description
payment-status-updated	Notificação de mudança de status de um pedido de pagamento. Enviada para a callbackUrl informada em POST /v1/checkouts/payments.
refund-status-updated	Notificação de mudança de status de um estorno. Enviada para a mesma callbackUrl do pagamento.
session-status-updated	Notificação de mudança de status de uma sessão de checkout. Enviada para a callbackUrl informada em POST /v1/checkouts/sessions. O payload traz apenas sessionId e reference — consulte o status via GET /v1/checkouts/sessions/sessionId.
backchannel-authorization	Notificação de autorização CIBA backchannel. Enviada para a callback registrada no fluxo de autorização.