Direct API Integration

For businesses that require full high level of control and flexibility, direct API allows you to build a customized payment experience while securely managing sensitive cardholder data.

Key Benefits & Features

REST-based architecture: Predictable, resource-oriented URLs for intuitive navigation.
JSON-first design: Raw JSON request bodies and responses keep development simple and modern.
Standardized implementation: Consistent use of HTTP verbs, authentication, and response codes.
Snake_case formatting: All fields across endpoints follow a unified naming style for clarity.
Comprehensive documentation: Includes endpoint lists, return codes, and test cards for immediate experimentation with different PSPs.
Use case examples: Ready-made request samples for recurring payments, 3DS, and more to help you speed up integration.
Safe testing environment: Sandbox mode lets you build and validate your flows without impacting live data or connecting to banking networks.

Compliance requirements:

Direct API integration requires the ability to securely handle card data and must meet PCI DSS compliance (SAQ D). This option is best for businesses with the infrastructure and certification to manage sensitive payment information and that want to design the payment journey end-to-end.

Our endpoints

Sandbox	Production	Description
api-sandbox.norbr.io/payment/checkout	api.norbr.io/payment/checkout	Used to create checkout
vault-sandbox.norbr.io/token	vault.norbr.io/token	Used for tokenization
api-sandbox.norbr.io/payment/order	api.norbr.io/payment/order	Used to create order
api-sandbox.norbr.io/payment/maintenance	api.norbr.io/payment/maintenance	Used to: capture an order, refund an order and void an authorization

Requests samples

You can use the sample requests below to quickly test and understand how the endpoints behave, including the typical required parameters and typical response format.

Create Checkout

curl --request POST \
     --url https://api-sandbox.norbr.io/payment/checkout \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: your_private_api_key' \
     --data '
{
  "operation_type": "direct_capture",
  "type": "api",
  "amount": 16,
  "currency": "USD",
  "order_merchant_id": "123445-1abc1-1111-2222-34a56bbb789ccc",
  "payment_channel": "e-commerce",
  "token_type": "oneshot",
  "accept_url": "https://www.google.com/search?q=accept",
  "decline_url": "https://www.google.com/search?q=decline",
  "cancel_url": "https://www.google.com/search?q=cancel",
  "pending_url": "https://www.google.com/search?q=pending",
  "exception_url": "https://www.google.com/search?q=exception",
  "payment_method_name": "visa",
  "customer_email": "[email protected]",
  "expiration_date": "Mon Oct 20 2025 08:31:09 GMT+0000 (Coordinated Universal Time)",
  "customer_first_name": "Kirby",
  "customer_last_name": "Nash"
}
'

{
      "result": {
        "code": "011111",
        "description": "checkout created successfully"
      },
        "checkout": {
        "token_type": "oneshot",
        "payment_method_name": "visa",
        "customer_first_name": "Kirby",
        "customer_browser_info_screen_height": 739,
        "type": "api",
        "customer_browser_info_color_depth": "24",
        "customer_browser_info_js_enabled": true,
        "merchant_data": [],
        "payment_channel": "e-commerce",
        "order_merchant_id": "123445-1abc1-1111-2222-34a56bbb789ccc",
        "checkout_id": "68f5efc96c14a9e4c82e49b8",
        "customer_browser_info_time_zone": "Europe/Paris",
        "customer_browser_info_screen_width": 428,
        "customer_browser_info_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_6_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/141.0.7390.96 Mobile/15E148 Safari/604.1",
        "operation_type": "direct_capture",
        "customer_email": "[email protected]",
        "customer_browser_info_accept_header": "*",
        "expiration_date": "Mon Oct 20 2025 08:31:09 GMT+0000 (Coordinated Universal Time)",
        "customer_last_name": "Nash",
        "currency": "USD",
        "status": "created",
        "customer_browser_info_language": "en",
        "customer_browser_info_java_enabled": false,
        "amount": 16,
        "hosted_page_configuration": {
          "hosted_fields": {}
        }
      },
      
      "payment_methods": {
        "payment_methods_available": [
          {
            "logo_white_png": "[email protected]",
            "logo": "visa.svg",
            "logo_favicon_colorbg_png": "[email protected]",
            "name": "visa",
            "logo_whitebg_png": "[email protected]",
            "logo_favicon_whitebg": "Visa_favicon_whitebg.svg",
            "logo_favicon_colorbg": "Visa_favicon_colorbg.svg",
            "logo_favicon_whitebg_png": "[email protected]",
            "logo_whitebg": "Visa_whitebg.svg",
            "display_name": "Visa",
            "logo_colorbg_png": "[email protected]",
            "logo_png": "visa.png",
            "form_fields": [
              {
                "label": "card_number",
                "name": "card_number",
                "data_type": "integer",
                "enum": [],
                "example": "4111 xxxx xxxx xxxx",
                "display_name": "card_number"
              },
              {
                "display_name": "cvc",
                "example": "123",
                "enum": [],
                "label": "cvc",
                "name": "cvc",
                "data_type": "integer"
              },
              {
                "data_type": "date",
                "display_name": "card_validity",
                "example": "MM/YY",
                "label": "card_validity",
                "enum": [],
                "name": "card_validity"
              },
              {
                "data_type": "name",
                "name": "cardholder_name",
                "label": "cardholder_name",
                "example": "Mickael Smith",
                "enum": [],
                "display_name": "cardholder_name"
              }
            ],
            "logo_white": "Visa_white.svg",
            "component_type": "card",
            "partner": "trustpayments",
            "required_fields": [
              "payment_method_name",
              "token",
              "amount",
              "currency"
            ],
            "countries": [
              "all"
            ],
            "logo_colorbg": "Visa_colorbg.svg"
          }
        ]
      }
    },

