---
updatedAt: 2026-09-29T14:04:39.000Z
agentTools:
  projectIndex: https://developer.norbr.io/llms.txt
---

# 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.

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

<style>
  .guides-section {
    margin-top: 4rem;
  }

  .guides-section h2 {
    font-size: 1.8rem;
    font-weight: 700;
    margin-bottom: 1.5rem;
    color: #000;
    text-align: center;
  }

  .guides-cards {
    display: grid;
    grid-template-columns: 1fr;
    gap: 2rem;
    margin-top: 2rem;
  }

  .guide-card {
    background: #fff;
    border-radius: 12px;
    border: 1px solid #e5e5e5;
    padding: 2rem;
    box-shadow: 0 2px 8px rgba(0,0,0,0.05);
    transition: transform 0.2s ease, box-shadow 0.2s ease;
  }

  .guide-card:hover {
    transform: translateY(-3px);
    box-shadow: 0 4px 12px rgba(0,0,0,0.08);
  }

  .guide-card h3 {
    font-size: 1.3rem;
    font-weight: 700;
    color: #000;
    margin-bottom: 1rem;
  }

  .guide-card ul {
    list-style: none;
    padding-left: 0;
    margin: 0;
  }

  .guide-card li {
    position: relative;
    margin-bottom: 0.75rem;
    padding-left: 1.4rem;
    line-height: 1.5;
    color: #333;
  }

  .guide-card li::before {
    content: "•";
    position: absolute;
    left: 0;
    top: 0;
    color: #000;
    font-weight: bold;
    font-size: 1.2rem;
  }

  .guide-card strong {
    color: #000;
  }
</style>
`}</HTMLBlock>

## 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 payment/checkout request
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": "test@gmail.com",
  "expiration_date": "Mon Oct 20 2025 08:31:09 GMT+0000 (Coordinated Universal Time)",
  "customer_first_name": "Kirby",
  "customer_last_name": "Nash"
}
'
```
```json payment/checkout response
{
      "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": "test@gmail.com",
        "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": "Visa_white@2x.png",
            "logo": "visa.svg",
            "logo_favicon_colorbg_png": "Visa_favicon_colorbg@2x.png",
            "name": "visa",
            "logo_whitebg_png": "Visa_whitebg@2x.png",
            "logo_favicon_whitebg": "Visa_favicon_whitebg.svg",
            "logo_favicon_colorbg": "Visa_favicon_colorbg.svg",
            "logo_favicon_whitebg_png": "Visa_favicon_whitebg@2x.png",
            "logo_whitebg": "Visa_whitebg.svg",
            "display_name": "Visa",
            "logo_colorbg_png": "Visa_colorbg@2x.png",
            "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"
          }
        ]
      }
    },
```

<br />

<HTMLBlock>{`
<div style="
  background-color: #0a1a3c; /* lekko przezroczyste, ciemnoniebieskie tło */
  border: 2px solid #0a3d91; /* ciemnoniebieska obramówka */
  border-radius: 15px; /* zaokrąglone rogi */
  padding: 15px 20px; 
  color: #ffffff; /* biały tekst dla kontrastu */
  font-family: Arial, sans-serif; 
  width: 100%; /* pełna szerokość sekcji */
  box-shadow: 0 4px 6px rgba(0,0,0,0.05);
  display: flex;
  align-items: center;
  margin: 10px 0;
  box-sizing: border-box;
">
  
  <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" style="width: 20px; height: 20px; margin-right: 10px; flex-shrink: 0; color: #ffffff;">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
          d="M13 16h-1v-4h-1m1-4h.01M12 2a10 10 0 100 20 10 10 0 000-20z"></path>
  </svg>
  <span>We <b>strongly recommend</b> 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 <b>add the browser data tag script</b> in your html. You will find it below.</span>
</div>
`}</HTMLBlock>

#### Customer browser data fields

```json Customer browser data sample
  "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

```html Browser data script tag
<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 /token request
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"
}
'
```
```json /token response
{
  "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 payment/order request
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"
}
```
```json payment/order response
{
  "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": "test@gmail.com",
  "payment_method_name": "visa",
  "order_id": "68f618935a282ea788fb85ef",
  "authentication_indicator": "no_3ds"
}
```

### Full API Reference

Please visit our [**API reference**](/reference) section to see the full scope. Also, you can download our Postman collection **[here](https://elements.getpostman.com/view/import?collection=15029336-1462553e-a9bd-46f7-b44f-36805df419cf-2s7YfScCKE)**.

<br />