Create a payment

POST/v1/paymentsRun

Requires payments:write permission.

Headers

Idempotency-Keystringrequired

Example: order-1001-attempt-1

Required. A unique string for this request. See Idempotency.

Request body

project_idstringoptional

The project to make the payment in. Needed with a merchant key; a project key already names its project.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

amountintegerrequired

Base payment amount before fees, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 12500000

Minimum: 1

Maximum: 100000000000

currencystringrequired

The currency, an ISO 4217 code. Only IDR today.

Example: IDR

Value: IDR

payment_methodstringrequired

Method used by the payer: payment.qris, payment.va.<bank>, payment.ewallet.<wallet> or payment.retail.<outlet>. See List payment methods.

Example: payment.qris

Pattern: ^payment\.(qris|(va|ewallet|retail)\.[a-z0-9_]+)$

merchant_referencestringoptional

Your own reference for the payment, such as an order number, up to 100 characters. Use it to find the payment again.

Example: order-1001

Min length: 1

Max length: 100

descriptionstringoptional

A note about the payment that the payer sees, up to 500 characters.

Example: Pesanan kopi 1001

Min length: 1

Max length: 500

expires_inintegeroptional

Seconds until the payment expires, from 300 (5 minutes) to 604800 (7 days). The default depends on the method.

Example: 3600

Minimum: 300

Maximum: 604800

customerobjectoptional

Payer details. Some methods, such as OVO, require a phone number.

namestringoptional

The payer's name, attached to the payment and shared with the selected payment method when needed.

Example: Budi Santoso

Min length: 1

Max length: 120

emailstringoptional

The payer's email. Baiyar mails the receipt here in live.

Example: budi@example.com

Format: email

Max length: 254

phonestringoptional

The payer's phone number, with or without +, 6 to 20 digits.

Example: +628123456789

Pattern: ^\+?[0-9]{6,20}$

metadataobjectoptional

Up to 20 pairs of your own (names up to 40 characters, values up to 500) that come back with the payment and in its events.

Values: string

Max keys: 20

Response (201)

dataobjectrequired

The returned object, or an array of objects for a list.

idstringrequired

The id of the payment (pay_…).

Example: pay_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with pay_.

livemodebooleanrequired

true means this object belongs to live and can involve real payments; false means it belongs to the sandbox.

statusstringrequired

created (no method chosen yet), pending (waiting for the payer), paid, failed or expired.

Example: pending

Possible values: created, pending, paid, failed, expired

project_idstringrequired

The project this object belongs to. Its settings determine which payment methods and limits apply.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

payment_link_idstring | nullrequired

The payment link it was made through; null when it was not.

Example: lnk_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with lnk_.

amountintegerrequired

Base payment amount before fees, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 12500000

currencystringrequired

The currency, an ISO 4217 code. Only IDR today.

Example: IDR

Value: IDR

payment_methodstring | nullrequired

Method used by the payer: payment.qris, payment.va.<bank>, payment.ewallet.<wallet> or payment.retail.<outlet>. See List payment methods.

Example: payment.qris

feeobject | nullrequired

Baiyar's fee, fixed when the payer sees the amount. Null until a payment method is chosen.

amountintegerrequired

The fee, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 7000

bearerstringrequired

Who bears the fee: merchant or customer.

Example: merchant

Possible values: merchant, customer

charged_amountinteger | nullrequired

Total charged to the payer, including the fee when the payer bears it, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 1000000

net_amountinteger | nullrequired

The amount credited after the Baiyar fee, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 993000

merchant_referencestring | nullrequired

Your own reference for the payment, such as an order number, up to 100 characters. Use it to find the payment again.

Example: order-1001

descriptionstring | nullrequired

A note about the payment that the payer sees, up to 500 characters.

Example: Pesanan kopi 1001

instructionobject | nullrequired

The QR code, account number or other details the payer needs to complete the payment. Null when no instructions are needed.

typestringrequired

