Create Routing Rule

POSThttps://api.omise.co/routing_group_rules

Create a new routing group rule for payment routing. Routing rules allow you to control how transactions are processed across different payment providers and acquirers based on various conditions.

---

Request Parameters

Required - 3 fieldsRequired Parameters

▼

`name`STRING(required)

Human-readable name for the routing rule. Used for identification in dashboards and logs.

Example:"Route high-value cards to Provider A"

`conditions`ARRAY(required)

Array of condition objects that determine when this rule applies. Each condition specifies a field, operator, and value to match against.

Example:[{"field":"amount","operator":"gte","value":100000}]

`provider`STRING(required)

Target payment provider identifier. Transactions matching this rule will be routed to this provider.

Example:"provider_a"

Condition StructureCondition Parameters

▼

`conditions[].field`STRING(required)

The transaction field to evaluate. Options include amount, currency, card_brand, card_type, card_country, metadata fields.

Example:"amount"

Values:amount, currency, card_brand, card_type, card_country, metadata

`conditions[].operator`STRING(required)

Comparison operator for the condition.

Example:"gte"

Values:eq, neq, gt, gte, lt, lte, in, not_in, contains

`conditions[].value`ANY(required)

The value to compare against. Type depends on the field (number for amount, string for currency, array for "in" operator).

Example:100000

Additional - 5 fieldsAdditional Parameters

▼

Metadata - 1 fieldMetadata Parameters

▼

---

Responses

200

Rule created successfully

Routing rule created successfully. The rule is immediately active unless enabled is set to false.

Response includes:

• object - Always returns "routing_group_rule"
• id - Unique rule identifier
• name - Rule name
• conditions - Array of condition objects
• provider - Target provider identifier
• priority - Rule priority
• enabled - Whether rule is active
• created_at - Creation timestamp

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Missing required fields (name, conditions, provider)
• Invalid condition structure
• Unknown provider identifier
• Invalid operator for field type
• Condition value type mismatch

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Referenced resource not found.

Common causes:

• Invalid provider identifier
• Routing feature not enabled for account

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/routing_group_rules \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "name=Route high-value to Provider A" \
  -d "provider=provider_a" \
  -d "conditions[0][field]=amount" \
  -d "conditions[0][operator]=gte" \
  -d "conditions[0][value]=100000" \
  -d "priority=100"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

rule = Omise::RoutingGroupRule.create({
  name: 'Route high-value to Provider A',
  provider: 'provider_a',
  conditions: [
    { field: 'amount', operator: 'gte', value: 100000 }
  ],
  priority: 100
})

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

rule = omise.RoutingGroupRule.create(
    name='Route high-value to Provider A',
    provider='provider_a',
    conditions=[
        {'field': 'amount', 'operator': 'gte', 'value': 100000}
    ],
    priority=100
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const rule = await omise.routingGroupRules.create({
  name: 'Route high-value to Provider A',
  provider: 'provider_a',
  conditions: [
    { field: 'amount', operator: 'gte', value: 100000 }
  ],
  priority: 100
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$rule = OmiseRoutingGroupRule::create([
    'name' => 'Route high-value to Provider A',
    'provider' => 'provider_a',
    'conditions' => [
        ['field' => 'amount', 'operator' => 'gte', 'value' => 100000]
    ],
    'priority' => 100
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Condition condition = new Condition.Builder()
    .field("amount")
    .operator("gte")
    .value(100000)
    .build();

RoutingGroupRule rule = client.routingGroupRules().create()
    .name("Route high-value to Provider A")
    .provider("provider_a")
    .conditions(Arrays.asList(condition))
    .priority(100)
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var rule = await client.RoutingGroupRules.Create(new CreateRoutingRuleRequest
{
    Name = "Route high-value to Provider A",
    Provider = "provider_a",
    Conditions = new List<Condition>
    {
        new Condition { Field = "amount", Operator = "gte", Value = 100000 }
    },
    Priority = 100
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

rule, _ := client.RoutingGroupRules().Create(&operations.CreateRoutingGroupRule{
    Name:     "Route high-value to Provider A",
    Provider: "provider_a",
    Conditions: []omise.Condition{
        {Field: "amount", Operator: "gte", Value: 100000},
    },
    Priority: 100,
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Missing or invalid parameters	Check all required fields are provided
authentication_failure	Invalid API key	Verify your secret key is correct
invalid_condition	Condition structure is invalid	Check field, operator, and value are correct
invalid_provider	Provider not found	Verify provider identifier exists
duplicate_rule	Rule with same name exists	Use a unique rule name

Condition Operators

Operator	Description	Valid For
eq	Equal to	All fields
neq	Not equal to	All fields
gt	Greater than	amount
gte	Greater than or equal	amount
lt	Less than	amount
lte	Less than or equal	amount
in	Value in list	currency, card_brand, card_type
not_in	Value not in list	currency, card_brand, card_type
contains	Contains substring	metadata fields

Routing Rule Object Fields

Field	Type	Description
object	string	Always returns "routing_group_rule"
id	string	Unique rule identifier
name	string	Human-readable rule name
description	string	Rule description
conditions	array	Array of condition objects
provider	string	Target provider identifier
priority	integer	Rule evaluation priority
match_type	string	Condition matching logic (all/any)
weight	integer	Load balancing weight
enabled	boolean	Whether rule is active
metadata	object	Custom key-value pairs
created_at	string	Creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

---

🔑API Credentials

▼

Try it out

Required - 3 fields

▼

name(Required)

provider(Required)

conditions(Required)

Additional - 6 fields

▼

Your IP: ...Loading...