---
updatedAt: 2026-04-06T17:18:47.000Z
agentTools:
  projectIndex: https://docs.pagar.me/v1/llms.txt
---

# Criando assinaturas

Para efetivamente cobrar seu cliente de forma recorrente, você deve criar uma assinatura atrelada a um plano que conterá os dados de cobrança.

Sendo que a criação de uma subscription (assinatura), é parecida com a criação de uma transação. Se for uma assinatura paga com cartão, é possível usar um card_id, card_hash ou todos os dados do cartão. Enquanto para boleto, você precisa especificar apenas o payment_method.

## Dados necessários para uma assinatura

> ❗️ Produto descontinuado
>
> A Pagar.me **não permite nova integrações na API de recorrência v1** (esta página). Para nova integrações do produto de recorrência, utilizar a [API v5.](https://docs.pagar.me/docs/overview-recorr%C3%AAncia)

> 📘 Dados obrigatórios
>
> O email do cliente é uma informação obrigatória, uma vez que utilizamos ele para enviar emails de assinatura.

> 🚧 Antifraude
>
> A primeira transação criada em uma assinatura passa por antifraude, logo, é obrigatório enviar todos os dados de customer.

## Valores de uma assintura

> ❗️ Dando descontos na assinatura
>
> Apenas através de troca para um plano mais barato, mas vale ressaltar que isso gera uma nova periodicidade. Mais em: [Fluxo de cobrança](https://docs.pagar.me/v1/docs/fluxo-de-cobranca).

## Observações

> 📘 ID do plano
>
> Lembre-se de passar o id de seu plano em todas as requests, para que não seja necessário recriar todas assinaturas que ficaram com plan\_id = null.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "api-settings",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.pagar.me/1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "x-default": "",
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/subscriptions": {
      "post": {
        "summary": "Criando assinaturas",
        "description": "Para efetivamente cobrar seu cliente de forma recorrente, você deve criar uma assinatura atrelada a um plano que conterá os dados de cobrança.\n\nSendo que a criação de uma subscription (assinatura), é parecida com a criação de uma transação. Se for uma assinatura paga com cartão, é possível usar um card_id, card_hash ou todos os dados do cartão. Enquanto para boleto, você precisa especificar apenas o payment_method.",
        "operationId": "criando-assinaturas",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id",
                  "card_hash",
                  "card_number",
                  "card_cvv",
                  "card_holder_name",
                  "card_expiration_date",
                  "card_id"
                ],
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "description": "id do plano a ser associado a uma assinatura"
                  },
                  "payment_method": {
                    "type": "string",
                    "description": "Método de pagamento da assinatura. Aceita dois tipos: credit_card e boleto"
                  },
                  "card_hash": {
                    "type": "string",
                    "description": "Dados encriptados do cartão do cliente. Você também pode usar o card_id ao invés do card_hash"
                  },
                  "card_number": {
                    "type": "string",
                    "description": "Número do cartão, se for uma assinatura de cartão",
                    "default": "!CARD_NUMBER!"
                  },
                  "card_cvv": {
                    "type": "string",
                    "description": "Cvv do cartão, se for uma assinatura paga com cartão",
                    "default": "!CARD_CVV!"
                  },
                  "card_holder_name": {
                    "type": "string",
                    "description": "Nome do detentor do cartão se for uma assinatura paga com cartão",
                    "default": "!NAME!"
                  },
                  "card_expiration_date": {
                    "type": "string",
                    "description": "Data de expiração do cartão, se for uma assinatura paga com cartão",
                    "default": "!CARD_EXPIRATION_DATE!"
                  },
                  "card_id": {
                    "type": "string",
                    "description": "Id do cartão a ser cobrado, se for uma assinatura paga com cartão"
                  },
                  "postback_url": {
                    "type": "string",
                    "description": "URL onde nossa API irá enviar requisições informando alterações de status da assinatura em questão"
                  },
                  "customer": {
                    "properties": {
                      "email": {
                        "type": "string",
                        "description": "Email do cliente",
                        "default": "!EMAIL!"
                      },
                      "name": {
                        "type": "string",
                        "description": "Nome completo ou razão social do cliente que está realizando a transação",
                        "default": "!NAME!"
                      },
                      "document_number": {
                        "type": "string",
                        "description": "CPF ou CNPJ do cliente, sem separadores",
                        "default": "!DOCUMENT_NUMBER!"
                      },
                      "address": {
                        "properties": {
                          "street": {
                            "type": "string",
                            "description": "logradouro (rua, avenida, etc) do cliente",
                            "default": "!STREET!"
                          },
                          "street_number": {
                            "type": "string",
                            "description": "Número da residência/estabelecimento do cliente",
                            "default": "!STREET_NUMBER!"
                          },
                          "complementary": {
                            "type": "string",
                            "description": "complemento do endereço do cliente"
                          },
                          "neighborhood": {
                            "type": "string",
                            "description": "bairro de localização do cliente",
                            "default": "!NEIGHBORHOOD!"
                          },
                          "zipcode": {
                            "type": "string",
                            "description": "CEP do imóvel do cliente, sem separadores",
                            "default": "!ZIPCODE!"
                          }
                        },
                        "required": [
                          "street",
                          "street_number",
                          "neighborhood",
                          "zipcode"
                        ],
                        "type": "object"
                      },
                      "phone": {
                        "properties": {
                          "ddd": {
                            "type": "string",
                            "description": "DDD do telefone do cliente",
                            "default": "!PHONE_DDD!"
                          },
                          "number": {
                            "type": "string",
                            "description": "número de telefone do cliente",
                            "default": "!PHONE_NUMBER!"
                          }
                        },
                        "required": [
                          "ddd",
                          "number"
                        ],
                        "type": "object"
                      },
                      "sex": {
                        "type": "string",
                        "description": "sexo do cliente"
                      },
                      "born_at": {
                        "type": "string",
                        "description": "Data de nascimento do cliente. Ex: 11-02-1985",
                        "format": "date"
                      }
                    },
                    "required": [
                      "email",
                      "name",
                      "document_number"
                    ],
                    "type": "object"
                  },
                  "metadata": {
                    "type": "string",
                    "description": "Você pode passar dados adicionais na criação da transação para facilitar uma futura análise de dados tanto em nossa dashboard, quanto por seus sistemas. Ex: metadata[ idProduto ]=13933139",
                    "format": "json"
                  },
                  "reference_key": {
                    "type": "string",
                    "description": "Valor único que identifica a transação para permitir uma nova tentativa de requisição com a segurança de que a mesma operação não será executada duas vezes acidentalmente. **OBS**: Não pode ser igual a um valor já usado em uma criação de transação"
                  },
                  "boleto_fine": {
                    "properties": {
                      "days": {
                        "type": "integer",
                        "description": "Dias após a expiração do boleto quando a multa deve ser cobrada",
                        "format": "int32"
                      },
                      "amount": {
                        "type": "integer",
                        "description": "Valor em centavos da multa por atraso no pagamento do boleto",
                        "format": "int32"
                      },
                      "percentage": {
                        "type": "string",
                        "description": "Valor em porcentagem da multa por atraso no pagamento do boleto"
                      }
                    },
                    "required": [],
                    "type": "object"
                  },
                  "boleto_interest": {
                    "properties": {
                      "days": {
                        "type": "integer",
                        "description": "Dias após a expiração do boleto quando o juros deve ser cobrado",
                        "format": "int32"
                      },
                      "amount": {
                        "type": "integer",
                        "description": "Valor em centavos da taxa de juros que será cobrado por dia de atraso do boleto",
                        "format": "int32"
                      },
                      "percentage": {
                        "type": "string",
                        "description": "Valor em porcentagem da taxa de juros que será cobrado por dia de atraso do boleto"
                      }
                    },
                    "required": [],
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"object\": \"subscription\",\n    \"plan\": {\n        \"object\": \"plan\",\n        \"id\": 12783,\n        \"amount\": 31000,\n        \"days\": 30,\n        \"name\": \"Plano Ouro\",\n        \"trial_days\": 0,\n        \"date_created\": \"2015-03-03T16:56:32.000Z\",\n        \"payment_methods\": [\"boleto\", \"credit_card\"],\n        \"color\": null,\n        \"charges\": null,\n        \"installments\": 1\n    },\n    \"id\": 16892,\n    \"current_transaction\": {\n        \"object\": \"transaction\",\n        \"status\": \"waiting_payment\",\n        \"refuse_reason\": null,\n        \"status_reason\": \"acquirer\",\n        \"acquirer_response_code\": null,\n        \"acquirer_name\": \"development\",\n        \"authorization_code\": null,\n        \"soft_descriptor\": null,\n        \"tid\": null,\n        \"nsu\": null,\n        \"date_created\": \"2015-04-14T20:17:18.000Z\",\n        \"date_updated\": \"2015-04-14T20:17:19.000Z\",\n        \"amount\": 31000,\n        \"installments\": 1,\n        \"id\": 194402,\n        \"cost\": 0,\n        \"card_holder_name\": null,\n        \"card_last_digits\": null,\n        \"card_first_digits\": null,\n        \"card_brand\": null,\n        \"postback_url\": null,\n        \"payment_method\": \"boleto\",\n        \"antifraud_score\": null,\n        \"boleto_url\": \"https://pagar.me\",\n        \"boleto_barcode\": \"1234 5678\",\n        \"boleto_expiration_date\": \"2015-04-21T20:17:18.000Z\",\n        \"referer\": \"api_key\",\n        \"ip\": \"179.185.132.108\",\n        \"subscription_id\": 16892,\n        \"metadata\": {}\n    },\n    \"postback_url\": \"http://requestb.in/zyn5obzy\",\n    \"payment_method\": \"boleto\",\n    \"current_period_start\": null,\n    \"current_period_end\": null,\n    \"charges\": 0,\n    \"status\": \"unpaid\",\n    \"date_created\": \"2015-04-14T20:17:19.000Z\",\n    \"phone\": null,\n    \"address\": null,\n    \"customer\": {\n        \"object\": \"customer\",\n        \"document_number\": \"75948706036\",\n        \"document_type\": \"cpf\",\n        \"name\": null,\n        \"email\": \"api@test.com\",\n        \"born_at\": null,\n        \"gender\": null,\n        \"date_created\": \"2015-03-04T18:40:03.000Z\",\n        \"id\": 14437\n    },\n    \"card\": null,\n    \"metadata\": null\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "example": "subscription"
                    },
                    "plan": {
                      "type": "object",
                      "properties": {
                        "object": {
                          "type": "string",
                          "example": "plan"
                        },
                        "id": {
                          "type": "integer",
                          "example": 12783,
                          "default": 0
                        },
                        "amount": {
                          "type": "integer",
                          "example": 31000,
                          "default": 0
                        },
                        "days": {
                          "type": "integer",
                          "example": 30,
                          "default": 0
                        },
                        "name": {
                          "type": "string",
                          "example": "Plano Ouro"
                        },
                        "trial_days": {
                          "type": "integer",
                          "example": 0,
                          "default": 0
                        },
                        "date_created": {
                          "type": "string",
                          "example": "2015-03-03T16:56:32.000Z"
                        },
                        "payment_methods": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "example": "boleto"
                          }
                        },
                        "color": {},
                        "charges": {},
                        "installments": {
                          "type": "integer",
                          "example": 1,
                          "default": 0
                        }
                      }
                    },
                    "id": {
                      "type": "integer",
                      "example": 16892,
                      "default": 0
                    },
                    "current_transaction": {
                      "type": "object",
                      "properties": {
                        "object": {
                          "type": "string",
                          "example": "transaction"
                        },
                        "status": {
                          "type": "string",
                          "example": "waiting_payment"
                        },
                        "refuse_reason": {},
                        "status_reason": {
                          "type": "string",
                          "example": "acquirer"
                        },
                        "acquirer_response_code": {},
                        "acquirer_name": {
                          "type": "string",
                          "example": "development"
                        },
                        "authorization_code": {},
                        "soft_descriptor": {},
                        "tid": {},
                        "nsu": {},
                        "date_created": {
                          "type": "string",
                          "example": "2015-04-14T20:17:18.000Z"
                        },
                        "date_updated": {
                          "type": "string",
                          "example": "2015-04-14T20:17:19.000Z"
                        },
                        "amount": {
                          "type": "integer",
                          "example": 31000,
                          "default": 0
                        },
                        "installments": {
                          "type": "integer",
                          "example": 1,
                          "default": 0
                        },
                        "id": {
                          "type": "integer",
                          "example": 194402,
                          "default": 0
                        },
                        "cost": {
                          "type": "integer",
                          "example": 0,
                          "default": 0
                        },
                        "card_holder_name": {},
                        "card_last_digits": {},
                        "card_first_digits": {},
                        "card_brand": {},
                        "postback_url": {},
                        "payment_method": {
                          "type": "string",
                          "example": "boleto"
                        },
                        "antifraud_score": {},
                        "boleto_url": {
                          "type": "string",
                          "example": "https://pagar.me"
                        },
                        "boleto_barcode": {
                          "type": "string",
                          "example": "1234 5678"
                        },
                        "boleto_expiration_date": {
                          "type": "string",
                          "example": "2015-04-21T20:17:18.000Z"
                        },
                        "referer": {
                          "type": "string",
                          "example": "api_key"
                        },
                        "ip": {
                          "type": "string",
                          "example": "179.185.132.108"
                        },
                        "subscription_id": {
                          "type": "integer",
                          "example": 16892,
                          "default": 0
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {}
                        }
                      }
                    },
                    "postback_url": {
                      "type": "string",
                      "example": "http://requestb.in/zyn5obzy"
                    },
                    "payment_method": {
                      "type": "string",
                      "example": "boleto"
                    },
                    "current_period_start": {},
                    "current_period_end": {},
                    "charges": {
                      "type": "integer",
                      "example": 0,
                      "default": 0
                    },
                    "status": {
                      "type": "string",
                      "example": "unpaid"
                    },
                    "date_created": {
                      "type": "string",
                      "example": "2015-04-14T20:17:19.000Z"
                    },
                    "phone": {},
                    "address": {},
                    "customer": {
                      "type": "object",
                      "properties": {
                        "object": {
                          "type": "string",
                          "example": "customer"
                        },
                        "document_number": {
                          "type": "string",
                          "example": "75948706036"
                        },
                        "document_type": {
                          "type": "string",
                          "example": "cpf"
                        },
                        "name": {},
                        "email": {
                          "type": "string",
                          "example": "api@test.com"
                        },
                        "born_at": {},
                        "gender": {},
                        "date_created": {
                          "type": "string",
                          "example": "2015-03-04T18:40:03.000Z"
                        },
                        "id": {
                          "type": "integer",
                          "example": 14437,
                          "default": 0
                        }
                      }
                    },
                    "card": {},
                    "metadata": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "curl -X POST https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{\n    \"api_key\": \"SUA_API_KEY\", \n    \"card_id\": \"card_ci234fx8rr649rt16rtb11132\", \n    \"customer\": {\n        \"address\": {\n            \"neighborhood\": \"Cidade Monções\", \n            \"street\": \"Rua Dr.Geraldo Campos Moreira\", \n            \"street_number\": \"240\", \n            \"zipcode\": \"04571020\"\n        }, \n        \"document_number\": \"92545278157\", \n        \"email\": \"jappleseed@apple.com\", \n        \"name\": \"John Appleseed\", \n        \"phone\": {\n            \"ddd\": \"11\", \n            \"number\": \"15510101\"\n        }\n    },\n    \"payment_method\": \"credit_card\", \n    \"plan_id\": \"12783\", \n    \"postback_url\": \"http://requestb.in/zyn5obzy\"\n}'"
            },
            {
              "language": "ruby",
              "code": "require 'pagarme'\n\nPagarMe.api_key = \"SUA_API_KEY\"\n\nplan = PagarMe::Plan.find_by_id(\"12783\")\n\nsubscription = PagarMe::Subscription.new({\n  :payment_method => 'credit_card',\n    :card_number => \"4901720080344448\",\n    :card_holder_name => \"Jose da Silva\",\n    :card_expiration_month => \"10\",\n    :card_expiration_year => \"15\",\n    :card_cvv => \"314\",\n    :postback_url => \"http://test.com/postback\",\n    :customer => {\n        :name => \"John Appleseed\",\n        :document_number => \"92545278157\",\n        :email => \"jappleseed@apple.com\",\n        :address => {\n            :street => \"Rua Dr. Geraldo Campos Moreira\",\n            :neighborhood => \"Cidade Monções\",\n            :zipcode => \"04571020\",\n            :street_number => \"240\"\n        },\n        :phone => {\n            :ddd => \"11\"\n            :number => \"15510101\"\n        }\n    }\n})\nsubscription.plan = plan\n\nsubscription.create"
            },
            {
              "language": "php",
              "code": "<?php\nrequire(\"vendor/autoload.php\");\n$pagarme = new PagarMe\\Client('SUA_CHAVE_DE_API');\n\n$subscription = $pagarme->subscriptions()->create([\n  'plan_id' => 123456,\n  'payment_method' => 'credit_card',\n  'card_number' => '4111111111111111',\n  'card_holder_name' => 'UNIX TIME',\n  'card_expiration_date' => '0722',\n  'card_cvv' => '123',\n  'postback_url' => 'http://postbacj.url',\n  'customer' => [\n    'email' => 'time@unix.com',\n    'name' => 'Unix Time',\n    'document_number' => '75948706036',\n    'address' => [\n      'street' => 'Rua de Teste',\n      'street_number' => '100',\n      'complementary' => 'Apto 666',\n      'neighborhood' => 'Bairro de Teste',\n      'zipcode' => '11111111'\n    ],\n    'phone' => [\n      'ddd' => '01',\n      'number' => '923456780'\n    ],\n    'sex' => 'other',\n    'born_at' => '1970-01-01',\n  ],\n  'metadata' => [\n    'foo' => 'bar'\n  ]\n]);"
            },
            {
              "language": "csharp",
              "code": "PagarMeService.DefaultApiKey = \"SUA_API_KEY\";\n\nSubscription subscription = new Subscription\n{\n\t\tPaymentMethod = PaymentMethod.CreditCard,\n  \tCardNumber = \"4901720080344448\",\n\t\tCardHolderName = \"Jose da Silva\",\n\t\tCardExpirationDate = \"1215\",\n\t\tCardCvv = \"123\"\n};\nsubscription.Plan = PagarMeService.GetDefaultService().Plans.Find(12783);\nCustomer customer = new Customer\n{\n\t\tName = \"John Appleseed\",\n    DocumentNumber = \"92545278157\",\n    Email = \"jappleseed@apple.com\",\n    Address = new Address {\n        Street = \"Rua Dr. Geraldo Campos Moreira\",\n        Neighborhood = \"Cidade Monções\",\n        Zipcode = \"04571020\",\n        StreetNumber = \"240\"\n    },\n    Phone = new Phone {\n        Ddd = \"11\",\n        Number = \"15510101\"\n    }\n};\n\nsubscription.Customer = customer;\n\nsubscription.Save();"
            },
            {
              "language": "java",
              "code": "import me.pagar.model.Customer;\nimport me.pagar.model.Address;\nimport me.pagar.model.Card;\nimport me.pagar.model.Phone;\nimport me.pagar.model.PagarMe;\nimport me.pagar.model.PagarMeException;\nimport me.pagar.model.Subscription;\n\nPagarMe.init(\"SUA_API_KEY\");\n\nPhone phone = new Phone();\nphone.setDdd(\"11\");\nphone.setDdi(\"55\");\nphone.setNumber(\"99999999\");\n\nString street = \"Avenida Brigadeiro Faria Lima\";\nString streetNumber = \"1811\";\nString neighborhood = \"Jardim Paulistano\";\nString zipcode = \"01451001\";\nAddress address = new Address(street, streetNumber, neighborhood, zipcode);\n\nString name = \"Aardvark Silva\";\nString email = \"aardvark.silva@pagar.me\";\nString documentNumber = \"18152564000105\";\nCustomer customer = new Customer(name, email);\ncustomer.setAddress(address);\ncustomer.setPhone(phone);\ncustomer.setDocumentNumber(documentNumber);\n\nCard card = new Card();\ncard.setNumber(\"4901720080344448\");\ncard.setHolderName(\"Jose da Silva\");\ncard.setExpiresAt(\"1219\");\ncard.setCvv(\"123\");\ncard.save();\n\nSubscription subscription = new Subscription();\nsubscription.setCreditCardSubscriptionWithCardId(\"122539\", card.getId(), customer);\nsubscription.save();"
            },
            {
              "language": "javascript",
              "code": "const pagarme = require('pagarme')\n  \npagarme.client.connect({ api_key: 'SUA_API_KEY' })\n  .then(client => client.subscriptions.create({\n    plan_id: 12783,\n    card_id: 'CARD_ID',\n    payment_method:'credit_card',\n    customer: {\n      email: 'daenerys.targaryen@gmail.com',\n      name: 'Daenerys Targaryen',\n      document_number: '18152564000105',\n      address: {\n        zipcode: '04571020',\n        neighborhood: 'Dragon Village',\n        street: 'Rua Drogon',\n        street_number: '240'\n    },\n      phone: {\n        number: '987654321',\n        ddd: '11'\n        }\n    }\n    }))\n  .then(subscription => console.log(subscription))",
              "name": "JS"
            },
            {
              "language": "python",
              "code": "import pagarme\n\npagarme.authentication_key('SUA_API_KEY')\n\nsubscription = pagarme.subscription.create({\n    \"card_id\": \"card_cj6qvosem04w3nu6dm20nu8od\",\n    \"customer\":{\n        \"email\":\"jorah.mormont@gameofthrones.com\",\n        \"name\":\"Sir Jorah Mormont\",\n        \"document_number\":\"18152564000105\",\n        \"address\":{\n            \"zipcode\":\"04571020\",\n            \"neighborhood\":\"Cidade Moncoes\",\n            \"street\":\"R. Dr. Geraldo Campos Moreira\",\n            \"street_number\":\"240\"\n        },\n        \"phone\": {\n            \"number\":\"987654321\",\n            \"ddd\":\"11\"\n        }\n    },\n    \"payment_method\": \"credit_card\",\n    \"plan_id\": \"201836\",\n    \"postback_url\": \"http://requestb.in/zyn5obzy\"\n})\n\nprint (subscription)"
            }
          ],
          "samples-languages": [
            "curl",
            "ruby",
            "php",
            "csharp",
            "java",
            "javascript",
            "python"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```