openapi: 3.0.0 info: license: name: "Proprietary" url: "https://netopia-payments.com" title: NETOPIA Payments - merchant API description: "---\nsidebar_position: 1\n---\n\n# Introduction\n\nThe **Payments API** was designed and implemented by NETOPIA Payments development team and is meant to be used in third party applications to cover the payment process.\n\n## Why NETOPIA Payments API\n- Fast and Secure\n- Full support for 3-D Secure authentication\n- Easy to integrate with any third party application \n- Stellar support\n\n## Prerequisites\n\nYou should have a merchant account with NETOPIA. If you dont yet have one, start by **[creating it](https://netopia-payments.com/register/)**.\n\n\n### NETOPIA Payments administration platform\nLogin with your username/password to **[administration console](https://admin.netopia-payments.com/)**. From here you'll be able to configure your account, monitor incoming transactions, add users, etc.\n\nNETOPIA gives you the possibility to test the payment process during or after the implemention of your application too by providing a sandbox environment which mirrors the features of production. It can be accessed directly from your production account or by logging in to **[sandbox](https://sandbox.netopia-payments.com)**.\n\n\n### API KEY\nIn order to communicate with the payment API, you need a specific **API KEY** that you can generate from **[NETOPIA Payments admin](https://admin.netopia-payments.com/)** -> Profile -> Security\n\n**Note:** \n- You should always pass the API KEY in the **HTTP Headers** of your request \n- You can regenerate/remove/add a new API Key at any time\n- Sandbox keys are not working on Live, or viceversa\n\n\nOnce you have an **_ACTIVE ACCOUNT_** and an **_API KEY_**, you are ready to [start](b3A6NDEzMjI0MTk-card-start) actual payments via **NETOPIA Payments' API**" version: 1.0.0 contact: name: "NETOPIA Payments Support" url: "https://netopia-payments.com/support" email: "support@netopia-payments.com" security: [] servers: - url: https://secure.sandbox.netopia-payments.com description: sandbox - url: https://secure.mobilpay.ro/pay description: live tags: - name: SystemService description: spec,healz - name: PaymentService description: init payment, pay an order, verify authentication - name: OperationService description: additional payment actions - name: SandboxService description: 'notify sample ' paths: /spec: get: tags: - SystemService description: Netopia merchant API specs operationId: spec responses: "200": description: The request was processed correctly by the server content: application/json: schema: type: string format: binary examples: {} /healz: get: tags: - SystemService description: return ok if no circuit breaker is active operationId: healz responses: "200": description: The request was processed correctly by the server content: text/plain: schema: type: string "501": $ref: '#/components/responses/501Error' summary: "" x-internal: true /sandbox/notify: post: tags: - SandboxService description: This is a sample of the request being sent to your callback URL once a payment is completed operationId: notifySample requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotifyRequest' examples: sample callback request: value: payment: method: card ntpID: "866991" status: 0 amount: 0.1 currency: RON token: "" data: property1: value1 property2: value2 order: orderID: 573f79de-57de-4be7-9784-bf4280489819 data: property1: value1 property2: value2 responses: "200": $ref: '#/components/responses/OK' "501": $ref: '#/components/responses/501Error' x-internal: true /sandbox/authorize: post: tags: - SandboxService description: simulation of a 3-D Secure authentication in sandbox operationId: sandboxAuthorize requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DemoAuthorize' responses: "200": $ref: '#/components/responses/Auth' /payment/card/start: post: tags: - PaymentService description: Use this endpoint to start a payment. Based on the response to this call the process either stops or you need to continue with [verify_auth](b3A6NDEzMjI0MjA-card-auth) operationId: cardStart security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartRequest' examples: no 3-D Secure payment: value: config: emailTemplate: "" emailSubject: "" notifyUrl: https://www.my.domain/my_notify_url redirectUrl: https://www.my.domain/my_redirect_url language: ro payment: options: installments: 0 bonus: 0 instrument: type: card account: "9900004810225098" expMonth: 12 expYear: 2022 secretCode: "111" token: "" data: property1: string property2: string order: ntpID: "" posSignature: XXXX-XXXX-XXXX-XXXX-XXXX dateTime: "2023-03-19T10:48:17+02:00" description: Some order description orderID: Merchant order Id amount: 1 currency: RON billing: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 countryName: Country state: State postalCode: Zip details: "" shipping: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 state: State postalCode: Zip details: "" products: - name: name code: SKU category: category price: 1 vat: 19 installments: selected: 0 available: - 0 data: property1: string property2: string 3-D Secure payment: value: config: emailTemplate: "" emailSubject: "" notifyUrl: https://www.my.domain/my_notify_url redirectUrl: https://www.my.domain/my_redirect_url language: ro payment: options: installments: 0 bonus: 0 instrument: type: card account: "9900009184214768" expMonth: 12 expYear: 2022 secretCode: "111" token: "" data: BROWSER_USER_AGENT: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36 BROWSER_TZ: Europe/Bucharest BROWSER_COLOR_DEPTH: "32" BROWSER_JAVA_ENABLED: "true" BROWSER_LANGUAGE: en-US,en;q=0.9 BROWSER_TZ_OFFSET: "0" BROWSER_SCREEN_WIDTH: "1200" BROWSER_SCREEN_HEIGHT: "1400" BROWSER_PLUGINS: Chrome PDF Plugin, Chrome PDF Viewer, Native Client MOBILE: "false" SCREEN_POINT: "false" OS: macOS OS_VERSION: 10.15.7 (32-bit) IP_ADDRESS: 127.0.0.1 order: ntpID: "" posSignature: XXXX-XXXX-XXXX-XXXX-XXXX dateTime: "2023-08-24T14:15:22Z" description: Some order description orderID: Merchant order Id amount: 1 currency: RON billing: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 countryName: Romania state: State postalCode: Zip details: "" shipping: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 state: State postalCode: Zip details: "" products: - name: string code: SKU category: category price: 1 vat: 19 installments: selected: 0 available: - 0 data: property1: string property2: string description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/StartResponse' examples: example-1: value: payment: method: string ntpID: string status: 0 amount: 10 currency: string paymentURL: string token: string data: property1: string property2: string customerAction: type: string url: http://ACS.url authenticationToken: string formData: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string parameters: [] /payment/bnpl/return: post: tags: - PaymentService description: bnpl return operationId: bnplReturn security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OperationVoidRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' /payment/bnpl/start: post: tags: - PaymentService description: Use this endpoint to start a payment. Based on the response to this call the process either stops or you need to continue with [verify_auth](b3A6NDEzMjI0MjA-card-auth) operationId: bnplStart security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartRequest' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/StartResponse' examples: example-1: value: payment: method: string ntpID: string status: 0 amount: 10 currency: string paymentURL: string token: string data: property1: string property2: string customerAction: type: string url: http://ACS.url authenticationToken: string formData: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string parameters: [] /payment/ropay/start: post: tags: - PaymentService description: Use this endpoint to start an account-to-account RoPay payment. The response contains the payment link (mobile deeplink) and the QR code image (desktop); the payment is finalized asynchronously via status polling. operationId: ropayStart security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartRequest' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/StartResponse' examples: example-1: value: payment: method: string ntpID: string status: 15 amount: 10 currency: RON customerAction: type: RopayApp url: https://qr.ropay.ro/1/p/ROP/BInHPuoJ qrCode: format: png dataUrl: data:image/png;base64,iVBORw0KGgoAAAANS... expiresAt: 2026-07-09T16:35:39+03:00 error: code: "00" message: Approved parameters: [] /payment/applepay/merchant-check: post: tags: - PaymentService description: Use this endpoint to start a payment. Based on the response to this call the process either stops or you need to continue with [applepay/finish] operationId: applePayMerchantCheck security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MerchantCheck' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/MerchantCheckResponse' parameters: [] /payment/ropay/cancel: post: tags: - PaymentService description: Cancels the customer's pending RoPay payment intent at ING and releases the order lock so another payment method can be used immediately; the attempt itself is finalized asynchronously by the status consumer operationId: ropayCancel security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExpireRequest' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' parameters: [] /payment/ropay/participants: get: tags: - PaymentService description: Lists the RoPay scheme banks able to pay through the deeplink flow, for the payment page bank picker operationId: ropayParticipants security: - ApiKeyAuth: [] responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/RopayParticipantsResponse' "400": $ref: '#/components/responses/400Error' parameters: [] /payment/card/verify-auth: post: tags: - PaymentService description: authorize a 3-D Secure authenticated payment operationId: cardAuth security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerifyAuthRequest' examples: GB sample request: value: authenticationToken: wimjvWp-3gFaBt8FysbGevuc ntpID: "198669910" formData: xid: 4PEbaJMvPx0h mdstatus: "1" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/VerifyAuthResponse' summary: "" /payment/cardpresent/sale: post: tags: - PaymentService description: Use this endpoint to process a complete card present (in-person) payment sale. This endpoint handles payments where the card is physically present at the point of sale, with different processing requirements than card-not-present transactions. The payment is authorized and captured in a single step. operationId: cardPresentSale security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardPresentOperationRequest' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/StartResponse' examples: example-1: value: payment: method: cardPresent ntpID: "12345" status: 3 amount: 0.40 currency: "RON" operationDate: "2025-09-02T14:50:54Z" data: status: "accepted" transaction_id: "txn_xyz789" purchase_id: "12345" error: code: "00" message: "Approved" "400": $ref: '#/components/responses/400Error' "401": $ref: '#/components/responses/401Error' "500": $ref: '#/components/responses/500Error' "501": $ref: '#/components/responses/501Error' summary: "" /operation/capture: post: tags: - OperationService description: capture existing order - _will be available at a future date_ operationId: capture security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OperationRequest' description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' /operation/void: post: tags: - OperationService description: credit existing order - _will be available at a future date_ operationId: void security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OperationVoidRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' /operation/credit: post: tags: - OperationService description: credit existing order - _will be available at a future date_ operationId: credit security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OperationRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' /operation/fail: post: tags: - OperationService description: credit existing order - _will be available at a future date_ operationId: fail security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OperationVoidRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/OperationResponse' "400": $ref: '#/components/responses/400Error' /operation/payment-options: post: tags: - OperationService description: get bonus points, installments - _will be available at a future date_ operationId: paymentOptions security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentOptionRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/PaymentOptionResponse' "400": $ref: '#/components/responses/400Error' /operation/expire: post: tags: - OperationService description: expire existing order - _will be available at a future date_ operationId: expire security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExpireRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/ExpireResponse' "400": $ref: '#/components/responses/400Error' /operation/status: post: tags: - OperationService description: get order payment status - _will be available at a future date_ operationId: status security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExpireRequest' responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": $ref: '#/components/responses/400Error' /disbursement/card/auth: post: tags: - PaymentService description: Use this endpoint to authorize a card disbursement. operationId: disbursementCardAuth security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DisbursementCardAuthRequest' examples: card disbursement: value: config: emailTemplate: "" emailSubject: "" notifyUrl: https://www.my.domain/my_notify_url language: ro payment: instrument: type: card account: "9900004810225098" token: "" data: property1: string property2: string order: posSignature: XXXX-XXXX-XXXX-XXXX-XXXX dateTime: "2023-03-19T10:48:17+02:00" description: Some order description orderID: Merchant order Id amount: 1 currency: RON billing: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 countryName: Country state: State postalCode: Zip details: "" shipping: email: user@example.com phone: +407xxxxxxxx firstName: First lastName: Last city: City country: 642 state: State postalCode: Zip details: "" products: - name: name code: SKU category: category price: 1 vat: 19 data: property1: string property2: string description: "" responses: "200": description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/DisbursementCardAuthResponse' examples: example-1: value: payment: method: string ntpID: string status: 0 amount: 10 currency: string paymentURL: string data: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string parameters: [] components: links: {} callbacks: {} schemas: DemoAuthorize: type: object properties: paReq: type: string minLength: 5 description: payment authentication request - _you received this in the response to your start request_ backUrl: type: string minLength: 5 description: a URL on the merchant side where you want the 3-D Secure authentication response to be sent NotifyRequest: type: object properties: payment: $ref: '#/components/schemas/PaymentNotify' order: $ref: '#/components/schemas/OrderNotify' OrderNotify: type: object properties: orderID: type: string data: allOf: - $ref: '#/components/schemas/Attributes' - description: Specific Order Notify Information format: Attributes PaymentNotify: type: object x-examples: successful card payment: method: card ntpID: "99003322" status: 5 amount: 100 currency: RON token: eE10aklrbGxPRE05 data: property1: value1 property2: value2 properties: method: type: string description: payment method (card, crypto, sms, token) ntpID: type: string description: internal NETOPIA id status: type: integer description: |- payment status - 5 = confirmed - 3 = paid - 12 = invalid account example: 5 amount: type: number format: float64 minimum: 0 exclusiveMinimum: true description: amount in decimal units, i.e. 1234 = 12.34 currency: type: string description: Use ISO 4217 alpha codes example: RON instrument: $ref: '#/components/schemas/PaymentInstrumentNotify' token: type: string binding: $ref: '#/components/schemas/PaymentBinding' code: type: string message: type: string data: allOf: - $ref: '#/components/schemas/Attributes' - description: Specific Notify Data Information format: Attributes PaymentInstrumentNotify: type: object properties: panMasked: type: string panCategory: type: string issuer: type: string country: type: integer PaymentBinding: type: object properties: token: type: string expireMonth: type: integer expireYear: type: integer DisbursementNotify: type: object x-examples: successful card payment: method: card ntpID: "99003322" status: 5 amount: -100 currency: RON token: eE10aklrbGxPRE05 properties: method: type: string enum: - card - token description: payment method (card,token) ntpID: type: string description: internal NETOPIA id status: type: integer description: |- payment status - 5 = confirmed - 3 = paid - 12 = invalid account example: 5 amount: type: number format: float64 minimum: 0 exclusiveMinimum: true description: amount in decimal units, i.e. -1234 = -12.34 currency: type: string description: Use ISO 4217 alpha codes example: RON recipient: $ref: '#/components/schemas/DisbursementRecipientNotify' token: type: string code: type: string message: type: string DisbursementNotifyRequest: type: object properties: disbursement: $ref: '#/components/schemas/DisbursementNotify' order: $ref: '#/components/schemas/OrderNotify' OperationVoidRequest: type: object properties: ntpID: type: string minLength: 5 maxLength: 64 OperationRequest: type: object description: total amount = merchant specific amount + TOTAL destinations amount properties: ntpID: type: string minLength: 5 maxLength: 64 amount: description: merchant specific amount type: number format: float64 minimum: 0 exclusiveMinimum: true split: description: destinations details type: array items: $ref: '#/components/schemas/PaymentSplitDestination' OperationResponse: type: object properties: payment: $ref: '#/components/schemas/Payment' error: $ref: '#/components/schemas/ErrorWithDetails' RopayBank: type: object description: One bank able to complete a RoPay payment (payment page picker entry) properties: bic: type: string name: type: string RopayParticipantsResponse: type: object description: Banks able to pay through the RoPay deeplink flow properties: banks: type: array items: $ref: '#/components/schemas/RopayBank' StartRequest: type: object properties: config: $ref: '#/components/schemas/Config' payment: $ref: '#/components/schemas/PaymentRequest' order: $ref: '#/components/schemas/Order' description: "" StartResponse: type: object properties: payment: $ref: '#/components/schemas/Payment' customerAction: $ref: '#/components/schemas/Action' error: $ref: '#/components/schemas/ErrorWithDetails' description: "" x-examples: non 3-D Secure payment: payment: method: string ntpID: string status: 0 amount: 0 currency: string paymentURL: string token: string data: property1: string property2: string customerAction: type: string url: string authenticationToken: string formData: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string '3-D Secure payment ': payment: method: string ntpID: string status: 0 amount: 0 currency: string paymentURL: string token: string data: property1: string property2: string customerAction: type: string url: string authenticationToken: string formData: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string title: "" Config: type: object description: General notification settings properties: emailTemplate: type: string description: Required only for custom notification emails; will be shared by NETOPIA emailSubject: type: string format: standardInput description: Notification e-mail subject; mandatory if emailTemplate is present example: Payment confirmation for www.my.domain cancelUrl: type: string format: url notifyUrl: type: string format: url description: A URL on the merchant side where NETOPIA will send payment result notifications example: https://www.my.domain/my_notify_url redirectUrl: type: string format: url description: A URL on the merchant side where the 3-D Secure authentication response will be sent example: https://www.my.domain/my_3dreturn_url language: type: string minLength: 2 maxLength: 2 format: standardInput example: en description: Language you want notifications to be displayed in; use ISO 639-1 codes required: - notifyUrl - redirectUrl - language PaymentRequest: type: object x-examples: card request with client data: options: installments: 0 bonus: 0 instrument: type: card account: "9900002922742471" expMonth: 1 expYear: 2025 secretCode: "111" token: "" data: BROWSER_USER_AGENT: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36 BROWSER_TZ: Europe/Bucharest BROWSER_COLOR_DEPTH: "32" BROWSER_JAVA_ENABLED: "true" BROWSER_LANGUAGE: en-US,en;q=0.9 BROWSER_TZ_OFFSET: "0" BROWSER_SCREEN_WIDTH: "1200" BROWSER_SCREEN_HEIGHT: "1400" BROWSER_PLUGINS: Chrome PDF Plugin, Chrome PDF Viewer, Native Client MOBILE: "false" SCREEN_POINT: "false" OS: macOS OS_VERSION: 10.15.7 (32-bit) IP_ADDRESS: 193.224.10.10 description: General payment information x-internal: false properties: options: $ref: '#/components/schemas/PaymentOptions' instrument: $ref: '#/components/schemas/PaymentInstrument' data: allOf: - $ref: '#/components/schemas/Attributes' - description: Payment specific information, i.e. customer browser and device data format: Attributes PaymentOptions: type: object description: Payment options information properties: installments: type: integer description: Set the installments number you want the client to pay in bonus: type: integer description: Set the loyalty points number you want the client to use split: type: array description: Split payments - will be available in future versions items: $ref: '#/components/schemas/PaymentSplitDestination' x-examples: payment request in 6 installments and 100 loyalty points: installments: 6 bonus: 100 PaymentSplitDestination: type: object description: Future feature properties: posID: type: integer description: destination POS amount: type: number minimum: 0 description: amount to be disbursed; should always be smaller than order:amount description: type: string nullable: true description: set a specific description for created split payment PaymentInstrument: type: object description: Payment instrument information x-examples: Card payments: type: card account: "9900004810225098" expMonth: 1 expYear: 2030 secretCode: "111" Token payments: token: eE10aklrbGxPRE05 properties: type: type: string description: mandatory for all payment methods except token account: type: string description: |- mandatory for all payment methods except token - **card number** when type is **card** expMonth: type: integer description: expiration month - *mandatory* if type is **card** expYear: type: integer description: expiration year - *mandatory* if type is **card** secretCode: type: string description: for card payments - _CVV/CVC_ - card security code maxLength: 4 token: type: string description: if present, token overrides all other data Action: type: object description: This is the action you need to start in order to get additional information on the client side (i.e. 3-D Secure authentication) x-examples: example-1: type: Authentication3D url: https://sanalposprov.garantibank.ro/servlet/gt3dengine authenticationToken: string formData: secure3dhash: 4D9EAAF9FE6CFE2A secure3dsecuritylevel: 3D txnamount: "10" txncurrencycode: "946" txninstallmentcount: "" txnmotoind: "N" txntype: sales version: v0.00 properties: type: type: string description: type of action to be taken example: Authentication3D url: type: string format: url description: this is the URL where you need to POST your form's action fallbackUrl: type: string format: url description: in case URL will not open use this attribute to find out where you shoud redirect the customer for payment completion returnUrl: type: string format: url description: the URL where the customer will be redirected after completing the action authenticationToken: type: string description: an authentication token for the specific action; you need to store this for future operations formData: allOf: - $ref: '#/components/schemas/Attributes' - description: 3-D Secure specific data you need to send in your form; all received data is mandatory and should not be stored or altered format: Attributes qrCode: $ref: '#/components/schemas/QrCode' expiresAt: type: string description: the moment when the payment intent expires (RoPay); after this the customer action can no longer be completed example: 2026-07-09T16:35:39+03:00 QrCode: type: object description: QR code image the customer scans with the banking application (RoPay account-to-account payments); the dataUrl goes directly into an img src attribute properties: format: type: string description: image format of the QR code example: png dataUrl: type: string description: base64 encoded data URL of the QR code image example: data:image/png;base64,iVBORw0KGgoAAAANS... Attributes: type: object description: |2- Object with dynamic attributes. { name_1:value_1, name_2:value_2 } additionalProperties: description: custom desc type: string x-examples: Card payment required payment data: BROWSER_USER_AGENT: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36 BROWSER_TZ: Europe/Bucharest BROWSER_COLOR_DEPTH: "32" BROWSER_JAVA_ENABLED: "true" BROWSER_LANGUAGE: en-US,en;q=0.9 BROWSER_TZ_OFFSET: "0" BROWSER_SCREEN_WIDTH: "1200" BROWSER_SCREEN_HEIGHT: "1400" BROWSER_PLUGINS: Chrome PDF Plugin, Chrome PDF Viewer, Native Client MOBILE: "false" SCREEN_POINT: "false" OS: macOS OS_VERSION: 10.15.7 (32-bit) IP_ADDRESS: 127.0.0.1 Other Payment method: my_custom_param_name_1: my_custom_param_value_1 my_custom_param_name_2: my_custom_param_value_2 properties: {} title: Atributes CardPresentOperationRequest: type: object description: Request schema for card present payment notifications received from the POS terminal. Aligned with the integrator guide — field names follow the PRD and DB convention (cardMask, approvalCode, etc.), with provider-specific fields scoped to cardPresent. Refunds are not exposed; they are reconciled out-of-band through the provider. properties: transactionId: type: string description: "Integrator-generated unique transaction id; used as the idempotency key (together with posSignature). Echoed back in the response as data.transaction_id. NOTE: this is NOT a NETOPIA id — the internal purchase id is returned as payment.ntpID / data.purchase_id." minLength: 1 maxLength: 64 amount: type: number format: float64 minimum: 0 exclusiveMinimum: true description: Transaction amount (decimal, e.g. 100.50) currency: type: string description: Currency code (ISO 4217). Optional — when omitted, the currency configured on the gateway (PGWCPS.CURRENCY) is used. posSignature: type: string description: Merchant POS identifier, available in the NETOPIA account minLength: 1 maxLength: 64 orderDescription: type: string description: Free-form description of the transaction maxLength: 255 installments: type: integer description: Number of installments. Optional — defaults to 1 (full payment) when omitted. default: 1 transactionTimestamp: type: string format: date-time description: ISO 8601 datetime of the transaction at the POS terminal. Optional — defaults to the server receive time when omitted. cardPresent: $ref: '#/components/schemas/CardPresentOptions' required: - transactionId - amount - posSignature - cardPresent x-examples: Symphopay sale: transactionId: "txn_xyz789" amount: 0.40 posSignature: "TEST001" installments: 1 transactionTimestamp: "2025-09-02T14:50:54Z" cardPresent: provider: "symphopay" transactionUniqId: "hjgjhguj" transactionFlags: 2 cardholderName: "testHName" terminalData: terminalId: "testMid" merchantId: "testMid" batchId: "000070" receiptNumber: "000067" hostResponseData: approvalCode: "902661" cardMask: "**9866" hostResponseCode: "00" hostResponseMessage: "TRANZACTIE ACCEPTATA" aid: "A0000000031010" applicationLabel: "VISA" reconciliationData: rrn: "999999984548" CardPresentOptions: type: object description: Card present transaction data. The provider field selects which gateway-resolution stored procedure the API uses (sp_pgwcpsSelectPgwByMerchantIdTerminalId for Symphopay; future providers each get their own procedure returning the same PGW_PAYMENT_GATEWAY result set). Generic field names (cardMask, approvalCode, ...) follow the PRD and the PRCCP DB schema; integrators map provider-specific payloads into this contract. properties: provider: type: string description: POS gateway provider that authorized the transaction. enum: - symphopay transactionUniqId: type: string description: Unique transaction id at the POS — primary correlation key with the provider. Persisted to PRCCP_TR_ID (VARCHAR(32)); values longer than 32 are rejected rather than truncated. minLength: 1 maxLength: 32 transactionFlags: type: integer description: Provider-specific transaction flags (bitmask). Accepted but not persisted in Phase 1. cardholderName: type: string description: Cardholder name (anonymized after settlement). terminalData: $ref: '#/components/schemas/TerminalData' hostResponseData: $ref: '#/components/schemas/HostResponseData' reconciliationData: $ref: '#/components/schemas/ReconciliationData' attributes: $ref: '#/components/schemas/Attributes' description: Free-form bag of fields the POS supplied but the schema does not map explicitly (stan, cashbackLimitAmount, totals, voucher data, etc.). Stored as-is in PRCCP.ATTRIBUTES. required: - provider - transactionUniqId - terminalData - hostResponseData TerminalData: type: object description: POS terminal identifiers registered with the provider. properties: terminalId: type: string description: POS terminal identifier (e.g. PGWCPS.TERMINAL_ID for Symphopay). minLength: 1 maxLength: 32 merchantId: type: string description: Provider-side merchant identifier (e.g. PGWCPS.MERCHANT_ID for Symphopay). minLength: 1 maxLength: 32 batchId: type: string description: POS batch identifier for reconciliation (provider-side). receiptNumber: type: string description: POS receipt number (provider-side). required: - terminalId - merchantId HostResponseData: type: object description: Issuer/processor response data for the card present transaction. properties: approvalCode: type: string description: Authorization code from the issuer. Persisted to PRCCP_AUTH_CODE (VARCHAR(8)); values longer than 8 are rejected rather than truncated. minLength: 1 maxLength: 8 cardMask: type: string description: Masked card number (e.g. 411111****1111 or **1234). minLength: 4 maxLength: 19 hostResponseCode: type: string description: Processor host response code (00=approved). Persisted to PRCCP_HOST_RESPONSE_CODE (VARCHAR(10)); values longer than 10 are rejected rather than truncated. minLength: 1 maxLength: 10 hostResponseMessage: type: string description: Processor host response message. entryMode: type: string description: Card entry mode at the POS. enum: - chip - contactless - magstripe - manual - fallback cardType: type: string description: Card brand (e.g. VISA, MASTERCARD, AMEX). aid: type: string description: EMV Application Identifier. maxLength: 32 applicationLabel: type: string description: EMV application label (e.g. VISA CREDIT). maxLength: 32 tvr: type: string description: EMV Terminal Verification Results. tsi: type: string description: EMV Transaction Status Information. required: - approvalCode - cardMask - entryMode ReconciliationData: type: object description: Data needed for end-of-day reconciliation. Settlement date is omitted intentionally — it is determined at reconciliation through the provider, not on the POS. properties: rrn: type: string description: Retrieval Reference Number. Payment: type: object x-examples: example-1: method: string ntpID: string status: 0 amount: 1 currency: string paymentURL: string token: string data: property1: string property2: string description: "" properties: method: type: string allowedMethods: type: array items: type: string ntpID: type: string description: NETOPIA internal id rrn: type: string status: type: integer description: |- payment status - 3 - _paid_ - 5 - _confirmed_ - 12 - _rejected_ - 15 - _3-D Secure authentication required_ amount: type: number format: float64 minimum: 0 exclusiveMinimum: true description: payment amount, will mirror the amount in your request currency: type: string description: payment currency in ISO 4217 alpha codes example: RON paymentURL: type: string description: payment link for the specific order token: type: string operationDate: type: string format: date-time options: $ref: '#/components/schemas/PaymentOptions' binding: $ref: '#/components/schemas/PaymentBinding' instrument: $ref: '#/components/schemas/PaymentInstrumentNotify' data: allOf: - $ref: '#/components/schemas/Attributes' - description: Specific Response Information format: Attributes BnplOptions: type: object properties: oney: $ref: '#/components/schemas/Oney' paypo: $ref: '#/components/schemas/PayPo' Oney: type: object properties: merchantUID: type: string paymentOptions: type: array items: $ref: '#/components/schemas/OneyOption' OneyOption: type: object properties: businessTransactionCode: type: string title: type: string instalments: type: integer PayPo: type: object properties: merchantUID: type: string paymentOptions: type: array items: $ref: '#/components/schemas/PayPoOption' PayPoOption: type: object properties: businessTransactionCode: type: string title: type: string instalments: type: integer CardOptions: type: object properties: clickpay: $ref: '#/components/schemas/ClickPay' ClickPay: type: object properties: srcDpaId: type: string acquirerMerchantId: type: string acquirerBin: type: string mcc: type: string Order: type: object description: Merchant and order related information x-go-pointer-fields: - event required: - posSignature - dateTime - description - orderID - amount - currency - billing properties: ntpID: type: string description: NETOPIA internal id - _obsolete_ posSignature: type: string maxLength: 64 description: merchant POS identifier, available in your NETOPIA account minLength: 0 dateTime: type: string format: date-time description: order registration date description: type: string description: order description orderID: type: string description: merchant internal order id amount: type: number format: float minimum: 0 description: amount to be paid - *set to 0 for account verification* currency: type: string minLength: 3 maxLength: 3 example: RON description: Use ISO 4217 alpha codes billing: $ref: '#/components/schemas/Address' shipping: $ref: '#/components/schemas/ShippingAddress' products: type: array items: $ref: '#/components/schemas/Product' installments: $ref: '#/components/schemas/Installments' data: allOf: - $ref: '#/components/schemas/Attributes' - description: Custom merchant parameteres related to the order format: Attributes clientID: type: string x-stoplight: id: wfyami2zhamwf scaExemptionInd: type: string x-stoplight: id: fr18hrobdf6mx event: $ref: '#/components/schemas/EventTypeFlight' EventTypeFlight: type: object x-go-pointer-fields: - airline required: - type - id - date - flight - departure - arrival properties: type: type: string enum: - flight id: type: string format: uuid minLength: 3 date: type: string format: date name: type: string nullable: true minLength: 3 maxLength: 64 description: type: string nullable: true maxLength: 1024 flight: $ref: "#/components/schemas/EventFlight" departure: $ref: "#/components/schemas/EventAirport" arrival: $ref: "#/components/schemas/EventAirport" airline: $ref: "#/components/schemas/EventAirline" EventFlight: type: object required: - iata properties: number: type: string nullable: true format: integer minLength: 1 maxLength: 4 iata: type: string minLength: 3 maxLength: 6 icao: type: string nullable: true minLength: 4 maxLength: 7 EventAirport: type: object required: - iata - scheduled properties: airport: type: string nullable: true minLength: 3 iata: type: string minLength: 3 maxLength: 3 icao: type: string nullable: true minLength: 4 scheduled: type: string format: date-time EventAirline: type: object required: - iata properties: name: type: string nullable: true minLength: 3 iata: type: string minLength: 2 maxLength: 2 icao: type: string nullable: true minLength: 3 Installments: type: object properties: selected: type: integer available: type: array items: type: integer description: Not used Product: type: object properties: name: type: string format: standardInfo code: type: string category: type: string price: type: number format: float vat: type: number format: float Address: type: object title: "" description: customer billing information properties: email: type: string format: email phone: type: string format: phone firstName: type: string format: standardInfo lastName: type: string format: standardInfo city: type: string format: standardInfo country: type: integer description: Use ISO 3166-1 numeric codes countryName: type: string format: standardInfo state: type: string format: standardInfo postalCode: type: string format: standardInfo details: type: string format: standardInfo description: Adress details, interphone required: - email - phone - firstName - lastName - city - country - countryName - state - postalCode - details x-examples: example-1: email: user@example.com phone: string firstName: string lastName: string city: string country: 0 countryName: string state: string postalCode: string details: string ShippingAddress: type: object description: customer shipping information properties: email: type: string format: email phone: type: string format: phone firstName: type: string format: standardinfo lastName: type: string format: standardinfo city: type: string format: standardinfo country: type: integer description: Use ISO 3166-1 numeric codes state: type: string format: standardinfo postalCode: type: string format: standardinfo details: type: string description: Adress details, interphone format: standardinfo VerifyAuthRequest: type: object properties: authenticationToken: type: string minLength: 0 maxLength: 255 description: the authentication token you received in your start response ntpID: type: string minLength: 1 maxLength: 64 description: NETOPIA internal id you received in your start response formData: allOf: - $ref: '#/components/schemas/Attributes' - description: 3-D Secure authentication response; all data received in your **redirectUrl** is mandatory and should not be altered format: Attributes VerifyAuthResponse: type: object properties: payment: $ref: '#/components/schemas/Payment' error: $ref: '#/components/schemas/ErrorWithDetails' ExpireRequest: type: object properties: posID: type: string ntpID: type: string orderID: type: string ExpireResponse: type: object properties: payment: $ref: '#/components/schemas/Payment' error: $ref: '#/components/schemas/ErrorWithDetails' PaymentOptionRequest: type: object properties: ntpID: type: string minLength: 5 maxLength: 64 instrument: $ref: '#/components/schemas/PaymentInstrument' PaymentOptionResponse: type: object properties: options: $ref: '#/components/schemas/Options' error: $ref: '#/components/schemas/ErrorWithDetails' Options: type: object properties: installments: type: array items: type: integer discount: type: number format: float64 bonus: type: integer issuer: type: string MerchantCheck: type: object properties: ntpID: type: string data: type: string MerchantCheckResponse: type: object properties: error: $ref: '#/components/schemas/ErrorWithDetails' payload: type: string StatusResponse: type: object properties: bnpl: $ref: '#/components/schemas/BnplOptions' card: $ref: '#/components/schemas/CardOptions' merchant: $ref: '#/components/schemas/Merchant' config: $ref: '#/components/schemas/Config' order: $ref: '#/components/schemas/Order' payment: $ref: '#/components/schemas/Payment' customerAction: $ref: '#/components/schemas/Action' error: $ref: '#/components/schemas/ErrorWithDetails' Merchant: type: object properties: merchantName: type: string posUrl: type: string posName: type: string posID: type: integer qrType: type: integer showCancel: type: boolean posType: type: integer DisbursementCardConfig: type: object description: General notification settings properties: emailTemplate: type: string description: Required only for custom notification emails; will be shared by NETOPIA emailSubject: type: string format: standardInput description: Notification e-mail subject; mandatory if emailTemplate is present example: Payment confirmation for www.my.domain notifyUrl: type: string format: url description: A URL on the merchant side where NETOPIA will send disbursement auth result notifications example: https://www.my.domain/my_notify_url language: type: string minLength: 2 maxLength: 2 format: standardInput example: en description: Language you want notifications to be displayed in; use ISO 639-1 codes required: - notifyUrl - language DisbursementCardRecipient: type: object x-examples: disburse to card via PAN: type: card account: "9900002922742471" expYear: 2026 expMonth: 1 disburse to card via token: type: token account: "xxxxx" description: Recipient disbursement information x-internal: false properties: type: type: string enum: - card - token description: mandatory account: type: string nullable: true description: |- mandatory for type=card - **card number** expYear: type: integer nullable: true minimum: 2026 description: |- mandatory for type=card - **expiry year** expMonth: type: integer nullable: true minimum: 1 maximum: 12 description: |- mandatory for type=card - **expiry month** token: type: string nullable: true description: |- mandatory for type=token - **token** received from NETOPIA Payments in response to a payment request with save card option oneOf: - required: - type - account - expYear - expMonth - required: - type - token DisbursementCardOrder: type: object description: Merchant and order related information required: - posSignature - dateTime - description - id - amount - currency - billing properties: posSignature: type: string maxLength: 64 description: merchant POS identifier, available in your NETOPIA account minLength: 0 dateTime: type: string format: date-time description: order registration date description: type: string description: order description id: type: string description: merchant internal order id amount: type: number format: float minimum: 0.01 description: amount to be disbursed currency: type: string minLength: 3 maxLength: 3 example: RON description: Use ISO 4217 alpha codes billing: $ref: '#/components/schemas/Address' data: allOf: - $ref: '#/components/schemas/Attributes' - description: Custom merchant parameteres related to the order format: Attributes DisbursementCardAuthRequest: type: object properties: config: $ref: '#/components/schemas/DisbursementCardConfig' recipient: $ref: '#/components/schemas/DisbursementCardRecipient' order: $ref: '#/components/schemas/DisbursementCardOrder' description: "" DisbursementRecipientNotify: type: object properties: panMasked: type: string panCategory: type: string issuer: type: string country: type: integer DisbursementCard: type: object x-examples: example-1: ntpID: string status: 0 amount: 1 currency: string data: property1: string property2: string description: "" properties: ntpID: type: string description: NETOPIA internal id rrn: type: string status: type: integer description: |- payment status - 3 - _paid_ - 5 - _confirmed_ - 12 - _rejected_ - 15 - _3-D Secure authentication required_ amount: type: number format: float64 minimum: 0 exclusiveMinimum: true description: payment amount, will mirror the amount in your request currency: type: string description: payment currency in ISO 4217 alpha codes example: RON operationDate: type: string format: date-time recipient: $ref: '#/components/schemas/DisbursementRecipientNotify' data: allOf: - $ref: '#/components/schemas/Attributes' - description: Specific Response Information format: Attributes DisbursementCardAuthResponse: type: object properties: disbursement: $ref: '#/components/schemas/DisbursementCard' error: $ref: '#/components/schemas/ErrorWithDetails' description: "" x-examples: card disbursement: disbursement: ntpID: string status: 0 amount: 0 currency: string data: property1: string property2: string error: code: string message: string details: - code: string message: string field: string attributes: property1: string property2: string title: "" Error: type: object properties: code: type: string minLength: 1 maxLength: 10 message: type: string minLength: 1 maxLength: 255 ErrorWithField: type: object properties: code: type: string minLength: 1 maxLength: 10 message: type: string minLength: 1 maxLength: 255 field: type: string minLength: 1 maxLength: 255 attributes: allOf: - $ref: '#/components/schemas/Attributes' - description: Error details Information format: Attributes description: "Error response with field-specific details and attributes" ErrorWithDetails: type: object description: | Start response error codes explained properties: code: type: string minLength: 1 maxLength: 10 description: |- - **1** - **2** - **3** - **100** - _Requires 3-D Secure authentication_ message: type: string minLength: 1 maxLength: 255 description: explanatory message for the associated error code details: type: array items: $ref: '#/components/schemas/ErrorWithField' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: Use this authorization key to sign your request. Keys are available in your NETOPIA account under Profile - Security. You can add as many keys as you like. responses: Auth: description: The request was processed correctly by the server content: text/html: schema: type: string OK: description: The request was processed correctly by the server content: application/json: schema: $ref: '#/components/schemas/Error' 400Error: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorWithDetails' 401Error: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' 500Error: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' 501Error: description: Internal servel error content: application/json: schema: $ref: '#/components/schemas/Error'