Developer documentation

Create a payment via API

Last updated:

The initPayment method initiates a payment from your server. Pass the payment intent (project, amount, currency, customer reference, description) to UnitPay; UnitPay returns a hosted payment URL that you redirect the customer to. After the customer completes the payment, UnitPay notifies your callback handler — see Callback handler.

Endpoint

Send a request to https://api.unitpay.net/api. The request body uses query-string-style parameters under params[...]. Both GET and POST are accepted; production traffic should use POST over TLS.

Required parameters

ParameterTypeDescription
methodstringAlways initPayment.
params[paymentType]stringPayment-method code: card, qris, va, or another method enabled on your project. Contact onboarding to see the codes available to you.
params[projectId]integerYour project ID, visible in the merchant cabinet under Settings → Project.
params[sum]numberPayment amount in major currency units (for example, 150000.00 for IDR 150,000 or 10.00 for USD 10). Two decimal places maximum.
params[account]stringCustomer or order identifier in your system. Returned unchanged in callbacks so you can match the result to the original order.
params[desc]stringHuman-readable order description shown to the customer on the payment form and on the receipt.

Optional parameters

ParameterTypeDescription
params[currency]stringISO 4217 currency code: IDR, USD, or EUR. Defaults to the project's primary currency.
params[locale]stringPayment-form language: en or id. Auto-detected from the customer's Accept-Language header when omitted.
params[backUrl]stringURL the customer is sent to if they abandon the payment. Must use a domain registered to your project.
params[resultUrl]stringURL the customer is sent to after a successful payment. URL-encode any query string.
params[customerEmail]stringCustomer email used for the receipt.
params[signature]stringRequest signature. Required when "API request signing" is enabled on the project. See Signing the request below.

Signing the request

UnitPay signs requests with HMAC-SHA-256 using your project secret key. Reuse the same algorithm you use to verify incoming callbacks (see Callback handler — signature verification):

  1. Take all params[*] values except params[signature] and sort them by parameter name.
  2. Concatenate the values, separated by the literal four-character delimiter {up}, in this order: method, then each sorted parameter value, then your project secret key.
  3. Hash the resulting string with SHA-256 and lowercase the hex digest.
  4. Pass the digest as params[signature].

Never embed the secret key in client-side code or log it. Rotate it from Settings → Project → Secret key if you suspect compromise.

Example request

POST https://api.unitpay.net/api
Content-Type: application/x-www-form-urlencoded

method=initPayment
&params[paymentType]=card
&params[projectId]=123456
&params[sum]=150000.00
&params[currency]=IDR
&params[account]=order-9821
&params[desc]=Order%20%239821
&params[locale]=en
&params[signature]=<sha256-hex-digest>

Successful response

UnitPay replies with HTTP 200 and a JSON body that includes the hosted payment URL. Redirect the customer's browser to redirectUrl.

{
  "result": {
    "type": "redirect",
    "paymentId": 1231231234,
    "message": "Payment created.",
    "receiptUrl": "https://pay.unitpay.net/receipt/1231231234-12d1fae123",
    "statusUrl": "https://pay.unitpay.net/receipt/1231231234-12d1fae123",
    "redirectUrl": "https://pay.unitpay.net/123456-1fc2f/card?..."
  }
}
FieldDescription
typeredirect — redirect the customer to redirectUrl; response — the message field is final, display it to the customer; invoice — an invoice was emailed to the customer, no further action required.
paymentIdUnitPay's unique payment identifier. Store it alongside your account reference so you can correlate callbacks and refunds.
redirectUrlHosted payment URL. Valid until the payment expires (15 minutes by default).
receiptUrlHosted receipt URL the customer can revisit later.

Error response

{
  "error": {
    "message": "Invalid signature.",
    "code": -32010
  }
}

Treat any response that contains an error object as a hard failure: do not retry blindly. Common causes are an incorrect projectId, a signature mismatch, an unsupported currency, or a payment-method code that is not enabled for your project.

Test mode

Every project has a separate test secret key and a test toggle in the merchant cabinet. Test-mode payments use the same endpoint and parameters but never move real funds, and the callback handler receives params[test]=1 for those transactions. Switch to test mode while you implement and verify your integration end-to-end before enabling live payments.

Next steps