NETOPIA Payments API - Version 1.x

Overview

[This API Version Will Be Phased Out]

Version 2.x is the latest release of the NETOPIA Payments API and is recommended for both new and existing customers. This version uses JSON endpoints and is secured with API tokens. Version 1.x will be fully phased out by the end of 2025. This documentation is provided to assist existing customers until they complete their migration.

Introduction

The NETOPIA Payments API provides a flexible and secure way to integrate payments into your applications. This guide covers the API structure, authentication, security measures, and request/response formats.

Feedback

Help us improve this guide by sending feedback to: implementare@netopia.ro

Architecture

Client-Server Model

NETOPIA API follows a client-server model:

The client (your website or application) sends a request using POST to one of NETOPIA's service endpoints.
The user is redirected to NETOPIA’s payment page.
NETOPIA processes the payment and notifies your server.

Security Measures

To ensure secure transactions, the API implements:

Request authentication via API Signature (Signature field).
Data encryption using RSA keys.
Secure transport via SSL/TLS (recommended for responses).

Payment Request Workflow

Process Overview:

Redirect the user to NETOPIA with a payment request.
NETOPIA processes the transaction and notifies your server.
Your system handles the IPN (Instant Payment Notification).

Key Parameters:

env_key – Public key for encryption.
data – XML-structured payment details, signed with NETOPIA’s public certificate.
cipher – Encryption algorithm.
iv – Initialization vector for encryption security.

Service Endpoints

Payment Mode	Standard Payment	One-Click Payment
Live	https://secure.mobilpay.ro	https://secure.mobilpay.ro/card4
Test	https://sandboxsecure.mobilpay.ro	https://sandboxsecure.mobilpay.ro/card4

For language-specific interfaces, append the language code (e.g., /en for English).

Payment Request Structure

XML Format

<?xml version="1.0" encoding="utf-8"?>
<order type="card" id="ORDER_ID" timestamp="YYYYMMDDHHMMSS">
    <signature>XXXX-XXXX-XXXX-XXXX</signature>
    <invoice currency="RON" amount="XX.YY">
        <details>Payment Description</details>
        <contact_info>
            <billing type="company|person">
                <first_name>John</first_name>
                <last_name>Doe</last_name>
                <email>john.doe@example.com</email>
                <mobile_phone>+40712345678</mobile_phone>
                <address>123 Main St, Bucharest</address>
            </billing>
        </contact_info>
    </invoice>
    <ipn_cipher>aes-256-cbc</ipn_cipher>
    <params>
        <param>
            <name>custom_param</name>
            <value>value123</value>
        </param>
    </params>
    <url>
        <confirm>https://yourdomain.com/confirm</confirm>
        <return>https://yourdomain.com/return</return>
    </url>
</order>

Request Parameters

Parameter	Description	Format / Constraints	Notes
`order type`	Specifies the type of transaction to be initiated.	Accepted value: `card`	-
`order id`	Internal identifier for your order.	Max 64 characters, unique per seller account.	Refresh on each request unless duplicate is intended.
`timestamp`	The timestamp from your server.	Format: `YYYYMMDDhhmmss`	Example: `20240425020304` (April 25, 2024, 02:03:04)
`signature`	The unique key for your seller account.	Format: `XXXX-XXXX-XXXX-XXXX`	Obtainable from NETOPIA's merchant console.
`invoice`	Contains the payment details to be initiated.	-	-
`currency`	Currency for processing the payment.	ISO Code (e.g., `RON`)	Other currencies (EUR, USD, GBP) may be used if authorized; otherwise, converted to `RON` with dual display.
`amount`	The amount to be processed.	Max: `99999` units	Card checks may use an amount of `0`.
`installments` (optional)	Number of installments available.	Type: Integer	Must be preconfigured by a NETOPIA representative.
`selected_installments` (optional)	The number of installments selected by the client.	Type: Integer	Must be within the `installments` range.
`customer_id`	Internal identifier of your customer.	Unique ID	Useful for one-click payments.
`token_id`	Token received from an initial payment request.	-	Identifies the customer and payment instrument.
`pan_masked`	First 6 and last 4 digits of the associated credit card.	Masked Card Number	Displays a user-friendly version of the card.
`details`	Payment details as displayed on the NETOPIA secure payment page.	Alphanumeric	-
`cipher`	Algorithm/method for data encryption or decryption.	Options: `rc4`, `aes-256-cbc`	-
`contact_info`	Payer information for a smoother payment experience.	-	Eliminates the need for a secondary step to collect customer details.
`billing_type`	Customer type.	Values: `person`, `company`	-
`first_name`	Customer's first name.	String	-
`last_name`	Customer's last name.	String	-
`email`	Customer's email address.	Valid email format	-
`mobile_phone`	Customer's phone number.	Numeric	-
`address`	Customer's address.	String	-
`params`	An array of custom parameters.	-	Provides additional details about the payer and/or
`url`	The URL where NETOPIA sends the payment result.	Valid URL	-
`confirm`	Your web application's URL called on payment status changes or manual IPNs.	Must be publicly accessible	Must support HTTP (port 80) or HTTPS (port 443). First call is synchronous; subsequent calls are asynchronous.
`return`	URL to which the client is redirected after payment completion.	Valid URL	Not to be confused with success or cancel URLs. Content is dynamic based on data sent to the `confirm` URL.

Payment Response Structure

Upon every change in the status of a payment, NETOPIA will make a POST request to the URL set as the confirmation endpoint, with the Content-Type: application/x-www-form-urlencoded. The request will contain the following parameters: env_key, data, cipher, and optionally, iv. The response XML will be encrypted using an X509 public certificate, and you must decrypt it using the private key provided by NETOPIA (or your own).

