{ "openapi": "3.0.0", "info": { "license": { "name": "", "url": "" }, "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": {} }, "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", "returnUrl" : "https://ecclients.btrl.ro...", "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", "returnUrl" : "https://ecclients.btrl.ro...", "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/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": "applePayMechantCheck", "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/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": "" } }, "/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" } } } } }, "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\n- 5 = confirmed\n- 3 = paid\n- 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" } } }, "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" } } }, "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", "returnUrl" : "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", "returnUrl" : "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" } } }, "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\n- **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", "returnUrl": "https://ecclients.btrl.ro", "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" }, "returnUrl": { "type": "string", "format": "url", "description": "this is the URL that should be used as returnUrl for BTPay" }, "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" } ] } } }, "Attributes": { "type": "object", "description": "\nObject with dynamic attributes.\n\n{\n name_1:value_1,\n name_2:value_2\n}", "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" }, "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\n- 3 - _paid_\n- 5 - _confirmed_\n- 12 - _rejected_\n- 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" } } }, "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" } } }, "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" } } }, "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", "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" } } } }, "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" } } }, "Error": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "message": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "ErrorMaintenance": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 10 }, "message": { "type": "string", "minLength": 1, "maxLength": 255 }, "startDatetime": { "type": "string", "minLength": 1, "maxLength": 255 }, "endDatetime": { "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": "Eror details Information", "format": "Attributes" } ] } }, "description": "" }, "ErrorWithDetails": { "type": "object", "description": "Start response error codes explained\n", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 10, "description": "- **1**\n- **2**\n- **3**\n- **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" } } } }, "501Error": { "description": "Internal servel error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503Error": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMaintenance" } } } } } } }