post https://api.sandbox.midtrans.com/v1/subscriptions
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 Method | Endpoint | Description |
|---|---|---|
| POST | BASE_URL/v1/subscriptions | Create 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 Attribute | Description | Type | Required |
|---|---|---|---|
| name | Name 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 |
| amount | The amount to be charged to the customer. Note: Do not use decimal. | String | Required |
| currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.Note: Currently only IDR is supported. | String | Required |
| payment_type | The payment method used by the customer. Note: Currently only credit_card and gopay are supported. | String | Required |
| token | The saved_token_id or GoPay token retrieved from Get Account / received in the Charge response. | String | Required |
| schedule | Details of the subscription schedule. | Object | Required |
| metadata | Metadata of subscription specified by you. Note: Limit the size to less than 1KB. | Object | Optional |
| customer_details | Details of the customer. | Object | Optional |
| gopay | GoPay subscription information, required if payment type is gopay. | Object | Optional |
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 Attribute | Description | Type |
|---|---|---|
| id | Subscription ID given by Midtrans. | String |
| name | Subscription name specified by you. | String |
| amount | Amount specified by you for recurring charge. | String |
| currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.Note: Currently only IDR is supported. | String |
| created_at | Subscription schedule creation timestamp in ISO 8601 format. Time Zone: GMT + 7. | String |
| schedule | Details of the subscription schedule. | Object |
| status | Current subscription status. Possible values are active, inactive. | String |
| token | Payment token used for subscription. | String |
| payment_type | The payment method used by the customer. Value: credit_card.Note: Currently only credit_card and gopay are supported. | String |
| metadata | Metadata of subscription specified by you. Note: Limit the size to less than 1KB. | Object |
| customer_details | Details of the customer. | Object |
| status_message | Description of the error. | String |
| validation_message | Detailed description of the error. | Array(String) |