NuPay for Business
API docs by Redocly

NuPay API (1.4)

Download OpenAPI specification:

Tech Team: [email protected] URL: https://nupaybusiness.com.br

Todas as APIs providas pela NuPay for Business foram desenvolvidas baseadas na tecnologia REST, seguindo as melhores práticas de mercado, tendo sempre em mente uma integração o mais simples possível. Seu feedback é muito valioso para nós – por isso, sinta-se à vontade para entrar em contato com nossa equipe de tecnologia pelo e-mail oi-nupay@nubank.com.br!

Sessões de pagamento

Guia para implementação

Criar sessão de pagamento

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. O sessionId acompanha todo redirecionamento para a returnUrl, então você sempre sabe de qual sessão se trata. Após a aprovação, o comprador volta 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 selectedPaymentOption antes de criar o pagamento em POST /v1/checkouts/payments. Se a sessão foi cancelada, ele volta com state=canceled; se expirou, com state=expired. Nos dois casos não há approvalCode, porque não há o que capturar. Se o comprador voltar ao site sem decidir, a sessão continua pending e nenhum state é enviado — ela ainda pode ser aprovada no app. Os cenários de erro mais comuns na criação são 400, quando o merchant não está habilitado para sessões de pagamento; 409, quando o reference já está em uso em uma sessão ativa; e 412, quando um CPF é informado em shopper.identification e o comprador não está elegível para NuPay. No 400, contate o suporte para habilitar a modalidade. No 409, não crie outra sessão para o mesmo pedido. No 412, ofereça outro método de pagamento. No sandbox, CPFs que começam com 4 retornam 412; demais CPFs válidos são elegíveis.

Authorizations:
(MerchantApiKeyMerchantApiToken)
Request Body schema: application/json
required
currency
required
string
Value: "BRL"

Moeda da sessão (ISO 4217), aplicada a todos os valores monetários do contrato.

reference
required
string non-empty

Identificador do pedido no sistema do merchant. Deve ser único enquanto a sessão estiver ativa (pending ou approved): um reference já em uso nesses estados retorna 409.

amount
required
number <double> > 0

Valor base do pedido.

returnUrl
required
string^https://

URL única para redirecionar o comprador após a interação no app (não há cancelUrl separada). O sessionId acompanha todo redirecionamento. Em caso de aprovação, recebe também o approvalCode. Se a sessão foi cancelada, recebe state=canceled; se expirou, state=expired. Se o comprador voltar sem decidir, a sessão segue pending e nenhum state é enviado.

object

Dados de exibição do merchant.

object

Identificação do comprador. Quando informada com CPF, a NuPay verifica automaticamente a elegibilidade para pagar com NuPay.

Array of objects non-empty

Opcional. Customiza as opções de pagamento padrão configuradas na conta para esta sessão. Se não for enviado, a NuPay exibirá as opções padrão da conta, com o mesmo comportamento do NuPay 2FA padrão. Cada type pode aparecer no máximo uma vez.

Array of objects non-empty

Itens que o comprador está comprando. Aceito no schema de criação, mas não é utilizado neste fluxo de sessão de pagamento (o valor cobrado vem de amount / paymentOptions).

expiresInMinutes
integer >= 1

Tempo, em minutos, até a sessão expirar a partir da criação. Padrão de 30 minutos. Enquanto a sessão estiver pending ou approved sem pagamento criado, ao atingir esse prazo ela vira expired.

callbackUrl
string^https://

URL que recebe as notificações (webhook) de mudança de status da sessão.

Responses

Response Schema: application/json
id
required
string

Identifica uma única sessão de pagamento. É utilizado para consultar o status via GET /v1/checkouts/sessions/{sessionId}.

reference
required
string

O mesmo reference enviado na criação da sessão.

status
required
string (CheckoutSessionStatus)
Enum: "pending" "approved" "completed" "canceled" "expired"

Status de uma sessão de pagamento.

Status Descrição
pending A sessão foi criada e está aguardando o comprador aprovar o pagamento no app do Nubank.
approved O comprador aprovou o pagamento no app. O approvalCode e o selectedPaymentOption estão disponíveis para criar o pagamento via POST /v1/checkouts/payments. Enquanto o pagamento não for criado, a sessão ainda pode ir para expired (pelo expiresAt ou pelo endpoint de expirar).
completed Um pagamento foi criado com o approvalCode desta sessão. Estado final.
canceled O comprador cancelou o pagamento no app. Estado final.
expired A sessão atingiu o expiresAt ainda em pending ou em approved (sem criação do pagamento), ou foi expirada manualmente via API. Estado final.
redirectUrl
required
string

URL para redirecionar o comprador ao app do Nubank para aprovar o pagamento. Pode ser reutilizada para levar o comprador de volta ao fluxo de aprovação.

createdAt
required
string <date-time>

Data e hora da criação da sessão (ISO 8601, UTC).

expiresAt
required
string <date-time>

Data e hora em que a sessão expira (ISO 8601, UTC).

object

Identificação do comprador. Presente quando enviada na criação da sessão. Ecoado apenas na resposta do POST de criação — o GET /v1/checkouts/sessions/{sessionId} não retorna shopper.

Request samples

Content type
application/json
{
  • "currency": "BRL",
  • "reference": "cart-123",
  • "merchant": {
    },
  • "amount": 150,
  • "shopper": {
    },
  • "paymentOptions": [
    ],
  • "expiresInMinutes": 30,
  • "returnUrl": "https://mystore.example.com/checkout/order/return/v32478982",
  • "callbackUrl": "https://mystore.example.com/webhooks/nupay"
}

Response samples

Content type
application/json
{}

Consultar status de uma sessão de pagamento

Consulta o status de uma sessão pelo id retornado na criação. A resposta é o objeto completo da sessão (CheckoutSessionGetResponse). Quando o status é approved, inclui o approvalCode e a selectedPaymentOption para criar o pagamento. Diferente do endpoint de expirar, que retorna apenas { id, status }.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
sessionId
required
string

ID da sessão de pagamento, retornado na criação da sessão

Responses

Response Schema: application/json
id
required
string

Identifica uma única sessão de pagamento. É o mesmo id retornado na criação da sessão.

reference
required
string

O mesmo reference enviado na criação da sessão.

