Create a subscription or recurring 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.
Subscription API currently supports idempotency when creating subscription. If you're using the same idempotency key, you will continue to receive the same response. Subscription will validate the request body first before performing the idempotency check - this idempotency applies for the next 3 minutes for the same key.
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"
}
}
{
"name": "MONTHLY_2019",
"amount": "14000",
"currency": "IDR",
"payment_type": "gopay",
"token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==",
"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 (Card Payment) | The saved_token_id for Card Payment. Credit Card token retrieved via Get Pay Account API | String | Required |
| token (GoPay) | The token for Gopay Tokenization. GoPay token retrieved via Get Pay Account API | 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 | Conditional |
Obtaining GoPay token
Get Pay Account API is called to retrieve GoPay Token, needed for GoPay subscriptions. Account ID can be retrieved from HTTP notification of first transaction charge that will be used to create subscription for the scheduled subsequent charges.
| HTTP Method | Endpoint | Definition |
|---|---|---|
| GET | BASE_URL/v2/pay/account/account_id | Get GoPay's account information and linked status. |
{
"status_code": "200",
"payment_type": "gopay",
"account_id": "00000269-7836-49e5-bc65-e592afafec14",
"account_status": "ENABLED",
"metadata": {
"payment_options": [
{
"name": "GOPAY_WALLET",
"active": true,
"balance": {
"value": "1000000.00",
"currency": "IDR"
},
"metadata": {},
"token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==" // The token is used for Subscription
}
]
}
}
Obtaining card token & GoPay account ID via Get Transaction API
Get Transaction API is used to get card token that has been saved in the first transaction charge facilitated in a One Click flow, or GoPay account_id mapped to the user_id passed during create Snap Token creation, that is needed to make the subsequent scheduled charges with Subscription API.
| HTTP Method | Endpoint | Definition |
|---|---|---|
| GET | BASE_URL/v2/{order_id OR transaction_id}/status | Get the status of transaction and card information. |
{
"masked_card": "48111111-1114",
"approval_code": "1689306913393",
"bank": "cimb",
"eci": "05",
"saved_token_id": "48111111ktaqYoxJQAGvXBoxEPqO1114", // The token is used for Subscription
"saved_token_id_expired_at": "2024-11-30 07:00:00",
"channel_response_code": "00",
"channel_response_message": "Approved",
"three_ds_version": "2",
"transaction_time": "2023-07-14 10:55:09",
"gross_amount": "20000.00",
"currency": "IDR",
"order_id": "sample-store-1689306888",
"payment_type": "credit_card",
"signature_key": "40df7114b015e899526f78f98ff7a0297fa8ba270e5a436687af9cfee2ec471444dd239834d8836f217b1bdf12e9677cb65643470dc666c578fb120b8135480b",
"status_code": "200",
"transaction_id": "a4e2f006-2cc1-4110-ac38-811e4c427199",
"transaction_status": "capture",
"fraud_status": "accept",
"expiry_time": "2023-07-14 11:05:09",
"status_message": "Success, Credit Card transaction is successful",
"merchant_id": "M123",
"card_type": "credit",
"challenge_completion": true
}
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"
}
}
{
"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"
},
"gopay": {
"account_id": "phy56f8f-2683-4248-8080-e59b36c6bbgf"
}
}
{
"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 | Notes |
|---|---|---|---|
| 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 (Card Payment) | The saved_token_id for Card Payment. Credit Card token retrieved via Get Pay Account API. | String | |
| token (GoPay) | Token that is retrieved via Get Pay Account API | 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 | Conditional |
| customer_details | Details of the customer. | Object | |
| status_message | Description of the error. | String | |
| validation_message | Detailed description of the error. | Array(String) | |
| account_id (GoPay) | GoPay account ID | String |
Retry Mechanism if Subscription Fails
If for some reason deduction fails, Midtrans will perform automatic retries 3 times for every one hour before marking subscription as inactive. To test for the automatic retries, you can try to simulate with cases that returns error such as incorrect card token, or GoPay account is in unlinked state prior to charge.
Example of retry schedules :
There's a payment that's failed to be processed at 11 Oct 2022 15.48 GMT+7. Then, Midtrans will automatically retry at :
- 11 Oct 2022 16.48 GMT+7
- 11 Oct 2022 17.48 GMT+7
- 11 Oct 2022 18.48 GMT+7
Midtrans will then notify merchants after 3 times automatic retry with error codes depending on the failure reason. Otherwise, if Midtrans encountered any 202 errors during the automatic retry (prior to the 3rd retry attempt), Midtrans will also notify merchants.