> ## Documentation Index > Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription (Checkout) > Creates a new subscription linked to a plan. **Payment Method Options:** - Use `cardTokenId` to reference an existing, active card - Use `paymentMethod` to register a new card with this subscription **Card Validation Flow (when using paymentMethod):** - If `validateCard: true` (default): A small test charge (e.g., R$ 1.50) is made to the card. The customer must check their card statement and call `POST /v1/cards/{cardTokenId}/activate` with the exact value. After activation, pending subscriptions using that card will have their first charge processed automatically. - If `validateCard: false`: The card is used immediately and the first charge is processed. **Using an existing card (cardTokenId):** - The card must be active (not pending activation) - The first charge is processed immediately ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/subscriptions openapi: 3.0.0 info: title: FastPay API version: 1.0.0 description: >- API for creating and managing payment charges. ## Authentication This API uses **Basic Authentication** for direct API access, such as creating charges. Use your API key as the username and an empty string as password. The header should be formatted as: `Authorization: Basic {base64(apiKey:)}`. For example: ``` Authorization: Basic YWxleG91dG9uOiIi ``` ## Webhooks FastPay sends webhooks to notify your application about charge status changes in real-time. Webhooks are sent via HTTP POST requests to your configured webhook endpoints. ### Webhook Events The following webhook events are available for charges: - `charge.created` - Sent when a new charge is created - `charge.pending` - Sent when a charge is pending payment - `charge.paid` - Sent when a charge is successfully paid - `charge.updated` - Sent when a charge is updated ### Webhook Payload Structure All webhook payloads follow this structure: ```json { "id": "webhook_event_id", "event": "charge.paid", "data": { // Complete charge object } } ``` ### Webhook Delivery - Webhooks are sent via HTTP POST requests - Content-Type: `application/json` - Retry logic is implemented for failed deliveries - Webhook events are stored in the database for audit purposes - Delivery logs are maintained for debugging and monitoring ### Webhook Security - Webhooks are sent to pre-configured endpoints - Endpoints can be enabled/disabled per merchant - Event filtering is supported (only receive specific events) - Failed deliveries are retried with exponential backoff servers: - url: https://api-global.fastpaybrasil.com description: Produção e Sandbox (diferenciados pela API key) security: [] paths: /v1/subscriptions: post: tags: - Subscriptions summary: Create a subscription (Checkout) description: >- Creates a new subscription linked to a plan. **Payment Method Options:** - Use `cardTokenId` to reference an existing, active card - Use `paymentMethod` to register a new card with this subscription **Card Validation Flow (when using paymentMethod):** - If `validateCard: true` (default): A small test charge (e.g., R$ 1.50) is made to the card. The customer must check their card statement and call `POST /v1/cards/{cardTokenId}/activate` with the exact value. After activation, pending subscriptions using that card will have their first charge processed automatically. - If `validateCard: false`: The card is used immediately and the first charge is processed. **Using an existing card (cardTokenId):** - The card must be active (not pending activation) - The first charge is processed immediately requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewSubscription' responses: '201': description: Subscription successfully created content: application/json: schema: $ref: '#/components/schemas/CreatedSubscription' '400': description: Invalid data or creation failure content: application/json: schema: type: object properties: statusCode: type: integer example: 400 message: type: string example: Failed to create subscription '401': description: Unauthorized - invalid credentials content: application/json: schema: type: object properties: statusCode: type: integer example: 401 message: type: string example: Unauthorized '404': description: Subscription plan not found or inactive content: application/json: schema: type: object properties: statusCode: type: integer example: 404 message: type: string example: Subscription plan not found or inactive security: - basic: [] components: schemas: NewSubscription: type: object required: - subscriptionPlanId properties: subscriptionPlanId: type: string description: Subscription plan ID example: 2RhQg9M7ZCg3X3nMb9W1kX8Q billingDay: type: integer minimum: 1 maximum: 28 description: Billing day of the month (1-28) example: 15 customerId: type: string description: Existing customer ID. Use this OR customer object, not both. example: 2RhQg9M7ZCg3X3nMb9W1kX8Q customer: description: >- Customer data. Use this OR customerId, not both. If provided, will search by email or create a new customer. type: object required: - name - email properties: name: type: string description: Customer name example: John Doe email: type: string format: email description: Customer email example: john@example.com document: type: object properties: type: type: string description: Document type (cpf, cnpj, passport) example: cpf id: type: string description: Document number example: '12345678900' phoneNumber: type: string description: Customer phone number example: '+5511999999999' cardTokenId: type: string description: >- Existing card token ID. Use this to create a subscription with a previously registered card. The card must be active (not pending activation). Use this OR paymentMethod, not both. example: 2RhQg9M7ZCg3X3nMb9W1kX8Q paymentMethod: type: object description: |- Card data for new card registration. Use this OR cardTokenId, not both. required: - number - holderName - expirationMonth - expirationYear - cvv properties: number: type: string description: Card number example: '4111111111111111' holderName: type: string description: Name on card example: JOHN DOE expirationMonth: type: string minLength: 2 maxLength: 2 description: Expiration month (01-12) example: '12' expirationYear: type: string minLength: 4 maxLength: 4 description: Expiration year (YYYY) example: '2028' cvv: type: string minLength: 3 description: Security code example: '123' validateCard: type: boolean default: true description: >- Whether to validate the card before activating the subscription. When `true` (default): - A small test transaction (up to R$ 2.00) is made on the card - The subscription is created with status `pending_card_activation` - The customer must verify the transaction amount on their card statement - Use `/cards/{cardTokenId}/activate` endpoint to activate the card - After successful activation, the test amount is refunded and the first subscription charge is processed When `false`: - Card is not validated, increasing risk of declined transactions - First charge is processed immediately - Subscription becomes `active` if charge succeeds example: true skipTrial: type: boolean description: |- When `true`, skips the trial period (if the plan has one) and starts billing immediately. Default is `false`. example: false metadata: type: object description: Additional metadata example: referralCode: PROMO2024 CreatedSubscription: type: object properties: id: type: string description: Unique subscription identifier example: 2RhQg9M7ZCg3X3nMb9W1kX8Q status: type: string enum: - active - pending_activation - pending_card_activation description: >- Subscription status: - `active`: Subscription is active and billing normally - `pending_activation`: First charge failed, awaiting retry - `pending_card_activation`: Card requires validation (when validateCard=true) example: active cardTokenId: type: string description: Token ID of the registered card (used for card activation) example: 2RhQg9M7ZCg3X3nMb9W1kX8Q currentPeriodStart: type: string format: date-time description: Current billing period start example: '2024-01-15T10:30:00.000Z' currentPeriodEnd: type: string format: date-time description: Current billing period end example: '2024-02-15T10:30:00.000Z' billingDay: type: integer description: Billing day of the month example: 15 cardActivation: type: object nullable: true description: Card activation info (only present when validateCard=true) properties: required: type: boolean description: Whether card activation is required example: true message: type: string description: Instructions for card activation example: >- Verifique o valor da transacao de teste na fatura do cartao e use o endpoint /cards/:cardTokenId/activate firstCharge: type: object nullable: true description: First charge result (only present when validateCard=false) properties: success: type: boolean description: Whether the charge was successful example: true nsuOperacao: type: string description: PSP operation identifier example: '123456789' codigoAutorizacao: type: string description: Authorization code example: ABC123 message: type: string description: Charge result message example: Transaction approved securitySchemes: basic: type: http scheme: basic description: |- HTTP Basic authentication. Use your secret key as the username and an empty string as password. The API key should be base64 encoded in the format 'username:' when sending the Authorization header. ````