> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar uma assinatura

O Localpayment permite que os comerciantes configurem assinaturas de pagamento recorrente com cartões de crédito e débito, oferecendo suporte tanto a planos fixos quanto a cenários de cobrança personalizados em vários países. Este guia descreve o processo de criação de uma assinatura por meio da API do Localpayment, detalhando os parâmetros obrigatórios, o tratamento das respostas e a interpretação dos códigos de status.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Passo 1: Crie uma assinatura

Para criar uma nova assinatura, você precisará enviar uma solicitação `POST` para o endpoint [Criar uma assinatura](https://docs.localpayment.com/pt-br/reference/create-a-subscription.md).

### Parâmetros-chave da solicitação

A solicitação exige vários parâmetros-chave, dependendo de você estar criando uma assinatura de plano fixo ou uma assinatura personalizada:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `externalId` | Sua referência exclusiva para a assinatura | ✅ |
| `merchant` | Detalhes do comerciante/empresa | ✅ |
| `country` | Código do país em que a assinatura será processada | ✅ |
| `currency` | Código da moeda da assinatura | ✅ |
| `paymentMethod` | Configuração do método de pagamento | ✅ |
| `planId` | ID de um plano de assinatura predefinido (para planos fixos) | ❌ |
| `autoRecurring` | Frequência de faturamento | Condicional |
| `amount` | Valor da assinatura (obrigatório se não houver planId) | Condicional |

### Tipos de assinatura

* **Assinatura de plano fixo**: Use quando você tiver planos de assinatura predefinidos criados por meio do endpoint [Criar plano de assinatura](https://docs.localpayment.com/pt-br/docs/create-a-subscription-plan.md).
* **Assinatura personalizada**: Use para cenários de faturamento variável em que cada pagamento pode ter valor ou prazo diferente.

### Códigos de métodos de pagamento

Em todos os países, `paymentMethod.code` identifica o país, a bandeira do cartão e o produto (crédito ou débito); portanto, envie o código que corresponde ao cartão e ao `country` da assinatura. No Peru, onde os cartões são aceitos em duas moedas, o código também deve corresponder à `currency`: por exemplo, um cartão de crédito Visa usa `6000` com PEN e `6004` com USD. Consulte [Códigos de métodos de pagamento com cartão](https://docs.localpayment.com/pt-br/docs/card-payment-methods.md) para ver os códigos de todos os países.

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/subscriptions \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1900",
        "flow": "DIRECT"
    },
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "country": "COL",
    "amount": 10000.00,
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Test subscription",
    "merchant": {
        "type": "COMPANY",
        "name": "My Company SA DE CV",
        "document": {
            "type": "CC",
            "id": "717321230"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "id": "1073695321",
            "type": "CC"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "name": "John Doe",
        "number": "4242424242424242",
        "cvv": "123",
        "expirationMonth": "11",
        "expirationYear": "2029",
        "installments": 1
    },
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    }
}'
'

```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/create-a-subscription.md) na solicitação.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma resposta bem-sucedida inclui informações detalhadas sobre a assinatura e identificadores:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "type": "SOFTWARE",
    "externalId": "1fe38b94-7e11-44c1-9a88-b4aa9fbe5b4a",
    "internalId": "990017f0-7928-4c20-a149-0c1673035f2c",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "105",
        "description": "WAITINGAUTH",
        "detail": "The subscription is active"
    },
    "date": {
        "creationDate": "2025-11-13T05:05:58.8502173",
        "nextPaymentDate": "2025-11-14T05:05:58.8502036"
    },
    "payments": [
        {
            "externalId": "36e1ce13-8a20-4565-b5f5-e275e1df0010",
            "internalId": "adccc452-4a8c-414c-b777-152f4b0ed2da",
            "status": {
                "code": "100",
                "description": "INPROGRESS",
                "detail": "The payin is pending the confirmation"
            },
            "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly93ZWItY2hlY2tvdXQuc3RhZ2UubG9jYWxwYXltZW50LmNvbS92ZXJpZmljYXRpb24vMDA5Nz9pbnRlcm5hbElkPTQzYzVjZDE1LTg0N2UtNDRhNC05MTU1LTcyYmVmNjZiZDAzMw"
        }
    ],
    "errors": []
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador exclusivo da assinatura do Localpayment. | Rastreamento e gestão de assinaturas. |
| `status.code` | Código de status atual da assinatura. | Monitoramento de status e automação. |
| `date.creationDate` | Data em que a assinatura foi criada | Rastreamento de auditoria e geração de relatórios. |
| `date.nextPaymentDate` | Quando o próximo pagamento será processado. | Gestão do ciclo de faturamento. |
| `payments` | Array de objetos de pagamento da assinatura. | Histórico e rastreamento de pagamentos. |

### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "b27ebf99-e92d-4aca-ba16-f9f8412372cd",
    "internalId": "f95883ce-f08a-485f-9734-0182ec3af70d",
    "country": "COL",
    "currency": "COP",
    "accountNumber": "{{accountNumber}}",
    "type": "SOFTWARE",
    "autoRecurring": {
        "type": "day"
    },
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "date": {
        "creationDate": "2025-11-13T05:07:42.7612531"
    },
    "payments": [
        {
            "externalId": "672022a9-b595-4d78-88d0-6ac8d6738082",
            "internalId": "8279db2d-2502-4c1f-8d3b-b668c8b5ff53",
            "status": {
                "code": "300",
                "description": "REJECTED"
            }
        }
    ],
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [payer.email] + must not be null"
        }
    ]
}
```

***

## Etapa 3: Rastrear o status da transação

Após criar uma assinatura, monitore o ciclo de vida dela por meio destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

A API do Localpayment fornece vários códigos de status para indicar o estado da assinatura.

| Código | Status | Descrição |
| :- | :- | :- |
| `105` | `ACTIVE` | A assinatura está ativa e em andamento. |
| `300` | `REJECTED` | A criação da assinatura ou o pagamento foi rejeitado. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Criação de assinatura bem-sucedida**: fluxo padrão de assinatura com cartão válido.
2. **Assinatura de plano fixo**: assinatura com plano predefinido.
3. **Assinatura personalizada**: assinatura com parâmetros de cobrança personalizados.
4. **Erros de validação**: cartão inválido, campos obrigatórios ausentes
5. **Atualizações de status**: gerenciamento de webhooks e consulta de status

***

## Próximos passos

Após a criação de uma assinatura, você poderá precisar realizar ações adicionais, como:

> [card] [Atualizar assinatura](https://docs.localpayment.com/pt-br/docs/update-a-subscription.md)
>
> Modifique os detalhes de uma assinatura existente, incluindo valor da cobrança, frequência ou
> informações do cliente.

> [card] [Cancelar assinatura](https://docs.localpayment.com/pt-br/docs/cancel-a-subscription.md)
>
> Encerre assinaturas ativas preservando o histórico de transações e os
> registros de faturamento.

> [card] [Tratar webhooks de assinatura](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure webhooks para receber notificações em tempo real sobre eventos de assinatura
> e mudanças no status dos pagamentos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.