Payment Initiation

POST/payment/initiate

Create Payment order

To initiate a payment, send a POST request to the payment initiation endpoint: POST /payment/initiate. Upon successful initiation, the API will return a payment URL for redirecting customers to complete their payment.

Required Parameters

You should include these parameters in the JWT payload alongside other parameters required for authentication.

Name
orderReference
Type
string
Description
Unique identifier for the order transaction.
Name
amount
Type
numeric
Description
Transaction amount. Must be a positive number. This field may be optional for some configurations but can require additional approval from Urbo before activation.
Name
currency
Type
string
Description
Transaction currency code. Currently supported: EUR.
Name
country
Type
string
Description
Two-letter ISO country code. Currently supported: LT.
Name
locale
Type
string
Description
Language/locale code for payment interface. Currently supported: lt, en.
Name
clientRedirectUrl
Type
string
Description
Callback URL for post-payment customer redirection.

Optional Parameters

Name
webhookUrl
Type
string
Description
Endpoint URL for receiving payment status notifications. If not provided, webhook notifications will not be sent.
Name
customerEmail
Type
string
Description
Customer's email address for payment notifications.
Name
paymentProviderId
Type
integer
Description
Specific payment provider identifier. Must be valid for the selected country.

Payload example in JSON

{
  "jti": "e.g. 9f3c2a1b7d9e4c51", 
  "exp": 1718112345,
  "accessKey": "your-access-key",
  "orderReference": "ORDER123",
  "amount": 100.00,
  "currency": "EUR",
  "country": "LT",
  "locale": "en",
  "customerEmail": "customer@example.com",
  "clientRedirectUrl": "https://{merchant_domain}/payment/return",
  "webhookUrl": "https://{merchant_domain}/api/payment/webhook",
  "paymentProviderId": 1
}

Token generation examples

// Generate JWT token for authentication
const jwt = require('jsonwebtoken');

const initiatePayment = async () => {
    const payload = {
        jti: crypto.randomBytes(8).toString('hex'),
        exp: Math.floor(Date.now() / 1000) + (5 * 60),
        accessKey: 'your-access-key',
        orderReference: 'ORDER123',
        amount: 100.00,
        currency: 'EUR',
        country: 'LT',
        locale: 'en',
        customerEmail: 'customer@example.com',
        clientRedirectUrl: 'https://{merchant_domain}/payment/return',
        webhookUrl: 'https://{merchant_domain}/api/payment/webhook',
        paymentProviderId: 1
    };

    const token = jwt.sign(payload, secret, { algorithm: 'HS256' });
};

Refer this guide on how to include token to request.

Response Format

The API returns a JSON response containing the payment details:

{
    "uuid": "019744b8-33e1-7350-bef1-1be8b7bda7aa",
    "paymentUrl": "https://mip.urbo.lt/payment/019744b8-33e1-7350-bef1-1be8b7bda7aa",
    "status": "pending"
}

Payment Flow

Customer Redirection

Upon receiving the paymentUrl, redirect the customer to complete their payment. If a paymentProviderId is specified, the customer will be directed to the selected bank's interface. Otherwise, they will be presented with the „Urbo“ Mokėjimo inicijavimo paslauga bank selection interface.

Payment Completion

After payment completion (or failure), the customer will be redirected to your specified clientRedirectUrl with a status and token parameters, for example:

https://{merchant_domain}/payment/return?status=completed&token={jwt_token}

First, validate the token. You can extract your order info from the decoded token.

The status parameter indicates the payment outcome:

processing: Payment is processing
completed: Payment successfully processed
canceled: Customer or bank initiated payment cancellation
failed: Payment processing failed

Important Note on Status Handling

The status received via clientRedirectUrl is preliminary and should only be used for displaying appropriate user interface messages. Do not use this status to update your order database and do not release goods/product based on this. For accurate payment status updates, rely only to the webhook notifications sent to your backend system.