Skip to main content
POST
/
v1
/
subscriptions
Create a subscription (Checkout)
curl --request POST \
  --url https://api-global.fastpaybrasil.com/v1/subscriptions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "billingDay": 15,
  "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "validateCard": true,
  "skipTrial": false,
  "metadata": {
    "referralCode": "PROMO2024"
  }
}
'
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "active",
  "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "currentPeriodStart": "2024-01-15T10:30:00.000Z",
  "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
  "billingDay": 15,
  "cardActivation": {
    "required": true,
    "message": "Verifique o valor da transacao de teste na fatura do cartao e use o endpoint /cards/:cardTokenId/activate"
  },
  "firstCharge": {
    "success": true,
    "nsuOperacao": "123456789",
    "codigoAutorizacao": "ABC123",
    "message": "Transaction approved"
  }
}

Authorizations

​
Authorization
string
header
required

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.

Body

application/json
​
subscriptionPlanId
string
required

Subscription plan ID

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
billingDay
integer

Billing day of the month (1-28)

Required range: 1 <= x <= 28
Example:

15

​
customerId
string

Existing customer ID. Use this OR customer object, not both.

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
customer
object

Customer data. Use this OR customerId, not both. If provided, will search by email or create a new customer.

​
cardTokenId
string

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
object

Card data for new card registration. Use this OR cardTokenId, not both.

​
validateCard
boolean
default:true

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
boolean

When true, skips the trial period (if the plan has one) and starts billing immediately. Default is false.

Example:

false

​
metadata
object

Additional metadata

Example:
{ "referralCode": "PROMO2024" }

Response

Subscription successfully created

​
id
string

Unique subscription identifier

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
status
enum<string>

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)
Available options:
active,
pending_activation,
pending_card_activation
Example:

"active"

​
cardTokenId
string

Token ID of the registered card (used for card activation)

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
currentPeriodStart
string<date-time>

Current billing period start

Example:

"2024-01-15T10:30:00.000Z"

​
currentPeriodEnd
string<date-time>

Current billing period end

Example:

"2024-02-15T10:30:00.000Z"

​
billingDay
integer

Billing day of the month

Example:

15

​
cardActivation
object

Card activation info (only present when validateCard=true)

​
firstCharge
object

First charge result (only present when validateCard=false)