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

Cancelar e capturar fluxo

Ao se integrar com o Yuno, você tem várias opções para implementar operações de captura e cancelamento. Este guia descreve todas as abordagens disponíveis e explica como interagir com nossas APIs para cada cenário.

Oferecemos captura simples em tempo real para transações rápidas, bem como configurações altamente personalizáveis de captura com atraso e cancelamento para atender às suas necessidades comerciais.

Visão geral

Modos de captura

A Yuno oferece três opções para a captura de pagamentos, determinadas pelo capture e o campo opcional delayed_capture_settings encontrada na configuração criar API de pagamento. A disponibilidade real do recurso ou os detalhes específicos da implementação podem variar dependendo do provedor de pagamento pelo qual você está encaminhando seus pagamentos.

Captura em tempo real

Este modo processa o pagamento e transfere os fundos sem qualquer atraso, combinando eficazmente a autorização e a captura em um único processo. compra operação. Quando payment_method.detail.card.capture é definido como true, a transação é executada como uma compra, o que significa que a autorização e a captura ocorrem simultaneamente.

Dependendo da API do provedor de pagamento, a Yuno pode executar isso como uma transação de compra direta ou como uma autorização imediatamente seguida por uma chamada de captura.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          // card details
        }
      }
    }
  }
}

Captura manual

Com essa configuração, o Yuno não capturará o pagamento até que você chame a função API de captura ou capturá-lo manualmente em seu Painel de controle da Yuno. Definir capture: false para autorizar o pagamento sem capturá-lo.

As capturas manuais proporcionam o máximo de flexibilidade, pois dão a você controle total de quando a captura é realizada. Entretanto, é importante capturar o mais rápido possível, pois os provedores de pagamento impõem limites de tempo para que as autorizações permaneçam não capturadas, e esses limites variam de acordo com o provedor e a região.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          // card details
        }
      }
    }
  }
}
🚧

Captura de valores diferentes

Se você precisar capturar um valor diferente do originalmente autorizado, deverá usar a captura manual. Os modos de captura em tempo real e com atraso sempre capturarão o valor autorizado inicialmente.

Captura atrasada

Configurar capture: false juntamente com delayed_capture_settings para agendar a captura do pagamento para um momento posterior, especificado no delay campo.

🚧

Capturas apenas do valor total

A captura atrasada só se aplica quando se captura o valor total da autorização. Se precisar capturar um valor parcial, você deve usar a captura manual.

📘

simplified_mode

Configuração simplified_mode para true fará com que o Yuno tente novamente a operação de captura caso ocorra um erro durante a tentativa de captura programada.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}

O delay é necessário ao usar operações de captura atrasadas e deve seguir o Norma ISO 8601. Por exemplo:

  • "PT3H" por 3 horas
  • "P7D" por 7 dias
  • "P1M" por 1 mês

Se você chamar a API de captura antes do horário programado, sua chamada substituirá o atraso e executará a captura imediatamente. Essa ação cancela automaticamente o acionador Yuno programado. Como alternativa, você pode capturar o pagamento manualmente através do seu painel Yuno.

Cancelar modos

Quando você autoriza um pagamento sem capturá-lo imediatamente, esses fundos são retidos temporariamente no método de pagamento do cliente. Se você decidir não capturar o pagamento, é importante cancelar a autorização para liberar esses fundos retidos e proporcionar uma melhor experiência ao cliente. Os modos de cancelamento lhe dão controle sobre quando e como essas autorizações são anuladas.

Cancelamento manual

Com o modo de cancelamento manual, os pagamentos autorizados permanecem ativos até que você os cancele explicitamente. O Yuno não anulará automaticamente essas autorizações, dando a você controle total sobre quando liberar os fundos. Você pode cancelar autorizações usando a API de cancelamento ou por meio da interface do painel do Yuno.

É fundamental cancelar as autorizações que não serão capturadas o mais rápido possível para liberar os fundos retidos. A experiência do cliente é significativamente afetada quando as autorizações não são canceladas, pois os fundos podem permanecer reservados por períodos variáveis, dependendo da região do cliente e da rede de cartões.

Cancelamento atrasado

Configurar delayed_cancel_settings para definir um atraso no cancelamento de autorizações não capturadas, semelhante às capturas atrasadas. Esse recurso automatiza a liberação dos fundos do cliente se você decidir não capturá-los dentro de um período de tempo especificado, melhorando significativamente a experiência do cliente ao evitar retenções indefinidas em seus métodos de pagamento.

