For archived content, access the previous documentation here or the previous API reference here.

Create Payment

  • Updated on Aug 8, 2025
  • Published on Aug 8, 2025
Prev Next
Post
/bill-payments/v1/payment

This endpoint allows users to submit a payment for a specific product. It can be used for various types of payments, including utility bills, prepaid services, and other products that may or may not require a prior inquiry.

Security
HTTP
Type Basic
Header parameters
Idempotency-Key
stringRequired

Unique key to prevent duplicate payments. Must be unique for each payment request.

Exampleunique-idempotency-key-123
Body parameters
plnPrepaid

PLN Prepaid Payment

{
  "product_id": "PLN_PREPAID_50K",
  "customer_number": "12345678910",
  "inquiry_id": "inq-98765",
  "reference_id": "tx-pln-001",
  "total_amount": 53200,
  "additional_properties": {}
}
plnPostpaid

PLN Postpaid Payment

{
  "product_id": "PLN_POSTPAID",
  "customer_number": "22345678910",
  "inquiry_id": "inq-98766",
  "reference_id": "tx-pln-postpaid-001",
  "total_amount": 159500
}
Expand All
object
product_id
string Required

Product identifier

customer_number
string Required

Customer's account/service number

inquiry_id
string

Inquiry ID from POST /inquiry (optional)

reference_id
string Required

Partner's unique transaction reference

total_amount
number Required

Total payment amount including admin fee

additional_properties
object

Additional parameters required for specific products

Responses
200

Payment accepted for processing

plnPrepaidPending

PLN Prepaid Payment - Pending

{
  "data": {
    "business_id": "5f27a14a9bf05c73dd040bc8",
    "type": "payment",
    "id": "trx-98765",
    "properties": {
      "product_id": "PLN_PREPAID_50K",
      "customer_number": "12345678910",
      "reference_id": "tx-pln-001",
      "admin_amount": 3200,
      "base_amount": 50000,
      "total_amount": 53200,
      "currency": "IDR",
      "status": "PENDING",
      "fulfilled_at": null,
      "failure_code": null,
      "failure_reason": null,
      "customer_details": [],
      "product_details": [],
      "bill_details": [],
      "payment_details": []
    }
  }
}
Expand All
object
data
object
business_id
string

Xendit's Business ID

type
string

Type of response, always "payment"

Valid values[ "payment" ]
id
string

Unique payment transaction ID

properties
object
reference_id
string

Partner's transaction reference

product_id
string

Product identifier

customer_number
string

Customer's account/service number

admin_amount
number

Administrative fee amount

base_amount
number

Base product amount

total_amount
number

Total amount including admin fee

currency
string

Currency of the product

status
string

Payment status

Valid values[ "PENDING", "SUCCEEDED", "FAILED" ]
fulfilled_at
string (date-time) | null

ISO8601 timestamp when payment completed (null when pending)

failure_code
string | null

Error code in case of FAILED status

failure_reason
string | null

Error message in case of FAILED status

customer_details
Array of object (BillPaymentDetailKeyValue)

Array of customer information key-value pairs

object
key
string

Name of the detail field

value
string

Value of the detail field

product_details
Array of object (BillPaymentDetailKeyValue)

Array of product information key-value pairs

object
key
string

Name of the detail field

value
string

Value of the detail field

bill_details
Array of object (BillPaymentDetailKeyValue)

Array of billing information key-value pairs

object
key
string

Name of the detail field

value
string

Value of the detail field

payment_details
Array of object (BillPaymentDetailKeyValue)

Array of payment information key-value pairs

object
key
string

Name of the detail field

value
string

Value of the detail field

400

Inputs are failing validation. The errors field contains details about which fields are violating validation.

object
error_code
string
Valid values[ "API_VALIDATION_ERROR", "FEATURE_NOT_AVAILABLE" ]
message
string
errors
Array
OneOf
string
string
object
object
402

Payment Required - Insufficient balance

object
error_code
string
Valid values[ "API_VALIDATION_ERROR", "FEATURE_NOT_AVAILABLE" ]
message
string
errors
Array
OneOf
string
string
object
object
404

The provided id does not exist. Please review the id and try again

object
error_code
string
Valid values[ "RATE_LIMIT_EXCEEDED" ]
message
string
errors
Array
OneOf
string
string
object
object
409

Conflict

object
error_code
string
Valid values[ "DUPLICATE_ERROR", "IDEMPOTENCY_ERROR" ]
message
string
errors
Array
OneOf
string
string
object
object
502

Bad Gateway - Biller error

object
error_code
string
Valid values[ "API_VALIDATION_ERROR", "FEATURE_NOT_AVAILABLE" ]
message
string
errors
Array
OneOf
string
string
object
object
503

Service Unavailable - Biller maintenance

object
error_code
string
Valid values[ "API_VALIDATION_ERROR", "FEATURE_NOT_AVAILABLE" ]
message
string
errors
Array
OneOf
string
string
object
object
504

Gateway Timeout - Biller timeout

object
error_code
string
Valid values[ "API_VALIDATION_ERROR", "FEATURE_NOT_AVAILABLE" ]
message
string
errors
Array
OneOf
string
string
object
object