Guias
Página de statusDashboardAgende uma demonstração
Comece a digitar para pesquisar...

NuPay

Este guia explora a integração do NuPay da Yuno usando o fluxo de trabalho Direct. Você aprenderá a:

  • Registre o NuPay como um método de pagamento do cliente
  • Efetuar pagamentos em parcelas (condições de pagamento)
  • Configurar assinaturas

Requisitos

Antes de começar, você precisa:

  • Uma conta Yuno com acesso ao Dashboard
  • Chaves de API e um account_id (encontrado no painel de controle)
  • Um cliente criado no Yuno (ou crie um na Etapa 1)

Criar e gerenciar clientes

Crie o cliente uma vez usando seu sistema externo merchant_customer_ide, em seguida, recuperado por Yuno id ou por merchant_customer_id conforme necessário.

  1. Use o Criar o cliente e fornecer seu próprio merchant_customer_id (o ID exclusivo do cliente em seu sistema). A resposta retorna id que é o ID do cliente Yuno.
  2. Uso Recuperar cliente com a Yuno id.
  3. Uso Recuperar cliente por ID externo com o parâmetro de consulta merchant_customer_id.

Registrar o método de pagamento NuPay

Siga estas etapas para se registrar NU_PAY_ENROLLMENT para um cliente usando o fluxo de trabalho Direct.

Etapa 1: Criar um cliente

Se você ainda não tiver um cliente, crie um conforme mostrado acima. Você usará o cliente retornado id.

Etapa 2: Registre o método de pagamento

Use Enroll Payment Method (Registrar método de pagamento ) com os seguintes parâmetros de solicitação:

  • tipo: NU_PAY_ENROLLMENT
  • account_id: UUID de sua conta (do Painel de Controle do Yuno)
  • workflow: DIRECT

Campos de resposta esperados:

  • vaulted_token: UUID para o método de pagamento registrado
  • status: READY_TO_ENROLL
  • sub_status: WAITING_ADDITIONAL_STEP
  • ação: REDIRECT_URL
  • redirect_url: URL para redirecionar o cliente para Nu para autenticação

Etapa 3: Redirecionar o cliente

Redirecionar o cliente para o redirect_url. O cliente conclui o fluxo da Nu. A Nu notifica a Yuno sobre o estado final.

Etapa 4: Confirmar a inscrição

Uso Recuperar o método de pagamento registrado por id com o vaulted_token. Um registro bem-sucedido retorna:

  • status: ENROLLED
  • sub_status: ENROLLED
⚠️

O registro só é concluído depois que Yuno recebe a confirmação de Nu.

Pagamentos com condições de pagamento (parcelas)

Após o registro, você pode aceitar pagamentos com o NuPay usando as condições de pagamento.

Etapa 1: Garantir os pré-requisitos

Ter um cliente Yuno id e um NuPay inscrito vaulted_token.

Etapa 2: Obter condições de pagamento

Solicite as opções de parcelamento disponíveis para o NuPay usando o endpoint parcelamento do APM.

curl --location 'https://api-sandbox.y.uno/v1/apm-installments' \
--header 'public-api-key: {{your_public_api_key}}' \
--header 'private-secret-key: {{your_secret_api_key}}' \
--header 'X-account-code: {{your_account_code}}' \
--header 'Content-Type: application/json' \
--data '{
  "country": "BR",
  "amount": {
    "currency": "BRL",
    "value": "250"
  },
  "customer": {
    "id": "{{customer_id}}"
  },
  "payment_method": "NU_PAY_ENROLLMENT",
  "vaulted_token": "{{vaulted_token}}"
}'

A resposta retorna uma matriz de planos de parcelamento, incluindo id, disponível installmentse valores. Selecione um plano id e um número de parcelas permitidas.

Etapa 3: Criar pagamento

Uso Criar o pagamento com o fluxo de trabalho Direct e o tipo NuPay. Incluir o ID do plano selecionado e as parcelas na carteira card_data.

{
  "description": "test",
  "account_id": "{{account_id}}",
  "merchant_order_id": "0000023",
  "country": "BR",
  "merchant_reference": "ref-merchant-AA01",
  "amount": {
    "currency": "BRL",
    "value": 250
  },
  "customer_payer": {
    "id": "{{customer_id}}"
  },
  "workflow": "DIRECT",
  "callback_url": "https://your-callback.com",
  "payment_method": {
    "type": "NU_PAY_ENROLLMENT",
    "vaulted_token": "{{vaulted_token}}",
    "detail": {
      "wallet": {
        "card_data": {
          "installments_plan_id": "{{plan_id}}",
          "installments": 2
        }
      }
    }
  }
}

Etapa 4: Recuperar o pagamento

Use Retrieve payment by id para confirmar o status final.

Fluxo de assinaturas

Você pode usar o NuPay para cobranças recorrentes.

  1. Criar um cliente
  2. Registre o NuPay como um método de pagamento (veja acima)
  3. Criar uma assinatura com o inscrito vaulted_token usando Criar assinatura
  4. Recupere a assinatura usando Retrieve subscription (Recuperar assinatura)
⚠️

Limitações

  • As assinaturas com NuPay não suportam condições de pagamento (parcelas)
  • Não há suporte para a criação de assinaturas diretamente em uma solicitação de pagamento

Endpoints

Atualizado há 3 meses