O delay é necessário ao usar operações de cancelamento atrasado e deve seguir o campo Norma ISO 8601. Por exemplo:

  • "PT3H" por 3 horas
  • "P7D" por 7 dias
  • "P30D" por 30 dias
📘

simplified_mode

Configuração simplified_mode para true fará com que o Yuno tente novamente a operação de cancelamento caso ocorra um erro durante a tentativa de cancelamento programada.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}

Se você chamar a API de captura ou cancelar a API antes do horário programado, sua chamada substituirá o atraso e executará a ação imediatamente. Essa ação cancela automaticamente o acionador Yuno programado. Alternativamente, você pode capturar ou cancelar o pagamento manualmente através do seu painel Yuno.

⚠️

Configurações de captura atrasada e cancelamento

Recomendamos não usar ambos delayed_capture_settings e delayed_cancel_settings simultaneamente para evitar comportamentos inesperados. Use apenas um de cada vez de acordo com suas necessidades.

Requisitos de configuração

  • delayed_capture_settings e delayed_cancel_settings são válidos apenas quando capture = false
  • Se capture = trueesses objetos devem ser omitidos ou definidos como null
  • As operações manuais podem ser realizadas por meio de endpoints da API ou pelo painel do Yuno

Exemplos de solicitações

Exemplo 1: Captura em tempo real

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Real-time capture payment",
  "merchant_order_id": "000023"
}

Exemplo 2: Apenas captura manual

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization only - manual capture",
  "merchant_order_id": "000024"
}

Exemplo 3: Captura atrasada

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed capture",
  "merchant_order_id": "000025"
}

Exemplo 4: Cancelamento atrasado

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed cancel",
  "merchant_order_id": "000026"
}

Exemplo 5: Captura e cancelamento combinados com validação aprimorada

Este exemplo mostra uma solicitação de pagamento completa com configurações de captura atrasada e cancelamento, juntamente com campos de validação do cliente aprimorados:

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "merchant_customer_validations": {
      "account_is_verified": true,
      "email_is_verified": true,
      "phone_is_verified": true
    },
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P20D",
          "simplified_mode": true
        },
        "delayed_cancel_settings": {
          "delay": "P40D",
          "simplified_mode": true
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        },
        "verify": false
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Payment with card details",
  "merchant_order_id": "000023"
}
⚠️

Observação

Embora este exemplo mostre ambos delayed_capture_settings e delayed_cancel_settings configurados juntos, recomendamos usar apenas um de cada vez para evitar comportamentos inesperados.

Quando usar cada modo

Use a captura em tempo real quando:

  • Você fornece bens ou serviços imediatamente
  • Não é necessário validar o inventário ou as verificações de fraude após a autorização
  • Você deseja o fluxo de pagamento mais simples

Use a captura manual quando:

  • Você precisa verificar o inventário antes de finalizar o pagamento
  • Você deseja capturar um valor diferente do autorizado
  • Você tem uma lógica comercial complexa que determina se deve capturar ou cancelar
  • Você precisa de controle máximo sobre o tempo de captura

Use a captura atrasada quando:

  • Você deseja a captura automática após um período de tempo específico
  • Você tem um processo de atendimento previsível
  • Você deseja reduzir a intervenção manual e, ao mesmo tempo, manter o controle

Use o cancelamento atrasado quando:

  • Você deseja liberar automaticamente os fundos do cliente se não fizer a captura dentro de um período de tempo
  • Você deseja melhorar a experiência do cliente ao não reter fundos indefinidamente
  • Você tem um limite máximo de tempo para seu processo de atendimento

Referência de campo

CampoTipoDescrição
capturebooleanDetermina se o pagamento com cartão é capturado imediatamente (true, compra) ou somente autorizado (falserequer captura ou cancelamento).
delayed_capture_settings.delaystringAtraso antes de a Yuno capturar o pagamento. Deve seguir o formato de duração ISO 8601 (por exemplo, "P7D" para 7 dias, "PT3H" para 3 horas).
delayed_capture_settings.simplified_modebooleanSe trueO Yuno tenta novamente a captura se ela falhar.
delayed_cancel_settings.delaystringAtraso antes que a Yuno cancele a autorização. Deve seguir o formato de duração ISO 8601 (por exemplo, "P30D" para 30 dias).
delayed_cancel_settings.simplified_modebooleanSe trueYuno tenta novamente o cancelamento se ele falhar.

Atualizado há 2 meses