Create and Confirm Subscription

Creates and confirms a subscription in a single request. Use this endpoint when you have all payment details available upfront and want to skip the separate confirm step.

POST /subscriptions

Headers

Header	Type	Required	Description
`api-key`	string	Yes	Your secret API key.
`X-Profile-Id`	string	Yes	Profile ID for authentication.

Body Parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	The unique identifier for the customer.
`item_price_id`	string	Yes	Identifier for the item price to subscribe to (e.g. `standard-plan-USD-Monthly`).
`payment_details`	object	Yes	Payment method and configuration. See Payment Details.
`merchant_reference_id`	string	No	Your own unique identifier for this subscription.
`plan_id`	string	No	Identifier for the subscription plan.
`coupon_code`	string	No	Coupon code to apply to the subscription.
`billing`	object	No	Billing address. See Address.
`shipping`	object	No	Shipping address. See Address.

Payment Details

Parameter	Type	Required	Description
`payment_method`	string	No	The payment method type: `card`, `wallet`, `bank_redirect`, `bank_transfer`, `bank_debit`, `pay_later`, `crypto`, `upi`, `voucher`, `gift_card`, `open_banking`, `mobile_payment`, `network_token`.
`payment_method_data`	object	No	Payment method data. Structure depends on `payment_method`. See Payment Method Data.
`payment_method_id`	string	No	ID of a previously saved payment method (e.g. `pm_01926c58bc6e77c09e809964e72af8c8`).
`payment_method_type`	string	No	Sub-type of the payment method (e.g. `credit`, `debit`, `google_pay`, `apple_pay`).
`authentication_type`	string	No	`three_ds` or `no_three_ds`. Defaults to connector behaviour if omitted.
`capture_method`	string	No	`automatic`, `manual`, `manual_multiple`, `scheduled`, or `sequential_automatic`. Defaults to `automatic`.
`setup_future_usage`	string	No	`off_session` (charge later without customer present) or `on_session`. Defaults to `on_session`.
`payment_type`	string	No	`normal`, `new_mandate`, `setup_mandate`, or `recurring_mandate`. Use `setup_mandate` for zero-auth flows.
`return_url`	string	No	URL to redirect the user to after payment completion.
`customer_acceptance`	object	No	Mandate acceptance details. See Customer Acceptance.

Payment Method Data

Pass the appropriate object key matching your payment_method value.

Card

Parameter	Type	Required	Description
`card.card_number`	string	Yes	The full card number (e.g. `4242424242424242`).
`card.card_exp_month`	string	Yes	Card expiry month (e.g. `03`).
`card.card_exp_year`	string	Yes	Card expiry year (e.g. `2030`).
`card.card_holder_name`	string	Yes	Name on the card.
`card.card_cvc`	string	Yes	Card verification code.
`card.card_network`	string	No	Card network: `Visa`, `Mastercard`, `AmericanExpress`, `JCB`, etc.
`card.nick_name`	string	No	Friendly name for the card.

Customer Acceptance

Parameter	Type	Required	Description
`acceptance_type`	string	Yes	How the mandate was accepted: `online` or `offline`.
`accepted_at`	string	No	ISO 8601 timestamp of when acceptance was given (e.g. `2024-01-01T10:00:00Z`).
`online.ip_address`	string	Yes (if online)	Customer's IP address at time of acceptance.
`online.user_agent`	string	Yes (if online)	Customer's browser user agent string.

Address

Parameter	Type	Required	Description
`address.line1`	string	No	First line of the street address.
`address.line2`	string	No	Second line (apartment, suite, unit, etc.).
`address.line3`	string	No	Third line, if applicable.
`address.city`	string	No	City, district, suburb, town, or village.
`address.state`	string	No	State or region.
`address.zip`	string	No	Postal or ZIP code.
`address.country`	string	No	Two-letter ISO 3166-1 country code (e.g. `US`, `GB`).
`address.first_name`	string	No	First name on the address.
`address.last_name`	string	No	Last name on the address.
`phone.number`	string	No	Contact phone number.
`phone.country_code`	string	No	Phone country code (e.g. `+1`).
`email`	string	No	Email address.

