post https://api.sandbox.midtrans.com/v1/payment-links
Merchant sends HTTP API request with the desired transaction details to this endpoint, and will get API response mainly with the Payment Link URL. The URL then should be shared to & opened by Customer, to initiates payment.
Request
Endpoints: /v1/payment-links
HTTP Method: POST
Headers:
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTH_STRING
AUTH_STRING value is result of Base64Encode("YourServerKey"+":")
Midtrans API validates HTTP request by using Basic Authentication method. The username is your Server Key while the password is empty. The authorization header value is represented by AUTH_STRING. AUTH_STRING is base-64 encoded string of your username and password separated by colon symbol (:). For more details, refer to API Authorization and Headers.
Request Body
{
"transaction_details": {
"order_id": "001",
"gross_amount": 190000,
"payment_link_id": "for-payment-123"
},
"customer_required": true,
"credit_card": {
"secure": true,
"bank": "bca",
"installment": {
"required": false,
"terms": {
"bni": [
3,
6,
12
],
"mandiri": [
3,
6,
12
],
"cimb": [
3
],
"bca": [
3,
6,
12
],
"offline": [
6,
12
]
}
}
},
"usage_limit": 1,
"expiry": {
"start_time": "2022-04-01 18:00 +0700",
"duration": 20,
"unit": "days"
},
"enabled_payments": [
"credit_card",
"bca_va",
"indomaret"
],
"item_details": [
{
"id": "pil-001",
"name": "Pillow",
"price": 95000,
"quantity": 2,
"brand": "Midtrans",
"category": "Furniture",
"merchant_name": "PT. Midtrans"
}
],
"customer_details": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+62181000000000",
"notes": "Thank you for your purchase. Please follow the instructions to pay.",
"customer_details_required_fields": [
"first_name",
"phone",
"email"
]
},
"title": "test title",
"payment_link_type": "DYNAMIC_AMOUNT",
"dynamic_amount": {
"min_amount": 5000,
"max_amount": 5000,
"preset_amount": 5000
},
"custom_field1": "custom field 1 content",
"custom_field2": "custom field 2 content",
"custom_field3": "custom field 3 content",
"callbacks": {
"finish": "https://www.google.com?merchant_order_id=test-122"
}
}
Request JSON Body Details
| Parameter | Required | Type | Description |
|---|---|---|---|
| transaction_details | required | Object | Specific information regarding the transaction. |
| customer_required | optional | Boolean | If set as True, Payment Link will prompt user to fill in customer details (name, phone and email) before customer can proceed to pay - which field set as mandatory can be specified in customer_details. If set as false, Payment Link will still show the customer details input form but it's not mandatory (customer can continue to the next page without filling any) |
| customer_details | optional | Object | Specific information regarding the customer. Note: If Merchant sends customer_detail’s email on the request, Midtrans will send the created Payment Link url to the customer’s email. |
| item_details | optional | Object | Details of the purchased items. Will be shown to customer during payment and shown in Midtrans Dashboard. |
| usage_limit | optional | integer | Maximum number of allowed successful/paid transactions. Max accepted value is 1000000 (1 million usage). Note: Each successful/paid payment will consume a "usage" quota. A pending payment (payment attempted, but still waiting for Customer to make payment e.g. waiting Bank Transfer, Gopay, QRIS, etc.) will temporarily hold a usage quota, but if it is abandoned/left-unpaid (becomes expire) it will release the usage quota back. |
| expiry | optional | Object | Customizable transaction lifetime. Once the duration exceeded, the link will no longer be available. |
| enabled_payments | optional | Array | Customizable list of payment methods that will be shown during payment. If not specified, by default all active payment methods are shown. Options: credit_card, gopay, cimb_clicks, bca_klikbca, bca_klikpay, bri_epay, telkomsel_cash, echannel, permata_va, other_va, bca_va, bni_va, bri_va, indomaret, danamon_online, akulaku, shopeepay. |
| title | optional | String(255) | Title to show in your payment link page that will be seen by your customer. Max char supported is 40. |
| payment_link_type | optional | String(255) | Pass the value DYNAMIC_AMOUNT if you want to use dynamic amount feature. Note that item_details and gross_amount will be ignored if the type passed is DYNAMIC_AMOUNT.If payment_link_type is not passed, by default Payment Link will create a FIXED_AMOUNT payment link. |
| dynamic_amount | optional | Object | Optional object if you're creating a payment link with dynamic amount features. You can set max/min amount and preset amount within this object. |
| custom_field1 | optional | String(255) | Retrievable custom text that you can pass to Midtrans on field 1. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification. |
| custom_field2 | optional | String(255) | Retrievable custom text that you can pass to Midtrans on field 2. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification. |
| custom_field3 | optional | String(255) | Retrievable custom text that you can pass to Midtrans on field 3. Wil be shown in Midtrans Dashboard, & sent on HTTP Notification. |
| callbacks | optional | Object | Callback finish URL where user will be redirected after finishing a transaction. Can append query param if needed. |
| credit_card | optional | Object | Credit card payment options. |
| bni_va | optional | Object | Customizable Virtual Account number & options for BNI VA. |
| permata_va | optional | Object | Customizable Virtual Account number & options for Permata VA. |
| bca_va | optional | Object | Customizable Virtual Account number & options for BCA VA. |
| bri_va | optional | Object | Customizable Virtual Account number & options for BRI VA. |
| [cimb_va | optional | Object | Customizable Virtual Account number & options for CIMB VA. |
transaction_details object
| Parameter | Required | Type | Description |
|---|---|---|---|
| order_id | required | String(50) | Unique transaction ID. A single ID could be used only once by a Merchant. Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.). |
| gross_amount | required* | Integer | Total payment amount Customer expected to pay. Required for FIXED_AMOUNT, do not use for DYNAMIC_AMOUNT Note: The Sum of Subtotal (item price multiplied by quantity) of all the item details needs to be exactly the same as the gross_amount inside transaction_details object. |
| payment_link_id | optional | String(50) | Unique Link ID that will be used as part of the resulting payment URL. A single ID could be used only once. Allowed characters are alphanumeric [a-z, 0-9] and hyphens [-]. Note: By default auto generated by midtrans. |
credit_card object
| Parameter | Required | Type | Description |
|---|---|---|---|
| secure | optional | Boolean | Specify whether 3D-Secure authentication should be used for Card payment method. Note: It is recommended to specify true for most cases. Default: false. |
| bank | optional | String | Specify which acquiring bank is preferred for Card payment method. If not specified, Midtrans will auto determine accordingly. It is recommended to not specify it. Options: bca, bni, mandiri, cimb, bri, danamon, maybank, mega. |
| channel | optional | String | Specify which acquiring channel is preferred for Card payment method's acquiring bank. If not specified, Midtrans will auto determine accordingly. It is recommended to not specify it. Options: migs |
| type | optional | String | Card payment transaction type. It is recommended to not specify it. Options: authorize, authorize_capture Default: authorize_capture |
| whitelist_bins | optional | Array | Specify list of card BIN numbers that will be allowed to pay. The BIN value can be either a prefix(up to 8 digits) of card number or the name of a bank, in which case all the cards issued by that bank will be allowed. |
| installment.required | optional | Boolean | Specify whether Customer is required to pay with installment for card payment method, if installment feature is enabled. It is recommended to not specify it. Default: false |
| installment.terms | optional | Object | Specify list of allowed installment terms, if installment feature is enabled. It is recommended to not specify it. |
expiry object
| Parameter | Required | Type | Description |
|---|---|---|---|
| start_time | optional | String Timestamp in yyyy-MM-dd HH:mm:ss Z format |
Timestamp of when the expiry period should start. If not specified, transaction time will be used as start time when payment link is created |
| duration | required | Integer | Expiry duration value. |
| unit | required | String | Expiry duration unit. Options: day, hour, minute. |
item_details object
The value of these parameters will be specified by Merchant.
| Parameter | Required | Type | Description |
|---|---|---|---|
| id | optional | String | Item ID. |
| price | required | Integer | Price of the item. NOTE: Don’t add decimal. |
| quantity | required | Integer | Quantity of the item. NOTE: Must be greater than or equal 1. |
| name | required | String(50) | Name of the item. |
| brand | optional | String(50) | Brand of the item. |
| category | optional | String(50) | Category of the item. |
| merchant_name | optional | String(50) | Merchant selling the item. Useful if you have multiple sub-merchants within your commerce platform. |
Implementing Discounts
You can actually input negative amount as part of the item details in the case there's a need to show Discounts as part of the checkout item details. Make sure however the final gross amount sent is the correct sum of all item details, otherwise charge will fail.
customer_details object
The value of these parameters will be specified by Merchant. If Merchant provide customer_details object in the request, merchant should provide minimum one of three required field as shown below.
| Parameter | Required | Type | Description |
|---|---|---|---|
| first_name | required* | String(50) | Customer's first name. |
| last_name | optional | String(50) | Customer's last name. |
| required* | String(50) | Customer's email address. | |
| phone | required* | String(20) | Customer's phone number. |
| notes | optional | String(255) | Customizable email instructions. |
| customer_details_required_fields | optional | Array of String(255) | When customer_required is true, merchant could specify which fields are required between "first_name", "phone" and "email" to be filled by customer |
Virtual Account Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| va_number | optional | String(11) | Custom Virtual Account Number. |
dynamic_amount object
| Parameter | Required | Type | Description |
|---|---|---|---|
| min_amount | optional | Integer | Min amount that customer can input in payment link page. |
| max_amount | optional | Integer | Max amount that customer can input in payment link page. |
| preset_amount | optional | Integer | Prefilled amount - customer will see this amount upon opening payment link page, but they can still edit it. |
Request Sample
See sample request on the right -- try it yourself!
Response
For successful response you will receive HTTP status code 2xx as a response. For failure response you may receive HTTP status code 4xx or 5xx.
Sample Success Response
{
"order_id": "concert-ticket-05",
"payment_url": "https://app.sandbox.midtrans.com/payment-links/amazing-ticket-payment-123"
}
Sample Failure Response
{
"error_messages": [
"The Order ID 'order-123' has been taken"
]
}
{
"error_messages": "Access denied due to unauthorized request"
}
{
"error_messages": [
"Invalid JSON data provided.",
"This Payment Link ID 'payment-112' has been taken",
"payment_link_id must only contain alphanumeric characters [a-z, 0-9] and hyphens [-]"
]
}
Response JSON Body Details
Response properties are conditional, depending on whether the API response is success or failure. E.g. error_messages may only exists on failure response.
HTTP Status Code
| Status Code | Descriptions |
|---|---|
| 200 | Request is successful |
| 409 | Duplicate order ID. Order ID has already been utilized previously |
| 401 | Access denied due to unauthorized request |
| 400 | Validation Error / Invalid JSON |
| 500 | Internal Server Error |