?> Payment Link API is still in BETA phase. But is currently usable on Midtrans Production & Sandbox environment. Feel free to contact our Support Team (or your Midtrans' Sales Account Manager) to share your feedback or question.
You can visit general overview of Payment Link API, in case you haven't.
- Merchant's backend sends request to Create Payment Link API, in order to retrieve payment URL.
- Share the payment URL to Customer (e.g. via system, messaging app, or Midtrans automated email), and then wait for them to proceed to payment.
- Merchant gets notified of payment status changes & handles accordingly.
- Optional: Merchant can also use other API endpoints to manage Payment Link. For example to read/delete Payment Link as needed.
The followings reference will explain the Payment Link API.
| Environment | API Host Base URL |
|---|---|
| Sandbox | https://api.sandbox.midtrans.com |
| Production | https://api.midtrans.com |
*Learn more about what is Sandbox Environment.
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.
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.
{
"transaction_details": {
"order_id": "001",
"gross_amount": 190000,
"payment_link_id": "for-payment-123"
},
"credit_card": {
"secure": true
},
"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."
},
"custom_field1": "custom field 1 content",
"custom_field2": "custom field 2 content",
"custom_field3": "custom field 3 content"
}| Parameter | Required | Type | Description |
|---|---|---|---|
| transaction_details | required | Object | Specific information regarding the transaction. |
| 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. 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. |
| 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. |
| 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. |
| 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. 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. |
| 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. |
| 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. |
The value of these parameters will be specified by Merchant (not Midtrans).
| 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. |
The value of these parameters will be specified by Merchant (not Midtrans).
| 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. |
BCA Virtual Account Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| va_number | optional | String(11) | Custom Virtual Account Number. |
BNI Virtual Account Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| va_number | optional | String(8) | Custom Virtual Account Number. |
Permata Virtual Account Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| va_number | optional | String(10) | Custom Virtual Account Number. |
BRI Virtual Account Object
| Parameter | Required | Type | Description |
|---|---|---|---|
| va_number | optional | String(13) | Custom Virtual Account Number. |
Sample Request including Headers & Body.
curl --location --request POST 'https://api.sandbox.midtrans.com/v1/payment-links' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic U0ItTWlkLXNlcnZlci1UT3ExYTJBVnVpeWhoT2p2ZnMzVV7LZU87' \
--data-raw '{
"transaction_details": {
"order_id": "concert-ticket-05",
"gross_amount": 190000,
"payment_link_id": "amazing-ticket-payment-123"
},
"credit_card": {
"secure": true
},
"usage_limit": 5,
"expiry": {
"duration": 30,
"unit": "days"
},
"item_details": [
{
"id": "tix-001",
"name": "Exclusive Tour Concert Day 1",
"price": 95000,
"quantity": 2
}
],
"customer_details": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+62181000000000",
"notes": "Thank you for your order. Please follow the instructions to complete payment."
}
}
'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.
HTTP Status Code: 200
{
"order_id": "concert-ticket-05",
"payment_url": "https://app.sandbox.midtrans.com/payment-links/amazing-ticket-payment-123"
}HTTP Status Code: 409
{
"error_messages": [
"The Order ID 'order-123' has been taken"
]
}HTTP Status Code: 401
{
"error_messages": "Access denied due to unauthorized request"
}HTTP Status Code: 400
{
"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 [-]"
]
}
| Property | Descriptions |
|---|---|
| order_id | Merchant’s Order ID |
| payment_url | The resulting payment url to share with Customer. |
| error_messages | The message describing the error, if any error encountered. |
Response properties are conditional, depending on whether the API response is success or failure. E.g. error_messages may only exists on failure response.
| 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 |
Merchant sends HTTP API request to this endpoint with the specified Order ID to delete the Payment Link. Useful to deactivate some specific Payment Links when merchant no longer want Customer to pay for it.
Endpoints: /v1/payment-links/{order_id}
HTTP Method: DELETE
Headers:
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTH_STRING
Authorization AUTH_STRING value is result of Base64Encode("YourServerKey"+":")
Sample Request including Headers & Body.
curl --location --request DELETE 'https://api.sandbox.midtrans.com/v1/payment-links/1525840754698' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic U0ItTWlkLXNlcnZlci1UT3ExYTJBVnVpeWhoT2p2ZnMzVV7LZU87'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.
HTTP Status Code: 200
{
"message": "Payment Link with Order ID 1525840754698-1647594290 deleted"
}| Status Code | Descriptions |
|---|---|
| 200 | Request is successful |
| 404 | Not Found |
| 401 | Access denied due to unauthorized request |
| 500 | Internal Server Error |
The created Payment Link(s) will then be available to be viewed & managed via Midtrans Dashboard.
Merchant can customize the Redirect URL in Dashboard's Settings > Snap Preference > System Settings Menu. Redirect URL will be used to redirect your customer after the payment process. Follow this section to learn the details..
Transaction notification will be sent to your backend/system when Customer completes the transaction or when the transaction status changes.
Merchant's HTTP notification URL can be configured on merchant dashboard, Midtrans will send HTTP notification to the specified URL.
There are also several ways to ensure authenticity of the HTTP notifications received by Merchant backend, in order to improve security aspect.
For each payment created/attempted (on any Payment Link) Midtrans will automatically append merchant's original Payment Link's Order ID with a timestamp, from order_id to order_id-{timestamp}.
For example from: order123 to order123-1647944535605.
So Merchant need to make sure that their system is able to handle this change when processing payment's HTTP notification. As Merchant may need to map the resulting Order ID back to the original specified Order ID.
For example, here are some ideas to do that:
In Merchant's notification handler code in backend, Merchant can implement logic to convert back the modified Order ID to the original Order ID that their system recognizes.
For example the logic must be able to convert order123-1647944535605 back to order123, by disregarding string after the last occurence of - character.
Alternatively, Merchant can optionally sends custom_field1 JSON body parameter with the original order_id when create payment link. Like so:
{
"transaction_details": {
"order_id": "order123",
"gross_amount": 10000
},
...
"custom_field1": "order123"
}So that later when merchant receive the notification from Midtrans, the original order_id will be available on the HTTP Notification within the same custom_field1 JSON property.
{
"va_numbers": [
{
"va_number": "00018929808",
"bank": "bca"
}
],
"transaction_time": "2022-03-22 17:22:21",
"transaction_status": "pending",
"transaction_id": "1d02cdda-a424-4e6e-a711-154f004bc26d",
"status_message": "midtrans payment notification",
"status_code": 201,
"signature_key": "caa79748f56892a8664633331d6b719320ccda008d44d10d56156988700ca37067b9d6531d0b4778366707ce0fb859ea6f38499f6f03283f48007e6d77956afe",
"payment_type": "bank_transfer",
"payment_amounts": [],
"order_id": "merchant-order-id-1-1647944535605",
"merchant_id": "G379181825",
"gross_amount": 10000,
"fraud_status": "accept",
"custom_field1": "order123",
"currency": "IDR"
}Once Customer has initiated a payment and payment is created on Midtrans side:
- Merchant can further perform other API actions to the transaction.
- Other After Payment sections explanations also applies to the payment transaction.
Under the hood, Payment Link product utilize Snap Payment product to present payment page. So, please note that most configurations, parameters, and behaviours of Snap Payment is also inherited by Payment Link. For example:
Notable benefits & differences compared to Snap Payment product:
- Support more than 7 days link expiry period. There is no defined maximum expiry period limit.
- Payment Link can be paid more than once or any specified limit. Snap Payment link can only be paid once.
- The created Payment Links are visible and manageable via Midtrans Dashboard.
- Automatic email of Payment Link & payment instruction will be sent to Customer (if merchant specify their email).
- Link/URL is customizable. e.g.
https://app.midtrans.com/payment-links/my-product-123 - The resulting payment Order ID in Midtrans dashboard will be appended with timestamp suffix.
Notable benefits & differences compared to Payment Link creation via Midtrans Dashboard:
- Payment Link creation can be programmatically automated, via system integration to our API according to your business needs. Although you will need your development resource to integrate with the API we provide.
- Can be programmatically integrated to the merchant's system. Especially the backend system, store CMS, POS, Invoicing system, etc.
- More suitable for SMB/Enterprise merchant, that has their own website/system and wants to automate Payment Link creation.