Request Example

curl -X POST 'https://api.sandbox.paychtec.com/subscriptions' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -H "X-Profile-Id: prof_12345" \
  -d '{
"customer_id": "cust_123456789",
"item_price_id": "standard-plan-USD-Monthly",
"merchant_reference_id": "mer_ref_123456789",
"payment_details": {
  "payment_method": "card",
  "payment_method_type": "credit",
  "payment_method_data": {
    "card": {
      "card_number": "4000000000000002",
      "card_exp_month": "03",
      "card_exp_year": "2030",
      "card_holder_name": "John Doe",
      "card_cvc": "737"
    }
  },
  "authentication_type": "no_three_ds",
  "capture_method": "automatic",
  "setup_future_usage": "off_session",
  "payment_type": "setup_mandate",
  "return_url": "https://yourapp.com/return",
  "customer_acceptance": {
    "acceptance_type": "online",
    "accepted_at": "2024-01-01T10:00:00Z",
    "online": {
      "ip_address": "127.0.0.1",
      "user_agent": "Mozilla/5.0"
    }
  }
},
"billing": {
  "address": {
    "line1": "1467",
    "line2": "Harrison Street",
    "city": "San Francisco",
    "state": "California",
    "zip": "94122",
    "country": "US",
    "first_name": "John",
    "last_name": "Doe"
  },
  "phone": {
    "number": "123456789",
    "country_code": "+1"
  }
}
}'

curl -X POST 'https://api.sandbox.paychtec.com/subscriptions' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -H "X-Profile-Id: prof_12345" \  -d '{"customer_id": "cust_123456789","item_price_id": "standard-plan-USD-Monthly","merchant_reference_id": "mer_ref_123456789","payment_details": {  "payment_method": "card",  "payment_method_type": "credit",  "payment_method_data": {    "card": {      "card_number": "4000000000000002",      "card_exp_month": "03",      "card_exp_year": "2030",      "card_holder_name": "John Doe",      "card_cvc": "737"    }  },  "authentication_type": "no_three_ds",  "capture_method": "automatic",  "setup_future_usage": "off_session",  "payment_type": "setup_mandate",  "return_url": "https://yourapp.com/return",  "customer_acceptance": {    "acceptance_type": "online",    "accepted_at": "2024-01-01T10:00:00Z",    "online": {      "ip_address": "127.0.0.1",      "user_agent": "Mozilla/5.0"    }  }},"billing": {  "address": {    "line1": "1467",    "line2": "Harrison Street",    "city": "San Francisco",    "state": "California",    "zip": "94122",    "country": "US",    "first_name": "John",    "last_name": "Doe"  },  "phone": {    "number": "123456789",    "country_code": "+1"  }}}'

Response

{
  "id": "sub_abc123",
  "status": "active",
  "profile_id": "prof_12345",
  "merchant_id": "mer_abc123",
  "customer_id": "cust_123456789",
  "item_price_id": "standard-plan-USD-Monthly",
  "merchant_reference_id": "mer_ref_123456789",
  "payment": {
    "payment_id": "pay_xyz789",
    "status": "succeeded",
    "amount": 2900,
    "currency": "USD",
    "payment_method_type": "credit"
  },
  "invoice": {
    "id": "inv_abc123",
    "subscription_id": "sub_abc123",
    "amount": 2900,
    "currency": "USD",
    "status": "invoice_paid"
  }
}

Subscription Statuses

Status	Description
`active`	Subscription created, confirmed, and billing normally.
`pending`	Awaiting final activation.
`trial`	In a free trial period.
`unpaid`	Payment was not collected successfully.
`failed`	Subscription setup failed.
`cancelled`	Subscription has been cancelled.
`in_active`	Subscription is inactive.
`onetime`	One-time payment subscription.

Error Responses

Status Code	Description
`400`	Invalid subscription data — check required fields and payment details.
`404`	Customer or plan not found — verify `customer_id` and `item_price_id`.

On this page