Create Subscription

Create a subscription transaction by sending all the details required to create a transaction. The details such as name, amount, currency, payment_type, token, and schedule are sent in the request. Successful request returns id status:active, and other subscription details.


📘

Retry mechanism when deduction fails

If for some reason deduction fails, Midtrans will perform retry 3 times for every one hour before marking subscription as inactive.

Example :
There's a payment that's failed to be processed at 11 Oct 2022 15.48 GMT+7. Then, retry attempts will possibly occur at:

  • 11 Oct 2022 16.48 GMT+7
  • 11 Oct 2022 17.48 GMT+7
  • 11 Oct 2022 18.48 GMT+7



Create Subscription Method

HTTP MethodEndpointDescription
POSTBASE_URL/v1/subscriptionsCreate subscription



Create Subscription Request

{
    "name": "MONTHLY_2019",
    "amount": "14000",
    "currency": "IDR",
    "payment_type": "credit_card",
    "token": "48111111sHfSakAvHvFQFEjTivUV1114",
    "schedule": {
      "interval": 1,
      "interval_unit": "month",
      "max_interval": 12,
      "start_time": "2020-07-22 07:25:01 +0700"
    },
    "metadata": {
      "description": "Recurring payment for A"
    },
    "customer_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "+62812345678"
    },
    "gopay": {
      "account_id": "0dd2cd90-a9a9-4a09-b393-21162dfb713b"
    }
}
JSON AttributeDescriptionTypeRequired
nameName of the subscription. It is used to generate order ID for the transaction. Generated order ID will contain subscription name and 10 digits of unique number.
Note: Allowed symbols are dash(-), underscore(_), tilde (~), and dot (.).
String(40)Required
amountThe amount to be charged to the customer.
Note: Do not use decimal.
StringRequired
currencyISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.
StringRequired
payment_typeThe payment method used by the customer. Note: Currently only credit_card and gopay are supported.StringRequired
tokenThe saved_token_id or GoPay token retrieved from Get Account / received in the Charge response.StringRequired
scheduleDetails of the subscription schedule.ObjectRequired
metadataMetadata of subscription specified by you.
Note: Limit the size to less than 1KB.
ObjectOptional
customer_detailsDetails of the customer.ObjectOptional
gopayGoPay subscription information, required if payment type is gopay.ObjectOptional



Create Subscription Sample Response

{
  "id": "d98a63b8-97e4-4059-825f-0f62340407e9",
  "name": "MONTHLY_2019",
  "amount": "14000",
  "currency": "IDR",
  "created_at": "2019-05-29T09:11:01.810452",
  "schedule": {
    "interval": 1,
    "interval_unit": "month",
    "start_time": "2019-05-29T09:11:01.803677",
    "previous_execution_at": "2019-05-29T09:11:01.803677",
    "next_execution_at": "2019-06-29T09:11:01.803677"
  },
  "status": "active",
  "token": "48111111sHfSakAvHvFQFEjTivUV1114",
  "payment_type": "credit_card",
  "metadata": {
    "description": "Recurring payment for A"
  },
  "customer_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+62812345678"
  }
}
{
  "status_message": "Invalid parameter.",
  "validation_messages": [
    "subscription.amount is required"
  ]
}
{
  "status_message": "Sorry, Our system is recovering from unexpected issues. Please retry."
}
JSON AttributeDescriptionType
idSubscription ID given by Midtrans.String
nameSubscription name specified by you.String
amountAmount specified by you for recurring charge.String
currencyISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.
String
created_atSubscription schedule creation timestamp in ISO 8601 format. Time Zone: GMT + 7.String
scheduleDetails of the subscription schedule.Object
statusCurrent subscription status.
Possible values are active, inactive.
String
tokenPayment token used for subscription.String
payment_typeThe payment method used by the customer. Value: credit_card.
Note: Currently only credit_card and gopay are supported.
String
metadataMetadata of subscription specified by you.
Note: Limit the size to less than 1KB.
Object
customer_detailsDetails of the customer.Object
status_messageDescription of the error.String
validation_messageDetailed description of the error.Array(String)
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!