> For the complete documentation index, see [llms.txt](https://docs.yoplanning.support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yoplanning.support/pt/developpeur/tutoriel-dacces-au-catalogue/yoplanning-payment-manager-api-documentation.md). # Documentação da API do YoPlanning Payment Manager ### `POST /api/create-payment` Cria um link de pagamento (Stripe) e retorna um URL para o qual o cliente será redirecionado. **URL base**: `https://payment.yoplanning.pro` *** ### Autenticação O Gerenciador de Pagamentos utiliza **autenticação baseada em token**, separada do token principal da API do YoPlanning. ``` Authorization: Token Content-Type: application/json ``` > **Importante:** O token do Gerenciador de Pagamentos **não** é o mesmo que o token da API v3.1 do YoPlanning. São dois tokens distintos. Usar o token errado resultará em um erro `401 "Token inválido."`. | Token | Usado para | Onde encontrar | | -------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | Token da API do YoPlanning | `yoplanning.pro/api/v3.1/*` (disponibilidade, pedidos, etc.) | Back office > API > Tokens | | **Token do Gerenciador de Pagamentos** | `payment.yoplanning.pro/api/*` | Painel administrativo > Configurações de pagamento > Token da API | *** ### Solicitar ``` POST https://payment.yoplanning.pro/api/create-payment Authorization: Token Content-Type: application/json ``` #### Parâmetros corporais | Campo | Obrigatório | Tipo | Descrição | | --------------------------------------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------------- | | `order_id` | Sim | corda | Seu identificador de pedido (ou seja, o UUID retornado por `/order-typicalvalidation`) | | `vendor_id` | Sim | string (UUID) | Seu identificador de fornecedor (encontrado nas suas configurações de pagamento do YoPlanning) | | `preço` | Sim | número | Valor total na unidade principal da moeda (ex.: `196,00` para 196 euros). **Não em cêntimos.** | | `moeda` | Sim | corda | Código de moeda ISO 4217 (ex.: "EUR", "USD") | | `callback_url` | Sim | string (URL) | URL de notificação IPN — deve ser de acesso público. É chamada via POST quando o pagamento é concluído. | | `url_de_redirecionamento` | Não | string (URL) | Para onde redirecionar o cliente após um pagamento bem-sucedido? | | `cancel_url` | Não | string (URL) | Para onde redirecionar o cliente caso ele cancele? | | `payer_email` | Não | corda | Preenche automaticamente o campo de e-mail na página de pagamento. | | `nome_do_titular_do_cartão` | Não | corda | Preenche automaticamente o primeiro nome do titular do cartão. | | `sobrenome_do_titular_do_cartão` | Não | corda | Preenche automaticamente o sobrenome do titular do cartão. | | `linha_endereço_de_cobrança1` | Não | corda | Linha 1 do endereço de cobrança | | `linha_de_endereço_de_cobrança2` | Não | corda | Linha 2 do endereço de cobrança | | `cidade_do_endereço_de_cobrança` | Não | corda | Cidade | | `código postal do endereço de cobrança` | Não | corda | Código postal | | `país do endereço de cobrança` | Não | corda | País | | `estado_do_endereço_de_cobrança` | Não | corda | Estado/Região | #### Notas importantes * **O campo se chama `price`, não `amount`.** Enviar `amount` em vez de `price` resultará em um erro `500 Internal Server Error`, pois o servidor receberá `price=None`. * **O preço deve estar em euros (ou na sua moeda), não em cêntimos.** Envie `196.00`, não `19600`. * **O parâmetro `callback_url` é obrigatório**, mesmo que você não processe ativamente as notificações IPN. A omissão desse parâmetro resultará em um erro de validação. * O Gerenciador de Pagamentos é um **serviço de link de pagamento único** — ele considera o preço total, não a discriminação de itens individuais. Os itens do pedido pertencem à API de reservas do YoPlanning (`/order-validation`), não a este serviço. *** ### Resposta #### Sucesso (`200`) ``` {  "success": true,  "payment_id": "179384e3-4e32-4f03-b6ea-2fdc998e2c6c",  "customer_id": null,  "vakario_fee": "0.00",  "payment_solution": "Stripe",  "payment_url": "https://payment.yoplanning.pro/pay/8edf6170-5495-432d-8b04-6717ccb8ad68" } ``` | Campo | Tipo | Descrição | | ---------------------- | -------------- | ------------------------------------------------------------------ | | `sucesso` | booleano | `true` se o link de pagamento foi criado | | `payment_id` | string (UUID) | Identificador de pagamento exclusivo | | `id_do_cliente` | string ou nulo | Identificação do cliente, se reconhecida. | | `vakario_fee` | corda | Taxa da plataforma (cadeia decimal) | | `solução_de_pagamento` | corda | Provedor de pagamento utilizado (“Stripe”) | | `payment_url` | string (URL) | **Redirecione o cliente para este URL para concluir o pagamento.** | #### Erro de validação (`400`) ``` {  "success": false,  "errors": {    "callback_url": ["This field is required."] } } ``` #### Erro de autenticação (`401`) Sem cabeçalho `Authorization`: ``` {"detail": "Authentication credentials were not provided."} ``` Token incorreto (por exemplo, usar o token da API do YoPlanning em vez do token do Gerenciador de Pagamentos): ``` {"detail": "Invalid token."} ``` #### Erro do servidor (`500`) Retorna uma página de erro HTML (não JSON) com a mensagem *"A plataforma de pagamento está temporariamente indisponível."* Isso **não** é uma interrupção real da plataforma. Na prática, os erros 500 são causados ​​por: | Causa raiz | Erro no servidor | Consertar | | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | O campo `price` está ausente ou é `nulo`. | `TypeError: '>' não suportado entre instâncias de 'NoneType' e 'int'` em `checkPaymentSolution` | Certifique-se de que `price` seja um número no corpo JSON. O campo se chama `price`, não `amount`. | | `vendor_id` ausente ou inválido | Vários erros em formulários do Django | Certifique-se de que `vendor_id` seja uma string UUID válida. | > A resposta 500 retorna HTML, não JSON. Analise o código com cuidado se você espera JSON. *** ### Retorno de chamada IPN Quando o pagamento for concluído (ou falhar), o Gerenciador de Pagamentos enviará uma solicitação `POST` para o seu `callback_url`: ``` {  "success": true,  "payed": true,  "order_id": "your-order-id",  "payment_solution": "Stripe",  "payer_lang": "fr" } ``` | Campo | Tipo | Descrição | | ---------------------- | -------- | ---------------------------------------------------- | | `sucesso` | booleano | Se o pagamento foi bem-sucedido | | `pago` | booleano | Se o pagamento foi efetuado. | | `order_id` | corda | O `order_id` que você informou ao criar o pagamento. | | `solução_de_pagamento` | corda | Fornecedor utilizado | | `payer_lang` | corda | Idioma do navegador do pagador | Requisitos para `callback_url`: * Deve ser de acesso público (sem autenticação) * Deve aceitar solicitações POST. * Deve retornar um código de status 2xx *** ### Exemplo completo #### cURL ``` curl -X POST "https://payment.yoplanning.pro/api/create-payment" \  -H "Authorization: Token YOUR_PAYMENT_MANAGER_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "vendor_id": "your-vendor-uuid",    "price": 196.00,    "currency": "EUR",    "payer_email": "customer@example.com",    "cardholder_first_name": "Jean",    "cardholder_last_name": "Dupont",    "callback_url": "https://yoursite.com/api/payment-callback",    "redirection_url": "https://yoursite.com/confirmation?status=success",    "cancel_url": "https://yoursite.com/confirmation?status=cancelled" }' ``` #### JavaScript (buscar) ``` const response = await fetch('https://payment.yoplanning.pro/api/create-payment', {  method: 'POST',  headers: {    'Authorization': 'Token YOUR_PAYMENT_MANAGER_TOKEN',    'Content-Type': 'application/json', },  body: JSON.stringify({    order_id: orderId,    vendor_id: 'your-vendor-uuid',    price: 196.00,       // euros, NOT cents    currency: 'EUR',    payer_email: 'customer@example.com',    callback_url: 'https://yoursite.com/api/payment-callback',    redirection_url: 'https://yoursite.com/confirmation?status=success',    cancel_url: 'https://yoursite.com/confirmation?status=cancelled', }), }); ​ const data = await response.json(); ​ if (data.success && data.payment_url) {  // Redirect customer to payment page  window.open(data.payment_url, '_blank'); } ``` #### Python (requisições) ``` import requests ​ response = requests.post(    "https://payment.yoplanning.pro/api/create-payment",    headers={        "Authorization": "Token YOUR_PAYMENT_MANAGER_TOKEN",        "Content-Type": "application/json",   },    json={        "order_id": order_id,        "vendor_id": "your-vendor-uuid",        "price": 196.00,        "currency": "EUR",        "payer_email": "customer@example.com",        "callback_url": "https://yoursite.com/api/payment-callback",        "redirection_url": "https://yoursite.com/confirmation?status=success",        "cancel_url": "https://yoursite.com/confirmation?status=cancelled",   }, ) ​ data = response.json() payment_url = data.get("payment_url") ``` *** ### Fluxo de integração típico ``` 1. Customer selects dates and products         │         ▼ 2. Check availability   GET yoplanning.pro/api/v3.1/teams/{team}/online-products/{product}/availabilities/         │         ▼ 3. Validate the order   POST yoplanning.pro/api/v3.1/teams/{team}/order-validation   → Returns order ID         │         ▼ 4. Create payment link   POST payment.yoplanning.pro/api/create-payment   → Returns payment_url         │         ▼ 5. Redirect customer to payment_url (Stripe checkout)         │         ▼ 6. Customer pays → redirected to redirection_url   Payment Manager POSTs to callback_url (IPN) ``` *** ### CORS A API do Gerenciador de Pagamentos **não** retorna cabeçalhos CORS. Chamadas diretas de um navegador serão bloqueadas pela política de mesma origem do navegador. **Soluções**: * Utilize um proxy do lado do servidor (por exemplo, Cloudflare Worker, backend Node.js, função sem servidor) para encaminhar solicitações. * Chame a API a partir do seu backend, não do JavaScript do lado do cliente. *** ### Perguntas frequentes **P: Recebo o erro `401 "Token inválido"`, mas meu token funciona na API do YoPlanning.** R: O Gerenciador de Pagamentos possui seu próprio token, separado do token da API v3.1 do YoPlanning. Verifique suas configurações de pagamento no painel administrativo para obter o token correto. **P: Recebo uma página de erro HTML `500` em vez de JSON.** R: Isso quase sempre significa que um campo obrigatório está faltando ou é `nulo`. Verifique se o `price` (e não o `amount`) é um número no corpo da sua requisição. Verifique também se o `vendor_id` está presente e é válido. **P: Meu `callback_url` ainda não está acessível. Posso ignorá-lo?** R: Não, o `callback_url` é obrigatório. Você pode apontar para uma URL de espaço reservado que retorne 200, mas o campo deve estar presente. **P: Preciso passar os itens da linha do pedido para o Gerenciador de Pagamentos?** R: Não. O Gerenciador de Pagamentos apenas processa o pagamento — ele recebe um valor fixo. Os itens da linha pertencem à API de pedidos do YoPlanning (`/order-validation`). **P: O preço está em centavos ou na unidade monetária principal?** R: Unidade monetária principal. Para EUR, envie `196,00`, não `19600`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.yoplanning.support/pt/developpeur/tutoriel-dacces-au-catalogue/yoplanning-payment-manager-api-documentation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.