We strongly recommend to either send the customer browser data in your request or to provide the checkout_id in the order creation request. Please make sure to add the browser data tag script in your html. You will find it below.

Customer browser data fields

  "customer_browser_info_js_enabled": true,
  "customer_browser_info_java_enabled": true,
  "customer_browser_info_screen_height": 739,
  "customer_browser_info_accept_header": "*",
  "customer_browser_info_screen_width": 428,
  "customer_browser_info_color_depth": "24",
  "customer_browser_info_time_zone": "Europe/Paris",
  "customer_browser_info_language": "fr",
  "customer_browser_info_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_6_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/141.0.7390.96 Mobile/15E148 Safari/604.1",

Customer browser data tag script

<script>
const customer_browser_info_color_depth = window.screen.colorDepth;
const customer_browser_info_js_enabled = true;
const customer_browser_info_language = window.navigator.language;
const customer_browser_info_screen_height = window.screen.height;
const customer_browser_info_screen_width = window.screen.width;
const customer_browser_info_user_agent = window.navigator.userAgent;
let timezone;
try {
  timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
} catch (error) {
  console.error('Can not get timezone', error);
}
</script>

Tokenize

curl --request POST \
     --url https://vault-sandbox.norbr.io/token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: your_public_api_key' \
     --data '
{
  "card_number": "4242424242424242",
  "card_validity_month": "12",
  "card_validity_year": "28",
  "cvc": "100",
  "customer_scheme_name": "visa",
  "token_type": "oneshot",
  "checkout_id": "68da7168585219b89320c719"
}
'

{
  "result": {
    "code": "999999",
    "description": "Tokenization successful"
  },
  "created_date": "2025-10-03T12:04:35.420Z",
  "token": "8ff02523fd653294d3267c8d92b1819494ad60dcdc750957b1ae4e778549cc11",
  "token_type": "oneshot",
  "token_kind": "card",
  "customer_scheme_name": "visa",
  "bin_scheme_name": "visa",
  "card_6_digits": "424242",
  "card_4_digits": "4242",
  "card_validity_month": "12",
  "card_validity_year": "28",
  "card_unique_id": "b00067ec-c9f0-4306-b248-b4d6d38b1982",
  "checkout_id": "68dfbbc905a7371ed35eec5d"
}

Create Order

curl --request POST \
     --url https://api-sandbox.norbr.io/payment/order \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
		 --header 'x-api-key: your_private_api_key' \
     --data '
{
  "operation_type": "authorize",
  "checkout_id": "67ceb0cb9af8068910f8a752",
  "token": "b65ab7f6099b1fd8e357ea319dc851f70daebe9e333be065a23d8239130089c3",
  "amount": 16,
  "currency": "USD",
  "order_merchant_id": "123445-1abc1-1111-2222-34a56bbb789ccc",
  "payment_channel": "e-commerce",
  "type": "hosted_fields",
  "token_type": "oneshot",
  "accept_url": "https://www.google.com/search?q=accept",
  "decline_url": "https://www.google.com/search?q=decline",
  "cancel_url": "https://www.google.com/search?q=cancel",
  "pending_url": "https://www.google.com/search?q=pending",
  "exception_url": "https://www.google.com/search?q=exception",
  "locale": "en_GB",
  "customer_id": "Customer-123",
  "customer_browser_info_java_enabled": true,
  "customer_browser_info_screen_height": 119,
  "authentication_indicator": "no_3ds",
  "customer_browser_info_language": "EN",
  "customer_country": "PT",
  "customer_gender": "male",
  "customer_birth_date": "1995-04-13",
  "max_attempts": "200",
  "customer_last_name": "Nash",
  "customer_first_name": "Kirby",
  "customer_ip": "127.0.0.1"
}
'

{
  "result": {
    "description": "pending authorization",
    "code": "421080"
  },
  "checkout_id": "68f618875a282ea788fb83e7",
  "pending_url": "https://www.google.com/search?q=pending",
  "authorization_code": "hicqefG8908270GJ",
  "is_authenticated": false,
  "authorization_date": "Mon Oct 20 2025 11:10:11 GMT+0000 (Coordinated Universal Time)",
  "order_description": "Gym membership: trial",
  "accept_url": "https://www.google.com/search?q=accept",
  "authorization_amount": 10,
  "exception_url": "https://www.google.com/search?q=exception",
  "customer_last_name": "Nash",
  "customer_first_name": "Kriby",
  "decline_url": "https://www.google.com/search?q=decline",
  "cancel_url": "https://www.google.com/search?q=cancel",
  "risk_assessment_partner": "PSP1",
  "payment_channel": "e-commerce",
  "authorization_result": "success",
  "is_suspicious": false,
  "psp_result_description": "accepted",
  "merchant_contract_id": "123456d8973128404927407200",
  "website_url": "https://example.com",
  "transaction_id": "68f618935a282ea788fb85f0",
  "status": "authorization_requested",
  "order_merchant_id": "123445-1abc1-1111-2222-34a56bbb789ccc",
  "psp_result_code": "20",
  "customer_ip": "66.249.83.110",
  "risk_assessment_date": "Mon Oct 20 2025 11:10:11 GMT+0000 (Coordinated Universal Time)",
  "order_currency": "USD",
  "authentication_result": "",
  "order_amount": 16,
  "payin_partner": "PSP1",
  "is_captured": false,
  "customer_email": "[email protected]",
  "payment_method_name": "visa",
  "order_id": "68f618935a282ea788fb85ef",
  "authentication_indicator": "no_3ds"
}

Full API Reference

Please visit our API reference section to see the full scope. Also, you can download our Postman collection here.