status
required
string (CheckoutSessionStatus)
Enum: "pending" "approved" "completed" "canceled" "expired"

Status de uma sessão de pagamento.

Status Descrição
pending A sessão foi criada e está aguardando o comprador aprovar o pagamento no app do Nubank.
approved O comprador aprovou o pagamento no app. O approvalCode e o selectedPaymentOption estão disponíveis para criar o pagamento via POST /v1/checkouts/payments. Enquanto o pagamento não for criado, a sessão ainda pode ir para expired (pelo expiresAt ou pelo endpoint de expirar).
completed Um pagamento foi criado com o approvalCode desta sessão. Estado final.
canceled O comprador cancelou o pagamento no app. Estado final.
expired A sessão atingiu o expiresAt ainda em pending ou em approved (sem criação do pagamento), ou foi expirada manualmente via API. Estado final.
redirectUrl
required
string

URL para redirecionar o comprador ao app do Nubank. Sempre presente, pode ser reutilizada para levar o comprador de volta ao fluxo de aprovação.

createdAt
required
string <date-time>

Data e hora da criação da sessão (ISO 8601, UTC).

expiresAt
required
string <date-time>

Data e hora em que a sessão expira (ISO 8601, UTC). Após esse instante, com a sessão ainda pending ou approved, o status passa a expired e criar o pagamento com o approvalCode retorna 400 (session has expired).

approvalCode
string

Código de aprovação do pagamento. Presente apenas quando o status é approved. Deve ser enviado no campo approvalCode para criar o pagamento via POST /v1/checkouts/payments. É de uso único: após criar o pagamento com sucesso, reutilizá-lo retorna 400 (approval code already used).

object (CheckoutSessionSelectedPaymentOption)

Opção de pagamento escolhida pelo comprador no app do Nubank.

Request samples 

curl --request GET \
     --url 'https://sandbox-api.spinpay.com.br/v1/checkouts/sessions/{sessionId}' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{}

Expirar uma sessão de pagamento

Expira uma sessão pending ou approved antes do expiresAt automático; ela passa para expired e o approvalCode deixa de poder ser usado. Sessão já capturada (completed) retorna 404. Sessão já canceled retorna 409. Sessão ainda ativa, mas vencida por prazo ou com attempt não expirável, retorna 412. Em sucesso (200), a resposta é apenas { id, status } (CheckoutSessionExpireResponse), não o objeto completo do GET.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
sessionId
required
string

ID da sessão de pagamento, retornado na criação da sessão

Responses

Response Schema: application/json
id
required
string

Identifica a sessão de pagamento expirada. É o mesmo id retornado na criação da sessão.

status
required
string
Value: "expired"

Status final da sessão após a expiração.

Request samples 

curl --request POST \
     --url 'https://sandbox-api.spinpay.com.br/v1/checkouts/sessions/{sessionId}/expire' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "id": "645a7eaa-4361-43b2-8749-575a1cd7dd4c",
  • "status": "expired"
}

Pagamentos

Criar pagamento

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.

Authorizations:
(MerchantApiKeyMerchantApiToken)
header Parameters
Authorization
string
Example: Bearer UVhslgtbavMol9u8

Informe o access_token com o prefixo Bearer . Header necessário somente para criação de pagamentos pré-autorizados de NuPay.

Request Body schema: application/json
required
One of
merchantOrderReference
required
string

Número da ordem de compra criada pela loja. Esse número é o que identifica essa compra nos arquivos de conciliação e deve ser único por loja.

referenceId
required
string

Referência que identifica um pagamento de forma única para o e-commerce. É recomendado que esse valor seja único por pagamento.

required
object (Amount)
required
object (Shopper)
required
Array of objects (Items)

Itens comprados.

required
object (PaymentMethod)

Forma de pagamento a ser utilizada.

transactionId
string

Identificação da transação relacionada a esse pagamento.

installments
integer

Quantidade de parcelas. Somente para pagamentos pré-autorizado.

object (PaymentMethod)

Determina o fluxo para o qual os consumidores serão redirecionados após autorização (returnUrl) ou cancelamento (cancelUrl) do pagamento.

merchantName
string

Nome da marca que deve ser mostrado ao consumidor. Se omitido, o nome cadastrado pelo e-commerce será utilizado.

storeName
string

Nome da filial/loja.

delayToAutoCancel
integer <int32>
Default: 30

Tempo de espera em minutos para o consumidor aprovar o pagamento. Vencido esse tempo, uma chamada para cancelamento do pagamento é feita automaticamente. Valor padrão é de 30 minutos. Não pode ser menor que 1.

object (Shipping)
object (Address)
Array of objects (Recipient)

Array de beneficiários finais. Representa os destinatários efetivos dos valores transacionados, conforme exigência regulatória do Banco Central (Circular BCB 3.978/2020) para identificação de beneficiários finais em arranjos de pagamento. Máximo de 10 itens. Campo opcional e não bloqueante na criação de pagamento.

orderUrl
string

