Skip to main content
POST
/
api
/
products
/
payments
curl -X POST https://juadah-backend.vercel.app/api/products/payments \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_time": "2024-03-03T10:30:00+07:00",
    "status_code": "200",
    "transaction_status": "settlement",
    "signature_key": "abc123def456...",
    "gross_amount": "50000",
    "order_id": "66e4fa55-fdac-4ef9-91b5-733b97d1b862",
    "transaction_id": "d4e86f7c-3e4d-4f5e-8c3b-9a2b1c0d8e7f",
    "payment_type": "bank_transfer",
    "fraud_status": "accept"
  }'

HTTP/1.1 200 OK

​
Overview

This is a webhook endpoint that receives payment status notifications from Midtrans payment gateway. This endpoint is called server-to-server by Midtrans and should NOT be called directly by your application.
This endpoint is designed to be called exclusively by Midtrans servers. Do not call this endpoint from your client application. Use the “Check Order Status” endpoint instead to query order status from your application.

​
Authentication

This endpoint does NOT require cookie-based authentication as it is called by Midtrans servers. However, Midtrans includes a signature_key in the payload that should be verified for security.

​
Request Body

Midtrans sends the following payload when a transaction status changes:
​
transaction_time
string
required
ISO 8601 datetime when the transaction occurred
​
status_code
string
required
HTTP status code from the payment provider
​
transaction_status
string
required
The current status of the transactionPossible values:
  • capture - Payment captured (credit card)
  • settlement - Payment settled successfully
  • pending - Payment is pending
  • deny - Payment was denied
  • cancel - Payment was cancelled
  • expire - Payment expired
  • failure - Payment failed
  • refund - Full refund processed
  • partial_refund - Partial refund processed
  • authorize - Payment authorized (not yet captured)
​
signature_key
string
required
Security signature from Midtrans for request verification
​
gross_amount
string
required
Total transaction amount as a string
​
order_id
string
required
The order ID (UUID) that was created by the “Request Order Token” endpoint
​
transaction_id
string
required
Unique transaction ID from Midtrans
​
payment_type
string
required
The payment method used (e.g., “credit_card”, “bank_transfer”, “gopay”, etc.)
​
fraud_status
string
required
Fraud detection status from MidtransPossible values:
  • accept - Transaction is safe
  • deny - Transaction flagged as fraudulent

​
Response

The endpoint returns a simple HTTP 200 status code to acknowledge receipt of the webhook.
​
status
number
HTTP status code 200 for successful webhook processing
curl -X POST https://juadah-backend.vercel.app/api/products/payments \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_time": "2024-03-03T10:30:00+07:00",
    "status_code": "200",
    "transaction_status": "settlement",
    "signature_key": "abc123def456...",
    "gross_amount": "50000",
    "order_id": "66e4fa55-fdac-4ef9-91b5-733b97d1b862",
    "transaction_id": "d4e86f7c-3e4d-4f5e-8c3b-9a2b1c0d8e7f",
    "payment_type": "bank_transfer",
    "fraud_status": "accept"
  }'

HTTP/1.1 200 OK

​
Webhook Behavior

​
Order Completion

When the webhook receives a notification with transaction_status of either settlement or capture, the order’s completed_at timestamp is automatically set to the current time.

​
Other Status Updates

For all other transaction statuses (pending, deny, cancel, expire, failure, refund, etc.), the order status is updated but the completed_at field remains null.

​
Security Considerations

The signature_key field in the webhook payload is included by Midtrans for security verification. While the current implementation includes this field in the schema, you should implement signature verification to ensure the webhook is genuinely from Midtrans.
To verify a Midtrans webhook signature:
  1. Concatenate: order_id + status_code + gross_amount + server_key
  2. Hash the string using SHA512
  3. Compare the hash with the signature_key in the payload

​
Configuring the Webhook URL

In your Midtrans dashboard, configure the webhook notification URL to: 
https://your-domain.com/api/products/payments
Midtrans will send notifications to this endpoint whenever a transaction status changes.

​
Integration Flow

  1. Customer initiates payment via “Request Order Token” endpoint
  2. Customer completes payment on Midtrans payment page
  3. Midtrans sends webhook notification to this endpoint
  4. Server updates order status in database
  5. Your application polls “Check Order Status” endpoint to verify completion