va, qr, ewallet_link, ewallet_push or retail_code. It decides which of the other fields are present.

Possible values: va, qr, ewallet_link, ewallet_push, retail_code

bank_codestringrequired

The bank of the virtual account, for example bca.

Example: bca

When type is va.

account_numberstringrequired

The virtual account number the payer transfers to.

Example: 8277012345678901

When type is va.

expires_atstringrequired

When the instruction stops working (RFC 3339, UTC).

Example: 2026-10-26T03:04:05.000Z

Format: date-time

qr_contentstringrequired

The QRIS content: draw it as a QR code for the payer to scan.

Example: 00020101021226670016COM.BAIYAR.WWW01189360091400000001230210000000000303UMI51440014ID.CO.QRIS.WWW0215ID10200000000010303UMI5204581253033605802ID5906Toko6007Jakarta6304ABCD

When type is qr.

payment_urlstringrequired

Where to send the payer to approve the payment in their wallet.

Example: https://pay.example.com/wallet/abc123

When type is ewallet_link.

wallet_codestringrequired

The wallet that asks the payer to approve in its own app, for example ovo.

Example: ovo

When type is ewallet_push.

phone_last4string | nullrequired

The last four digits of the phone number used for the wallet approval request.

Example: 6789

When type is ewallet_push.

payment_codestringrequired

The code the payer gives at the outlet.

Example: ALFA123456

When type is retail_code.

expires_atstring | nullrequired

When this object expires (RFC 3339, UTC). For a payment, it is the payer's deadline; for a link, it is when the link stops accepting payments.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

paid_atstring | nullrequired

When the payment was confirmed as paid (RFC 3339, UTC); null until then.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

settlement_statusstringrequired

not_applicable (not paid), awaiting (paid, settlement not matched yet) or settled (matched and moved to available balance).

Example: awaiting

Possible values: not_applicable, awaiting, settled

reversalobject | nullrequired

Details of a paid amount reversed by the provider or Baiyar operations; null when there is no reversal.

amountintegerrequired

The amount removed from the balance by the reversal, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 993000

reversed_atstringrequired

When the reversal was recorded (RFC 3339, UTC).

Example: 2026-10-26T03:04:05.000Z

Format: date-time

metadataobjectrequired

Up to 20 pairs of your own (names up to 40 characters, values up to 500) that come back with the payment and in its events.

Values: string

Max keys: 20

created_atstringrequired

When this object was created (RFC 3339, UTC). Use it to sort objects by creation time.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

metaobjectrequired

Request details such as its id and pagination cursor.

request_idstringrequired

The id of this request. Quote it when you ask support about it.

Example: req_Hy3k9QzT2LmN8vXa

A failed request answers with the common error shape; see Errors.

Request

curl -X POST "https://api.baiyar.com/v1/payments" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "merchant_reference": "order-1001",
    "description": "Pesanan kopi 1001"
  }'

Response

{
  "data": {
    "id": "pay_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "livemode": false,
    "status": "pending",
    "project_id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "payment_link_id": "lnk_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "amount": 12500000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "fee": {
      "amount": 7000,
      "bearer": "merchant"
    },
    "charged_amount": 1000000,
    "net_amount": 993000,
    "merchant_reference": "order-1001",
    "description": "Pesanan kopi 1001",
    "instruction": {
      "type": "qr",
      "bank_code": "bca",
      "account_number": "8277012345678901",
      "expires_at": "2026-10-26T03:04:05.000Z"
    },
    "expires_at": "2026-10-26T03:04:05.000Z",
    "paid_at": "2026-10-26T03:04:05.000Z",
    "settlement_status": "awaiting",
    "reversal": {
      "amount": 993000,
      "reversed_at": "2026-10-26T03:04:05.000Z"
    },
    "metadata": {
      "order_id": "1001"
    },
    "created_at": "2026-10-26T03:04:05.000Z"
  },
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa"
  }
}