URL da ordem de compra da loja. Protocolo é obrigatório (https://).

callbackUrl
string

URL para enviar notificação da plataforma NuPay for Business para a plataforma do e-commerce. Para mais informações sobre as notificações, veja a seção Notificações. Protocolo é obrigatório (https://).

referenceDate
string <ISO-8601 YYYY-MM-DD HH:mm:ss>

Data de referência sem fuso-horário enviada na criação do pedido.

Responses

Response Schema: application/json
One of
pspReferenceId
required
string

Identifica um único pagamento. É utilizado para toda comunicação sobre o status de pagamento.

referenceId
required
string

O mesmo referenceId enviado na solicitação.

status
required
string (CheckoutCreationStatus)
Enum: "WAITING_PAYMENT_METHOD" "COMPLETED" "CANCELLED" "ERROR"

Status de um pedido de pagamento.

Status Descrição
WAITING_PAYMENT_METHOD O pedido foi criado e está aguardando o método de pagamento.w
COMPLETED O cliente conclui a compra e o pagamento foi realizado.
CANCELLED O pagamento foi cancelado.
ERROR Informa quando um erro ocorreu, juntamente com sua causa.
paymentUrl
required
any

Retorna a URL para o app do Nubank para redirecionar o cliente para concluir o pagamento.

paymentMethodType
string
Value: "nupay"

Tipo do pagamento escolhido pelo consumidor.

code
string (CheckoutCreationCode)
Enum: "SYSTEM_ERROR" "CANCELLED_BY_USER" "CANCELLED_BY_TIMEOUT" "CANCELLED_BY_INSTITUTION" "CANCELLED_BY_SELLER"

Complementa status de erro com o código do erro de acordo com tabela abaixo:

status code message
ERROR SYSTEM_ERROR The system can not process this payment now. Please try again later.
CANCELLED CANCELLED_BY_USER The user cancelled the payment.
CANCELLED CANCELLED_BY_TIMEOUT This payment was cancelled due to timeout.
CANCELLED CANCELLED_BY_INSTITUTION The institution cancelled the payment.
CANCELLED CANCELLED_BY_SELLER Seller has cancelled this payment.
message
string (CheckoutCreationMessage)

Complementa status de erro com a mensagem do erro de acordo com tabela abaixo:

status code message
ERROR SYSTEM_ERROR The system can not process this payment now. Please try again later.
CANCELLED CANCELLED_BY_USER The user cancelled the payment.
CANCELLED CANCELLED_BY_TIMEOUT This payment was cancelled due to timeout.
CANCELLED CANCELLED_BY_INSTITUTION The institution cancelled the payment.
CANCELLED CANCELLED_BY_SELLER Seller has cancelled this payment.

Request samples

Content type
application/json
Example
{
  • "merchantOrderReference": "123432abc",
  • "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
  • "referenceId": "595b6e74-0030-43ab-9b89-8f2ec9923272",
  • "merchantName": "Loja Teste",
  • "storeName": "Loja Teste Campinas",
  • "amount": {
    },
  • "delayToAutoCancel": 15,
  • "paymentMethod": {
    },
  • "paymentFlow": {},
  • "shopper": {
    },
  • "shipping": {
    },
  • "billingAddress": {
    },
  • "items": [
    ],
  • "recipients": [
    ],
  • "orderUrl": "https://admin.mystore.example.com/orders/v32478982",
  • "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore"
}

Response samples

Content type
application/json
Example

Consultar status de um pagamento

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.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
pspReferenceId
required
string

ID do pagamento que deseja visualizar o status

Responses

Response Schema: application/json
pspReferenceId
required
string

Identifica um único pagamento. É utilizado para toda comunicação sobre o status de pagamento.

referenceId
required
string

O mesmo referenceId enviado na solicitação.

status
required
string (CheckoutStatus)
Enum: "WAITING_PAYMENT_METHOD" "AUTHORIZED" "CANCELLED" "ERROR" "COMPLETED"

Status de um pedido de pagamento.

Status Descrição
WAITING_PAYMENT_METHOD O pagamento foi criado e que está aguardando o método de pagamento.
AUTHORIZED O pagamento foi realizado e o pagamento está em processamento.
COMPLETED O cliente conclui a compra e o pagamento foi processado.
CANCELLED O pagamento foi cancelado.
ERROR Informa quando um erro ocorreu, juntamente com sua causa.
required
object

Valor do pagamento.

timestamp
required
string

Momento exato (ISO String) da ultima mudança de estado.

required
object

Identificação do pagador.

code
string (CheckoutStatusCode)
Enum: "CANCELLED_BY_SELLER" "CANCELLED_BY_TIMEOUT" "CANCELLED_BY_INSTITUTION" "CANCELLED_BY_USER" "REVERSED" "SYSTEM_ERROR"

Complementa status de erro com o código do erro de acordo com tabela abaixo:

status code message
CANCELLED CANCELLED_BY_SELLER O e-commerce cancelou este pagamento.
CANCELLED CANCELLED_BY_TIMEOUT Este pagamento foi cancelado por exceder o tempo para processamento.
CANCELLED CANCELLED_BY_INSTITUTION A instituição de pagamento cancelou este pagamento.
CANCELLED CANCELLED_BY_USER O cliente cancelou este pagamento.
CANCELLED ou ERROR REVERSED O processamento do pagamento não foi concluído e o valor foi devolvido para o cliente.
ERROR SYSTEM_ERROR O sistema não pode processar este pafamento agora. Tente novamente mais tarde.
message
string (CheckoutStatusMessage)

Complementa status de erro com a mensagem do erro de acordo com tabela abaixo:

status code message
CANCELLED CANCELLED_BY_SELLER Seller has cancelled this payment.
CANCELLED CANCELLED_BY_TIMEOUT This payment was cancelled due to timeout.
CANCELLED CANCELLED_BY_INSTITUTION The institution cancelled the payment.
CANCELLED CANCELLED_BY_USER User has cancelled this payment.
CANCELLED ou ERROR REVERSED This payment was reversed due to an internal error.
ERROR SYSTEM_ERROR The system can not process this payment now. Please try again later.
paymentMethodType
string

Tipo do meio de pagamento escolhido pelo consumidor.

Array of objects (StatusResponse)

Lista de estornos solicitados para este pagamento.

paymentType
string

Tipo do pagamento via NuPay.

Tipo Descrição
credit Pagamento usando crédito.
debit Pagamento usando o saldo da conta.
installmentNumber
number

Número de parcelas. Para pagamentos parcelados com juros, deve ser usado para fins de conciliação e é retornado 1

installmentNumberPurchase
number

Número de parcelas selecionadas para a compra quando for parcelamento com juros.

Request samples 

curl --request GET \
     --url 'https://sandbox-api.spinpay.com.br/v1/checkouts/payments/{pspReferenceId}/status' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{
  • "paymentMethodType": "nupay",
  • "installmentNumber": 1,
  • "paymentType": "credit",
  • "referenceId": "86371aa1-9e64-4abc-8af9-6400ef23cd69",
  • "pspReferenceId": "ea451bf2-26b8-40f8-a0a1-27d95df55871",
  • "timestamp": "2022-08-16T17:20:48.795Z",
  • "status": "COMPLETED",
  • "amount": {
    },
  • "payer": {
    }
}

Cancelar um pagamento

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.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
pspReferenceId
required
string

ID do pagamento que deseja cancelar

Responses

Response Schema: application/json
pspReferenceId
required
string

Identifica um único pagamento. É utilizado para toda comunicação sobre o status de pagamento.

referenceId
required
string

O mesmo referenceId enviado na solicitação.

status
required
string (CheckoutCancelStatus)
Enum: "CANCELLING" "CANCELLED" "DENIED" "ERROR"

Status de um pedido de pagamento.

Status Descrição
CANCELLING A requisição de cancelamento é válida e será processada. Ao término do processamento o estado do pagamento será CANCELLED.
CANCELLED O pagamento foi cancelado.
DENIED O pedido de pagamento foi recusado.
ERROR Informa quando um erro ocorreu, juntamente com sua razão.
code
string (CheckoutCancelCode)
Enum: "ALREADY_CANCELLED" "CANCELLED_BY_USER" "CANCELLED_BY_SELLER" "ALREADY_DENIED" "ALREADY_SETTLED" "ALREADY_REFUNDED" "SYSTEM_ERROR"

Complementa status de erro com o código do erro de acordo com tabela abaixo:

status code message
DENIED ALREADY_CANCELLED This payment was already cancelled.
DENIED CANCELLED_BY_USER This payment was already cancelled by user.
DENIED CANCELLED_BY_SELLER This payment was already cancelled by seller.
DENIED ALREADY_DENIED This payment was denied by user or institution and cannot be refunded.
DENIED ALREADY_SETTLED This payment was already settled. Use refund endpoint instead.
DENIED ALREADY_REFUNDED This payment was already refunded.
ERROR SYSTEM_ERROR The system can not process this payment now. Please try again later.
message
string (CheckoutCancelMessage)

Complementa status de erro com a mensagem do erro de acordo com tabela abaixo:

status code message
DENIED ALREADY_CANCELLED This payment was already cancelled.
DENIED CANCELLED_BY_USER This payment was already cancelled.
DENIED CANCELLED_BY_SELLER This payment was already cancelled.
DENIED CANCELLED_BY_USER This payment was already cancelled.
DENIED CANCELLED_BY_SELLER This payment was already cancelled.
DENIED ALREADY_DENIED This payment was denied by user or institution and cannot be refunded.
DENIED ALREADY_SETTLED This payment was already settled. Use refund endpoint instead.
DENIED ALREADY_REFUNDED This payment was already refunded.
ERROR SYSTEM_ERROR The system can not process this payment now. Please try again later.

Request samples 

curl --request POST \
     --url 'https://sandbox-api.spinpay.com.br/v1/checkouts/payments/{pspReferenceId}/cancel' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{
  • "referenceId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  • "pspReferenceId": "ea6dd35a-699e-4dc1-b036-3369f409c8cd",
  • "status": "CANCELLED"
}

Atualizar beneficiários finais de um pagamento

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.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
pspReferenceId
required
string

ID do pedido de pagamento cujos beneficiários finais serão atualizados.

header Parameters
X-Merchant-Key
required
string

Especifica a chave do merchant que está utilizando os serviços da NuPay for Business

X-Merchant-Token
required
string

Especifica o merchant que está fazendo a venda

Request Body schema: application/json
required
required
Array of objects [ 1 .. 10 ] items

Lista de beneficiários finais. Mínimo 1, máximo 10 itens.

Responses

Response Schema: application/json
object (Atualizar beneficiários finais — Resposta)

Resposta de sucesso ao substituir os beneficiários finais de um pedido de pagamento. O corpo da resposta é um objeto vazio.

Request samples

Content type
application/json
Example
{
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{ }

Estornos

Estornar um pagamento

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.

Os comprovantes de estornos ficam disponíveis somente por meio do Painel do Lojista.

Casos especiais

Em alguns casos, um estorno pode não ser concluído. Alguns deles são:

  • O pagamento foi reautorizado por algum acordo entre NuPay for Business e e-commerce;
  • Um pedido de estorno foi aberto e cancelado anteriormente para o mesmo pagamento;
  • Foi solicitado o bloqueio de estornos para o pagamento;
  • Não há saldo suficiente na conta de pagamento do e-commerce na NuPay for Business;
  • A conta de origem do pagamento não existe mais.

Você pode consultar o mapeamento de erros neste link. O erro será descrito na resposta da requisição no campo error. Consulte os exemplos de resposta ao lado para mais informações.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
pspReferenceId
required
string

ID do pagamento que deseja estornar

Request Body schema: application/json
required
required
object (RefundAmount)
transactionRefundId
required
string

Identificação da transação relacionada a esse estorno. Deve ser única por estorno.

notes
string

Comentário sobre o estorno.

Responses

Response Schema: application/json
pspReferenceId
required
string

Identifica um único pagamento. É utilizado para toda comunicação sobre o status de pagamento.

status
required
string (RefundCreationStatus)
Enum: "OPEN" "REFUNDING" "ERROR"

Status de um pedido de estorno.

Status Descrição
REFUNDING O pedido de estorno está sendo processado.
ERROR Informa que um erro ocorreu com o pedido de estorno em conjunto do descrição do erro.
refundId
required
string

Identificador do estorno criado.

Request samples

Content type
application/json
{
  • "transactionRefundId": "234982-abcde-1235",
  • "amount": {
    },
  • "notes": "Cliente recebeu produto com defeito."
}

Response samples

Content type
application/json
Example
{
  • "refundId": "fde05f28-486e-4399-b23e-c14a559c1845",
  • "pspReferenceId": "ea6dd35a-699e-4dc1-b036-3369f409c8cd",
  • "status": "REFUNDING",
  • "dueDate": null
}

Consultar um estorno

Este endpoint retorna as informações do estorno (refundId) de um pagamento (pspReferenceId), especificados como parâmetros na requisição.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
refundId
required
string

ID do estorno do pagamento que deseja consultar.

pspReferenceId
required
string

ID do pagamento do estorno.

Responses

Response Schema: application/json
transactionRefundId
required
string

Identificação da transação relacionada a esse estorno. Deve ser única por estorno.

Observação: Quando for retornado CREATED_BY_SELLER_PANEL, significa que o estorno foi criado pelo painel do lojista e, portanto, não possui o identificador único do e-commerce salvo na NuPay for Business.

pspReferenceId
required
string

Identifica um único pagamento. É utilizado para toda comunicação sobre o status de pagamento.

refundId
required
string

Identifica um único estorno.

status
required
string (RefundStatus)
Enum: "REFUNDING" "REFUNDED" "ERROR"

Status de um pedido de estorno.

Status Descrição
REFUNDING O pedido de estorno está sendo processado.
REFUNDED O pedido de estorno foi processado e realizado.
ERROR Informa quando um erro ocorreu, juntamente com sua causa.
dueDate
required
string <date-time>

Data limite para a composição do estorno.

required
object (RefundAmount)
object (RefundError)

Objeto contendo informações do erro ocorrido durante a execução do estorno.

source
string

Canal (Painel ou API) pelo qual o estorno foi solicitado.

Request samples 

curl --request GET \
     --url 'https://sandbox-api.spinpay.com.br/v1/checkouts/payments/{pspReferenceId}/refunds/{refundId}' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{
  • "refundId": "F5C1A4E20D3B4E07B7E871F5B5BC9F22",
  • "pspReferenceId": "ea6dd35a-699e-4dc1-b036-3369f409c8cd",
  • "transactionRefundId": "234982-abcde-1235",
  • "status": "REFUNDING",
  • "dueDate": null,
  • "amount": {
    }
}

Beneficiário final

Criar beneficiário final

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).

Authorizations:
(MerchantApiKeyMerchantApiToken)
Request Body schema:
required
referenceId
required
string <= 100 characters ^[a-zA-Z0-9._-]{1,50}$

Identificador único do beneficiário no sistema do merchant. Aceita letras, números, ponto (.), hífen (-) e underscore (_).

country
required
string
Enum: "BR" "MX" "CO" "US" "HK" "KY" "PA" "CH" "Other"

Código do país do beneficiário no formato ISO 3166-1 alpha-2. Use Other para países não listados.

name
required
string

Razão social ou nome do beneficiário final.

document
required
string

Número do documento do beneficiário.

  • CPF: 11 dígitos
  • CNPJ: 14 dígitos
  • Other: máximo de 50 caracteres
documentType
required
string
Enum: "CPF" "CNPJ" "Other"

Tipo do documento do beneficiário.

Responses

Response Schema: application/json
object

Dados do beneficiário criado.

Request samples

Content type
{
  • "referenceId": "8943dd2c-e743-46a5-b953-45f806022210",
  • "country": "BR",
  • "name": "Empresa Exemplo Ltda",
  • "document": "12345678000195",
  • "documentType": "CNPJ"
}

Response samples

Content type
application/json
{
  • "recipient": {
    }
}

Consultar beneficiário final

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.

Authorizations:
(MerchantApiKeyMerchantApiToken)
path Parameters
referenceId
required
string
Example: 8943dd2c-e743-46a5-b953-45f806022210

ID de referência externo do recipient informado pelo merchant

Responses

Response Schema: application/json
country
string

País do beneficiário final

referenceId
string

Identificador único do beneficiário no sistema do merchant.

merchantId
string <uuid>

ID do merchant no sistema

name
string

Nome ou razão social do beneficiário final

document
string

Documento do beneficiário final

documentType
string
Enum: "CPF" "CNPJ" "Other"

Tipo de documento do beneficiário final

createdAt
string <date-time>

Data e hora de criação do beneficiário

Array of objects (RecipientHistoryEntry)

Histórico de versões anteriores do beneficiário

Request samples 

curl --request GET \
     --url 'https://sandbox-api.spinpay.com.br/v1/recipients/{referenceId}' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}'

Response samples

Content type
application/json
Example
{
  • "country": "BR",
  • "referenceId": "uuid-001",
  • "merchantId": "4fc11f31-7620-42c0-b8f3-84d12a6d1dea",
  • "name": "Restaurante Exemplo LTDA",
  • "document": "12345678000195",
  • "documentType": "CNPJ",
  • "createdAt": "2025-12-06T10:30:00Z",
  • "history": [ ]
}

Autorização para app - OAuth2

Guia para implementação

Gerar URL de autorização

Endpoint para obter a URL de redirecionamento do cliente associada à tela de autorização dentro do aplicativo do Nubank.

Authorizations:
(MerchantApiKeyMerchantApiToken)
query Parameters
client_id
required
string
Example: client_id=234982-abcde-1235

Client ID gerado pelo time NuPay e informado no momento do onboarding.

scope
required
Array of strings
Example: scope=charge&scope=refund&scope=payment_conditions

Array de strings com os escopos desejados.

Escopo Descrição
charge Escopo com permissão para cobranças.
refund Escopo com permissão para estornos.
payment_conditions Escopo com permissão para consulta de condições de pagamento.
response_type
required
string
Default: "code"

Envie o valor code.

redirect_uri
required
string
Example: redirect_uri=https://merchant-domain.com/redirect-uri

URL a ser utilizada para redirecionar o cliente de volta ao e-commerce uma vez que concluir a autorização no app do Nubank. Os atributos code e state são enviados como query parameter. O protocolo deve ser sempre HTTPS

state
required
string
Example: state=0b10616b-3aa7-4b1c-a902-3e85b2549025

Estado de validação gerado pelo e-commerce que será retornado na URL de resposta e pode ser utilizado para validar a resposta.

code_challenge
required
string
Example: code_challenge=415594c595621aa3ae171843f1f256fa4920ca5da06eeccdd6f2bab9edc8e818

Valor alfanumérico gerada pelo e-commerce, deve ser armazenada para uso posterior.

code_challenge_method
required
string
Default: "S256"

Tipo de validação do code_challenge, deve-se sempre enviar S256.

Responses

Response Schema: application/json
redirect_uri
required
string <uri>

URL para redirecionar o cliente para o fluxo de autorização no aplicativo do Nubank.

Esta URL contém alguns parâmetros de URL que precisam ser tratados pelo e-commerce:

Nome do parâmetro Descrição
state Obrigatório. Estado de validação enviado pelo e-commerce na requisição para gerar a URL e pode ser usado para validar a resposta.
error Opcional. Indica que houve um erro ao gerar a URL.
error_description Opcional. Descrição da causa do erro ao gerar a URL.

Request samples 

curl --request GET \
     --url 'https://sandbox-authentication.spinpay.com.br/api/v1/authorize?client_id={client_id}&scope=charge&scope=refund&scope=payment_conditions&response_type=code&redirect_uri={redirect_uri}&state={state}&code_challenge={code_challenge}&code_challenge_method=S256' \
     --header 'X-Merchant-Key: {X-Merchant-Key}' \
     --header 'X-Merchant-Token: {X-Merchant-Token}' \
     --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example

Autorização para web - CIBA

Guia para implementação

Gerar autorização

Esse endpoint deve ser chamado para iniciar o processo de autenticação via CIBA (Client-Initiated Backchannel Authentication) ou OTP (One-Time Password).

Authorizations:
(MerchantApiKeyMerchantApiToken)
Request Body schema: application/x-www-form-urlencoded
One of
parameters
required
string

Dentro do campo parameters campos e valores devem ser concatenados como queryString.

Esperamos os seguintes parâmetros dentro de parameters:

Campo Descrição
login_hint CPF do cliente.
client_assertion_type Deve sempre informar urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Token JWT gerado para autorização da requisição.
client_notification_token É um bearer token fornecido pelo client e será usado pelo NuPay para autenticar o callback para o client. Para o auth_method=otp será a mesma informação do client_assertion.
scope Deve sempre informar openid e charge. Caso queira consultar as condições de pagamento adicionar também payment_conditions.
auth_method Se o método de autenticação escolhido for OTP deve sempre informar otp, caso contrário esse campo não deve ser informado.

Responses

Response Schema: application/json
One of
auth_req_id
string

Este é um identificador único para identificar o pedido de autenticação feito pelo parceiro.

masked_phone_number
string

Número de telefone do cliente mascarado ao qual foi enviado o SMS. Esse campo só será retornado caso o metódo de authenticação seja OTP e o SMS foi enviado com sucesso.

ticket
string

Ticket de autorização para o cliente. Esse campo só será retornado caso o metódo de authenticação seja OTP.

expires_in
number

Tempo de expiração do auth_req_id em segundos.

Request samples

Content type
application/x-www-form-urlencoded
parameters=login_hint%3D%7B%7BcustomerCPF%7D%7D%26scope%3Dopenid%26scope%3Dcharge%26scope%3Dpayment_conditions%26client_notification_token%3D%7B%7BclientNotificationToken%7D%7D%26client_assertion_type%3Durn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer%26client_assertion%3D%7B%7BclientAssertion%7D%7D

Response samples

Content type
application/json
Example
{
  • "auth_req_id": "FiKSlYqrvApAtE9uIirrWFsLb5l7wR9CWUfG4YqJiXw",
  • "expires_in": 600
}

Notificação de autorização

Lembrete: esse endpoint deve ser implementado pelo e-commerce, e não pela NuPay for Business.

header Parameters
Authorization
required
string

Token informado na requisição /backchannel/authentication na propriedade client_notification_token seguindo o formato: Bearer client_notification_token

Request Body schema: application/json
required
auth_req_id
required
string

Identificador único utilizado para associar o retorno da notificação no endpoint de callback, com a solicitação de autorização.

access_token
required
string

Access token gerado.

token_type
required
string

Tipo do token gerado.

refresh_token
required
string

Refresh token gerado.

expires_in
required
int

Tempo de expiração do access token em segundos.

id_token
required
string

Token JWT que atua como uma assinatura desanexada

error_description
required
string

Descrição do erro.

error
required
string

Código do erro.

Responses

Request samples

Content type
application/json
Example
{
  • "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6InhnbnlmbU9fSlhYMjZDMGNhaDZaSzk2TDBrVERWUy1fdHFMMzc0ODhNUWMifQ.eyJzdWIiOiJqaG9ubnkiLCJncmFudF90eXBlIjoidXJuOm9wZW5pZDpwYXJhbXM6Z3JhbnQtdHlwZTpjaWJhIiwic2NvcGUiOiJvcGVuaWQiLCJpc3MiOiJodHRwczovL3NhbmRib3gtYXV0aGVudGljYXRpb24uc3BpbnBheS5jb20uYnIiLCJleHAiOjE2OTU3MzY2NzMsImlhdCI6MTY5NTczNjM3MywiY2xpZW50X2lkIjoiMTAzODEyOTU5MjQzNTQiLCJqdGkiOiJCNkZRRmNWeU81RXBBRUNSc3pwdzg1MDM2MUc2U2ZkMG9OWmJaRVFBaWdZIn0.HJmTF3ShamzPJnbB-GNqZKOXRfxZutm50fT3yAkdR1MWcKsRwl-gF0VjoW0wg087Db7eZ9EjpwmYsUuarqS5s7yMr6Le6jwFF78RSDt_0cduwOHI6arbK6eBdBGeremrGoZf1EM5lzk3_eelO1XXpncubk8lsbnh4zqALILDzpVIh5DEPs_hAzeHkSORetnajk8heXC5Jl9PvnlS6Of7bbcfctxliEzDTm6BuiN__zt4b7snEiMslT8Srp2v2K2oagbAFovUPK0gDvyrxIV_Y9WmPrO6FShIYdinokwZ4baT7YgeOTZYGX0BBnkwkpAyXlbOIFUZBweEPWRTucj4WQ",
  • "token_type"": "Bearer",
  • "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
  • "expires_in": 120,
  • "id_token"": "eyJhbGciOiJIUzI1NiJ9.eyJhdF9oYXNoIjoiVko1Tk13QVlZWVBicFRTczg0QkctZyIsInN1YiI6bnVsbCwiYXVkIjoiMTAzODEyOTU5MjQzNTQiLCJ1cm46b3BlbmlkOnBhcmFtczpqd3Q6Y2xhaW06YXV0aF9yZXFfaWQiOiJzR0RxWldLdkd2ZzNqR2pMLUoxLXplbVMwSjhvWTBGOEx3UklTX1g3UURzIiwidXJuOm9wZW5pZDpwYXJhbXM6and0OmNsYWltOnJ0X2hhc2giOiJLTXpMenV0bV9vMWI3NXBmWnhLcVBRIiwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LWF1dGhlbnRpY2F0aW9uLnNwaW5wYXkuY29tLmJyIiwiZXhwIjoxNjk1ODIyNzczLCJpYXQiOjE2OTU3MzYzNzN9.KRx_tn9F7beWcSSv5H2l8k1LW5_UwuC3VcNRuKPIrZM"
}

Response samples

Content type
text/html
Autorização para web - OTP
Guia para implementação
Gerar autorização 
Esse endpoint deve ser chamado para iniciar o processo de autenticação via CIBA (Client-Initiated Backchannel Authentication) ou OTP (One-Time Password).


Authorizations:
(MerchantApiKeyMerchantApiToken) 
Request Body schema: application/x-www-form-urlencoded
 One of 
parameters
required
string
 
Dentro do campo parameters campos e valores devem ser concatenados como queryString.


Esperamos os seguintes parâmetros dentro de parameters:






Campo
Descrição





login_hint
CPF do cliente.




client_assertion_type
Deve sempre informar urn:ietf:params:oauth:client-assertion-type:jwt-bearer.




client_assertion
Token JWT gerado para autorização da requisição.




client_notification_token
É um bearer token fornecido pelo client e será usado pelo NuPay para autenticar o callback para o client. Para o auth_method=otp será a mesma informação do client_assertion.




scope
Deve sempre informar openid e charge. Caso queira consultar as condições de pagamento adicionar também payment_conditions.




auth_method
Se o método de autenticação escolhido for OTP deve sempre informar otp, caso contrário esse campo não deve ser informado.





Responses
Response Schema: application/json
 One of 
auth_req_id
string
 
Este é um identificador único para identificar o pedido de autenticação feito pelo parceiro.


masked_phone_number
string
 
Número de telefone do cliente mascarado ao qual foi enviado o SMS. Esse campo só será retornado caso o metódo de authenticação seja OTP e o SMS foi enviado com sucesso.


ticket
string
 
Ticket de autorização para o cliente. Esse campo só será retornado caso o metódo de authenticação seja OTP.


expires_in
number
 
Tempo de expiração do auth_req_id em segundos.


 Request samples 
Content type
application/x-www-form-urlencoded
parameters=login_hint%3D%7B%7BcustomerCPF%7D%7D%26scope%3Dopenid%26scope%3Dcharge%26scope%3Dpayment_conditions%26client_notification_token%3D%7B%7BclientNotificationToken%7D%7D%26client_assertion_type%3Durn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer%26client_assertion%3D%7B%7BclientAssertion%7D%7D
 Response samples 
Content type
application/json
Example
{
  • "auth_req_id": "FiKSlYqrvApAtE9uIirrWFsLb5l7wR9CWUfG4YqJiXw",
  • "expires_in": 600
}
Validar código OTP 
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.


Authorizations:
(MerchantApiKeyMerchantApiToken) 
Request Body schema: application/json
 One of 
parameters
required
string
 
Dentro do campo parameters campos e valores devem ser concatenados como queryString.


Esperamos os seguintes parâmetros obrigatórios dentro de parameters:






Campo
Descrição





login_hint
CPF do cliente.




client_assertion_type
Deve sempre informar urn:ietf:params:oauth:client-assertion-type:jwt-bearer.




client_assertion
Token JWT gerado para autorização da requisição.





ticket
required
string
 
Ticket de autorização para o cliente.


otp
required
string
 
Código de autenticação recebido pelo cliente.


Responses
Response Schema: application/json
 One of 
auth_code
string
 
Codigo de autorização, indicando que o cliente foi autenticado com sucesso.


access_token
string
 
Access token gerado


refresh_token
string
 
Refresh token gerado


 Request samples 
Content type
application/json
{
  • "parameters": "login_hint=<customer-CPF>&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=<client-assertion>",
  • "otp": "123456",
  • "ticket": "Ge24tKp1ahrTf5XCsqhPaGB239SD_2oT4gx8A-aRfoE"
}
 Response samples 
Content type
application/json
{
  • "access_token": "AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  • "refresh_token": "FiKSlYqrvApAtE9uIirrWFsLb5l7wR9CWUf"
}
Reenviar código OTP 
Esse endpoint deve ser chamado para reenviar o código OTP (One-Time Password) para o cliente.


Authorizations:
(MerchantApiKeyMerchantApiToken) 
Request Body schema: application/json
 One of 
login_hint
required
string
 
CPF do cliente que deseja reenviar o código.


ticket
required
string
 
Ticket de autorização gerado no primeiro passo da autenticação.


Responses
 Request samples 
Content type
application/json
{
  • "login_hint": "12345678909",
  • "ticket": "Ge24tKp1ahrTf5XCsqhPaGB239SD_2oT4gx8A-aRfoE"
}
 Response samples 
Content type
application/json
Example
{
  • "error": "invalid_request",
  • "error_description": "Invalid login_hint"
}
Tokens de autorização
Gerar refresh e access 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 solicitação de access_token for necessária.


Após o tempo de expiração do refresh_token, é necessário refazer o processo de autorização do NuPay.


Authorizations:
(MerchantApiKeyMerchantApiToken) 
Request Body schema: application/x-www-form-urlencoded
 One of 
client_assertion_type
required
string
 Default:  "urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer"
 
Envie o valor "urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer".


client_assertion
required
string
 
Token JWT gerado para autorização da request.


grant_type
required
string
 Default:  "authorization_code"
 
Envie o valor "authorization_code".


code_verifier
required
string
 
Valor utilizado para gerar o code_challenge da requisição para gerar a URL de autorização.


code
required
string
 
Recebido após a conclusão da autorização pelo cliente.


redirect_uri
required
string
 
URL de redirecionamento do e-commerce.
Deve ser o mesmo valor enviado para gerar a URL de autorização.


Responses
Response Schema: application/json
 One of 
access_token
string
 
Access token gerado.


token_type
string
 
Tipo do token gerado.


expires_in
number
 
Tempo de expiração do access token em segundos.


refresh_token
string
 
Refresh token gerado.


 Request samples 
Content type
application/x-www-form-urlencoded
Example
client_assertion_type=urn%253Aietf%253Aparams%253Aoauth%253Aclient-assertion-type%253Ajwt-bearer&client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....&grant_type=authorization_code&code=1e557cd9-31c8-4b60-86c6-3f8974416e7a&redirect_uri=https%3A%2F%2Fmerchant-domain.com%2Fredirect-uri&code_verifier=4alk121agfg
 Response samples 
Content type
application/json
Example
{
  • "access_token": "1ceb3a86-3a7e-479f-bee7-d8bb025809c2",
  • "token_type": "Bearer",
  • "expires_in": 300,
  • "refresh_token": "979d887a-2c63-4719-ba65-0b20b50f1cab"
}
Notificações de atualização de status de pedido 
Lembrete: esse endpoint deve ser implementado pelo e-commerce, e não pela NuPay for Business.


Consulte a seção sobre Notificações de eventos para mais detalhes.


path Parameters
callbackUrl
required
string
 
URL de callback fornecida na criação do pagamento.


header Parameters
X-Spin-Signature
string
 Deprecated 
 
 Example:  UVhslgtbavMol9u8iAQsy5NtmlcYZnfbJ7XtnlFzV7B9NNG7C6Z4RQj2k3+wWcJKUP9selY9UPGtgwgmvG6dfg==
Assinatura da chamada


X-Spin-Timestamp
string
 
 Example:  2020-01-01T14:22:18.572Z
Timestamp da chamada


Request Body schema: application/json
required
pspReferenceId
required
string
 
Identificador único do pedido no sistema


referenceId
required
string
 
Identificador único do pedido no sistema do e-commerce.


timestamp
required
string
 
Momento exato (ISO String) da mudança de estado.


paymentMethodType
required
string
 
Método de pagamento do pedido


Responses
 Request samples 
Content type
application/json
Example
{
  • "referenceId": "12345678900009876",
  • "pspReferenceId": "1e984614-1ce2-11ee-be56-0242ac120002",
  • "timestamp": "2023-07-01T10:10:20.512Z",
  • "paymentMethodType": "nupay"
}
 Response samples 
Content type
text/html
Notificações de atualização de status de estorno 
Lembrete: esse endpoint deve ser implementado pelo e-commerce, e não pela NuPay for Business.


Consulte a seção sobre Notificações de eventos para mais detalhes.


path Parameters
callbackUrl
required
string
 
URL de callback fornecida na criação do pagamento.


header Parameters
X-Spin-Signature
string
 Deprecated 
 
 Example:  UVhslgtbavMol9u8iAQsy5NtmlcYZnfbJ7XtnlFzV7B9NNG7C6Z4RQj2k3+wWcJKUP9selY9UPGtgwgmvG6dfg==
Assinatura da chamada


X-Spin-Timestamp
string
 
 Example:  2020-01-01T14:22:18.572Z
Timestamp da chamada


Request Body schema: application/json
required
pspReferenceId
required
string
 
Identificador único do pedido no sistema


transactionRefundId
required
string
 
Identificação da transação relacionada a esse estorno. Deve ser única por estorno.


Observação: Quando for enviado CREATED_BY_SELLER_PANEL, significa que o estorno
foi criado pelo painel do lojista e, portanto,
não possui o identificador único do e-commerce salvo na NuPay for Business.


refundId
required
string
 
Identificador único do pedido de estorno no sistema.


timestamp
required
string
 
Momento exato (ISO String) da mudança de estado.


referenceId
string
 
Identificador único do pedido no sistema do e-commerce.


Responses
 Request samples 
Content type
application/json
{
  • "referenceId": "12345678900009876",
  • "refundId": "0a0e00a0-3ea4-400f-b7d1-1647dfc129a9",
  • "pspReferenceId": "1e984614-1ce2-11ee-be56-0242ac120002",
  • "transactionRefundId": "8e4b308e-dbf3-4f98-901a-05a7955daff7",
  • "timestamp": "2023-07-01T10:10:20.512Z"
}
 Response samples 
Content type
text/html
Notificações de atualização de status de sessão de pagamento 
Lembrete: esse endpoint deve ser implementado pelo e-commerce, e não pela NuPay for Business.


As notificações são enviadas para a callbackUrl informada na criação da sessão quando a sessão é approved ou canceled pelo comprador no app, contendo apenas sessionId e reference. Não há notificação para expired nem para completed. A notificação não inclui assinatura JWS nem headers X-Spin-*. Por segurança, o novo status não é enviado: consulte o status atualizado pela rota GET /v1/checkouts/sessions/{sessionId}. Veja a seção NuPay 2FA com Sessões para mais detalhes.


path Parameters
callbackUrl
required
string
 
URL de callback fornecida na criação da sessão.


Request Body schema: application/json
required
sessionId
required
string
 
Identificador da sessão de pagamento cujo status mudou.


reference
required
string
 
O mesmo reference enviado na criação da sessão.


Responses
 Request samples 
Content type
application/json
{
  • "sessionId": "645a7eaa-4361-43b2-8749-575a1cd7dd4c",
  • "reference": "cart-123"
}
Condições de pagamento
Guia para implementação
Consultar condições de pagamento 
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 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íveis - Se paymentMethods for informado com valores específicos, o método será calculado a partir do valor fornecido - Para métodos não especificados em paymentMethods, será usado o valor de amount como padrão
    • 



O header Authorization é necessário somente para pagamentos pré-autorizados de NuPay.


Authorizations:
(MerchantApiKeyMerchantApiToken) 
header Parameters
Authorization
string
 
 Example:  Bearer UVhslgtbavMol9u8
Recebe o Bearer access_token.


Request Body schema: application/json
amount
required
number <double> 
 
Valor da compra. Usado como valor padrão quando não há um valor definido para um método de pagamento em paymentMethods.


document
string <string> 
 
CPF do usuário. Obrigatório caso não esteja no fluxo pré-autorizado de NuPay.


Array of objects (PaymentMethodInput) 
 
Lista de métodos de pagamento com valores específicos. Se não informado ou vazio, será usado o valor de amount para todos os métodos disponíveis.


Responses
Response Schema: application/json
 Array 
type
required
string
 Enum: "debit" "credit" "credit_with_additional_limit" 
 
Método de pagamento.


amount
required
number
 
Valor a ser pago.


required
Array of objects (PaymentConditionItem) 
 
Lista com as informações de parcelamento.


additionalLimitMessage
string
 
Mensagem do limite adicional que será aplicado. Exemplo - "Não consome limite do cartão" ou "R$ 999,00 para essa compra".


 Request samples 
Content type
application/json
Example
{
  • "document": "98765432108",
  • "amount": 100
}
 Response samples 
Content type
application/json
Example
[
  • {
    }
]