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!

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)
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": [
    ],
  • "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"
}

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": {
    }
}

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.

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
{
  • "auth_req_id": "FiKSlYqrvApAtE9uIirrWFsLb5l7wR9CWUfG4YqJiXw",
  • "masked_phone_number": "(11)xxxxx-1234",
  • "ticket": "AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  • "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.


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
{
  • "auth_req_id": "FiKSlYqrvApAtE9uIirrWFsLb5l7wR9CWUfG4YqJiXw",
  • "masked_phone_number": "(11)xxxxx-1234",
  • "ticket": "AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  • "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
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.




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.


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


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
{
  • "amount": 0.1,
  • "document": "string"
}
 Response samples 
Content type
application/json
Example
[
  • {
    }
]
Condições de pagamento com Token
Guia para implementação
Consultar condições de pagamento com Token  Deprecated 
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. Não utilize cache para esta consulta.




Importante: Para consultar as condições de pagamento, verifique se a autorização foi feita com o escopo payment_conditions.




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


Authorizations:
(MerchantApiKeyMerchantApiToken) 
query Parameters
amount
required
number <double> 
 
Valor a ser pago.


header Parameters
Authorization
required
string
 
 Example:  Bearer UVhslgtbavMol9u8
Recebe o Bearer access_token.


Responses
Response Schema: application/json
type
required
string
 
Método de pagamento.


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


amount
required
number
 
Valor a ser pago.


 Response samples 
Content type
application/json
Example
[
  • {
    },
  • {
    }
]
Condições de pagamento CPF
Guia para implementação
Consultar condições de pagamento com CPF  Deprecated 
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.


Authorizations:
(MerchantApiKeyMerchantApiToken) 
Request Body schema: application/json
amount
required
number <double> 
 
Valor da compra.


document
required
string <string> 
 
CPF do usuário.


Responses
Response Schema: application/json
type
required
string
 
Método de pagamento.


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


amount
required
number
 
Valor a ser pago.


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