You will receive all the parameters you initially sent, unchanged, along with an additional element, called mobilpay, in the response XML.

XML Format

<?xml version="1.0" encoding="utf-8"?>
<order type="card" id="ORDER_ID" timestamp="YYYYMMDDHHMMSS">
    <mobilpay timestamp="YYYYMMDDHHMMSS" crc="XXXXX">
        <action>action_type</action>
        <customer type="person|company">
            <first_name>John</first_name>
            <last_name>Doe</last_name>
            <address>123 Main St, Bucharest</address>
            <email>john.doe@example.com</email>
            <mobile_phone>+40712345678</mobile_phone>
        </customer>
        <purchase>mobilPay_purchase_no</purchase>
        <original_amount>XX.XX</original_amount>
        <processed_amount>NN.NN</processed_amount>
        <pan_masked>XXXXXX****YYYY</pan_masked>
        <payment_instrument_id>ZZZZZZZ</payment_instrument_id>
        <token_id>token_identifier</token_id>
        <token_expiration_date>YYYY-MM-DD HH:MM:SS</token_expiration_date>
        <error code="N">error_message</error>
    </mobilpay>
</order>

Response Parameters

Parameter	Description	Format / Constraints	Notes
`mobilpay`	NETOPIA's response, appended to your unchanged request.	-	-
`timestamp`	NETOPIA's internal timestamp.	Format: `YYYYMMDDHHMMSS`	-
`crc`	NETOPIA internal identifier check.	Alphanumeric	-
`action`	The action attempted by NETOPIA.	Values: `paid_pending`, `confirmed_pending`, `paid`, `confirmed`, `credit`, `canceled`	This is not the transaction status, as all actions can succeed or fail.
`customer type`	The type of paying customer.	Values: `person`, `company`	-
`first_name`	The customer's first name.	String	-
`last_name`	The customer's last name.	String	-
`address`	The customer's address.	String	-
`email`	The customer's email address.	Valid email format	-
`mobile_phone`	The customer's phone number.	Numeric	-
`purchase`	NETOPIA internal identifier.	Unique ID	Unique for the entire NETOPIA platform.
`original_amount`	The original amount processed.	Decimal	-
`processed_amount`	The processed amount at the moment of response.	Decimal	Can be lower than the original amount in case of partial capture or refund.
`pan_masked`	First 6 and last 4 digits of the card used.	Masked Card Number	Store and use for customer-friendly payment instrument identification.
`payment_instrument_id`	Internal NETOPIA identifier of the payment instrument.	Alphanumeric	Helps check uniqueness.
`token_id`	Token associated with the payment instrument.	Alphanumeric	Used for recurring payments or one-click payments.
`token_expiration_date`	Expiration date of the token.	Format: `YYYY-MM-DD HH:MM:SS`	Usually the expiration date of the card.
`error code`	Indicates whether the action was successful.	0 (Success) or other numeric values	A value of `0` means success, any other value indicates failure.
`error message`	Descriptive error message.	String	Can be displayed to the user for better understanding.

Merchant's Response

For each call to your confirmation URL, you must send a response in XML format back to NETOPIA, indicating whether you have successfully recorded the response. This response is crucial for NETOPIA to determine whether to retry sending the IPN.

If you encounter an error, you should specify an error code and message. You can check your response in the NETOPIA Platform under Orders > Card, selecting Any status and identifying the transaction.

XML Response Format

<?xml version="1.0" encoding="utf-8"?>
<crc error_type="1|2" error_code="numeric">message</crc>

Response Attributes

Attribute	Description	Format / Constraints	Notes
`error_type`	Determines if NETOPIA will retry sending the IPN.	`1` (Temporary Error), `2` (Permanent Error)	Set to `1` for temporary issues, `2` for permanent failures.
`error_code`	Your internal error code.	Numeric	Helps diagnose issues on your system.
`message`	Your error message.	String	If no error, return the received `crc` value or an appropriate success message.

This structured response ensures smooth communication with NETOPIA and prevents unnecessary retries of failed IPNs.

Error Codes

Code	Meaning
`0`	Approved
`16`	Stolen card
`17`	Incorrect card number
`18`	Closed card
`19`	Expired card
`20`	Insufficient funds
`21`	CVV2 incorrect
`22`	Issuer unavailable
`32`	Incorrect amount
`33`	Incorrect currency
`34`	Transaction not permitted
`35`	Transaction declined
`36`	Rejected by antifraud
`37`	Declined (legal restrictions)
`38`	Requires 3D Authentication
`48`	Invalid request
`49`	Duplicate PREAUTH
`50`	Duplicate AUTH
`51`	Can only CANCEL preauth
`52`	Can only CONFIRM preauth
`53`	Can only CREDIT confirmed order
`54`	Credit amount exceeds auth amount
`55`	Capture amount exceeds preauth
`56`	Duplicate request
`99`	Generic error

Overview​

Introduction​

Feedback​

Architecture​

Client-Server Model​

Security Measures​

Payment Request Workflow​

Service Endpoints​

Payment Request Structure​

XML Format​

Request Parameters​

Payment Response Structure​

XML Format​

Response Parameters​

Merchant's Response​

XML Response Format​

Response Attributes​

Error Codes​

Overview

Introduction

Feedback

Architecture

Client-Server Model

Security Measures

Payment Request Workflow

Service Endpoints

Payment Request Structure

XML Format

Request Parameters

Payment Response Structure

XML Format

Response Parameters

Merchant's Response

XML Response Format

Response Attributes

Error Codes