Recaudo Docs
Criar conta

Pagamentos e clientes

Assinaturas

As assinaturas permitem cobrar seus clientes de forma recorrente. Suportam períodos de teste, pausas e mudanças de plano.

POST /v1/subscriptions

Criar assinatura

Cria uma nova assinatura para um cliente. Você pode usar uma forma de pagamento salva ou um token do recaudo.js.

Tokenização: Você pode usar o parâmetro token com um token do recaudo.js (tok_xxx) em vez de payment_method. O token será convertido automaticamente em uma forma de pagamento salva.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
customer string (uuid) Sim ID do cliente
plan string (uuid) Sim ID do plano de assinatura
payment_method string (uuid) Não* ID da forma de pagamento salva. Obrigatório se não houver teste e não for usado token.
token string Não* Token do recaudo.js (tok_xxx para Conekta, pm_xxx para Stripe). Alternativa ao payment_method.
card object Não Informações do cartão do recaudo.js: { brand, last4, exp_month, exp_year }. Recomendado para melhor rastreamento
trial_days integer Não Dias de teste (0-365)
amount numeric Não Valor personalizado (substitui o do plano)
metadata object Não Dados adicionais 
curl -X POST https://recaudo.app/api/v1/subscriptions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "550e8400-e29b-41d4-a716-446655440000",
    "plan": "660e8400-e29b-41d4-a716-446655440001",
    "token": "tok_abc123def456",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027
    },
    "metadata": {
      "signup_source": "landing_page"
    }
  }'
curl -X POST https://recaudo.app/api/v1/subscriptions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "550e8400-e29b-41d4-a716-446655440000",
    "plan": "660e8400-e29b-41d4-a716-446655440001",
    "payment_method": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {
      "signup_source": "landing_page"
    }
  }'
Resposta 201 
{
  "id": "2b76a920-5381-4414-a2ae-34950faf16d7",
  "object": "subscription",
  "status": "active",
  "customer_id": "8e250c25-9d84-4892-98ec-d71fc1fcd3c7",
  "plan": {
    "id": "5f1c7b3e-2a94-4d18-b6c0-9e3f8a1d7c25",
    "name": "Premium Mensual",
    "amount": 299.00,
    "currency": "MXN",
    "interval": "month"
  },
  "current_period_start": "2024-01-15T00:00:00Z",
  "current_period_end": "2024-02-15T00:00:00Z",
  "trial_end": null,
  "cancel_at_period_end": false,
  "created_at": "2024-01-15T10:30:00Z"
}

Ações da assinatura

POST /v1/subscriptions/:id/cancel Cancelar assinatura 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/cancel \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{"cancel_at_period_end": true, "reason": "too_expensive"}'
POST /v1/subscriptions/:id/pause Pausar assinatura 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/pause \
  -H "Authorization: Bearer sk_live_xxx"
POST /v1/subscriptions/:id/resume Retomar assinatura 
curl -X POST https://recaudo.app/api/v1/subscriptions/2b76a920-5381-4414-a2ae-34950faf16d7/resume \
  -H "Authorization: Bearer sk_live_xxx"
Esta página ajudou? Obrigado por avisar.
Esc