Routing

11 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

Retryable / do-not-retry decline codes per connector

GET/v1/decline-codes

Platform tables per connector (built from published processor documentation, unverified against sandbox) with this merchant’s overrides applied, plus decline codes no table knew in the last 30 days.

Authentication: API key (Bearer)
Permission: processor:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/decline-codes" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Override one decline code (retry / do not retry / default)

PUT/v1/decline-codes/overrides

Fraud, authentication and duplicate declines can never be made retryable (422 decline_code_locked). Audited.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

connectorstringrequired
pattern ^[a-z0-9][a-z0-9_-]{0,39}$
codestringrequired
pattern ^[A-Za-z0-9_.:-]{1,64}$
actionstringrequired
One ofretrydo_not_retrydefault

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/decline-codes/overrides" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector": "string",
  "code": "string",
  "action": "retry"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Preview routing for a candidate policy

POST/v1/stores/{id}/routing-policy/preview

Where the next 100 payments with the given currency and amount would go first under a draft policy, computed by the same code as live routing. Changes nothing.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

policyobjectrequired
Fields: 6 fields
- routesarray<object>required
  Each item has 4 fields
  connectorIdstring · uuidrequired
  labelstringrequired
  enabledbooleanrequired
  weightintegerrequired
  min 0 · max 100
- rulesarray<object>
  Default max 100 items
  Each item has 6 fields
  idstringrequired
  min 1 chars · max 64 chars
  namestringrequired
  max 120 chars
  enabledboolean
  priorityintegerrequired
  whenarray<object>required
  max 20 items
  Each item has 3 fields
  fieldstringrequired
  One ofcurrencyamountcountryissuerCountrycardBrandcardBinpaymentMethodstoreIdisRecurring
  opstringrequired
  One ofeqneqinningtgteltlteprefixrange
  valueone ofrequired
  connectorIdsarray<string> · uuidrequired
- orderarray<string> · uuid
  max 50 items
- cascadeobjectrequired
  Fields: 2 fields
  enabledbooleanrequired
  maxAttemptsintegerrequired
  min 1 · max 5
- strategystring
  One ofpercentagefill_to_target
- sequencearray<object>
  max 50 items
  Each item has 3 fields
  connectorIdstring · uuidrequired
  targetobject
  Fields: 2 fields
  amountintegerrequired
  greater than 0
  currencystringrequired
  pattern ^[A-Z]{3}$
  targetCountinteger
  greater than 0
templateobject
Fields: 6 fields
- amountintegerrequired
  greater than 0
- currencystringrequired
  3 chars
- countrystring
  2 chars
- issuerCountrystring
  2 chars
- cardBrandstring
- cardBinstring
  pattern ^\d{6,8}$

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/stores/31f82246-a8dd-40aa-a5a2-e8930074a/routing-policy/preview" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy": {
    "routes": [
      {
        "connectorId": "fbfaa38d-d214-418d-a14d-1f9e089b",
        "label": "string",
        "enabled": false,
        "weight": 1
      }
    ],
    "cascade": {
      "enabled": false,
      "maxAttempts": 1
    }
  }
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Simulate a policy over historical payments

POST/v1/stores/{id}/routing-policy/simulate

Replays recent payments of the store (up to the last 30 days) through a draft policy and the active one, and counts how many would go to a different processor first. Changes nothing.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

policyobjectrequired
Fields: 6 fields
- routesarray<object>required
  Each item has 4 fields
  connectorIdstring · uuidrequired
  labelstringrequired
  enabledbooleanrequired
  weightintegerrequired
  min 0 · max 100
- rulesarray<object>
  Default max 100 items
  Each item has 6 fields
  idstringrequired
  min 1 chars · max 64 chars
  namestringrequired
  max 120 chars
  enabledboolean
  priorityintegerrequired
  whenarray<object>required
  max 20 items
  Each item has 3 fields
  fieldstringrequired
  One ofcurrencyamountcountryissuerCountrycardBrandcardBinpaymentMethodstoreIdisRecurring
  opstringrequired
  One ofeqneqinningtgteltlteprefixrange
  valueone ofrequired
  connectorIdsarray<string> · uuidrequired
- orderarray<string> · uuid
  max 50 items
- cascadeobjectrequired
  Fields: 2 fields
  enabledbooleanrequired
  maxAttemptsintegerrequired
  min 1 · max 5
- strategystring
  One ofpercentagefill_to_target
- sequencearray<object>
  max 50 items
  Each item has 3 fields
  connectorIdstring · uuidrequired
  targetobject
  Fields: 2 fields
  amountintegerrequired
  greater than 0
  currencystringrequired
  pattern ^[A-Z]{3}$
  targetCountinteger
  greater than 0

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/stores/31f82246-a8dd-40aa-a5a2-e8930074a/routing-policy/simulate" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy": {
    "routes": [
      {
        "connectorId": "fbfaa38d-d214-418d-a14d-1f9e089b",
        "label": "string",
        "enabled": false,
        "weight": 1
      }
    ],
    "cascade": {
      "enabled": false,
      "maxAttempts": 1
    }
  }
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Set the store's capture method

PUT/v1/stores/{storeId}/payment-settings

manual authorises only; capture with POST /v1/payments/{id}/capture.

Authentication: API key (Bearer)
Permission: processor:manage
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Request body · application/jsonrequired

captureMethodstringrequired
One ofautomaticmanual

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/stores/string/payment-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "captureMethod": "automatic"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

The active routing policy for a store (null when none is published)

GET/v1/stores/{storeId}/routing-policy

Returns { policy, activatedAt, targetProgress }. For a fill_to_target policy, targetProgress is { timeZone, resetsAt, entries: [{ connectorId, used, target }] }: each account's committed volume this calendar month in the merchant time zone (the monthly-cap measure, integer minor units of the target currency). Informational; every payment recomputes it. null for percentage policies.

Authentication: API key (Bearer)
Permission: processor:read
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/stores/string/routing-policy" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Publish the routing policy for a store

PUT/v1/stores/{storeId}/routing-policy

Creates the next policy version, archives the previous one and writes an audit row. strategy defaults to percentage. With fill_to_target, sequence is required: non-empty, no duplicate accounts, each a route of this policy that serves this store, positive integer targets in a currency the account settles (and its cap currency when it has an amount cap). Targets are soft (concurrent payments may overshoot); caps stay hard limits.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Request body · application/jsonrequired

routesarray<object>required
Each item has 4 fields
- connectorIdstring · uuidrequired
- labelstringrequired
- enabledbooleanrequired
- weightintegerrequired
  min 0 · max 100
rulesarray<object>
Default max 100 items
Each item has 6 fields
- idstringrequired
  min 1 chars · max 64 chars
- namestringrequired
  max 120 chars
- enabledboolean
- priorityintegerrequired
- whenarray<object>required
  max 20 items
  Each item has 3 fields
  fieldstringrequired
  One ofcurrencyamountcountryissuerCountrycardBrandcardBinpaymentMethodstoreIdisRecurring
  opstringrequired
  One ofeqneqinningtgteltlteprefixrange
  valueone ofrequired
- connectorIdsarray<string> · uuidrequired
orderarray<string> · uuid
max 50 items
cascadeobjectrequired
Fields: 2 fields
- enabledbooleanrequired
- maxAttemptsintegerrequired
  min 1 · max 5
strategystring
One ofpercentagefill_to_target
sequencearray<object>
max 50 items
Each item has 3 fields
- connectorIdstring · uuidrequired
- targetobject
  Fields: 2 fields
  amountintegerrequired
  greater than 0
  currencystringrequired
  pattern ^[A-Z]{3}$
- targetCountinteger
  greater than 0

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/stores/string/routing-policy" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routes": [
    {
      "connectorId": "fbfaa38d-d214-418d-a14d-1f9e089b",
      "label": "string",
      "enabled": false,
      "weight": 1
    }
  ],
  "cascade": {
    "enabled": false,
    "maxAttempts": 1
  }
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Reorder the cascade (new policy version)

PUT/v1/stores/{storeId}/routing-policy/order

Publishes a new version of the active policy with only the explicit processor order changed; audited as routing_policy.reordered.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Request body · application/jsonrequired

orderarray<string> · uuidrequired
min 1 items · max 50 items

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/stores/string/routing-policy/order" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order": [
    "732c1097-a9fc-448f-abaa-f6c63ae0"
  ]
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Pause a store's routing (emergency brake)

POST/v1/stores/{storeId}/routing/pause

New payments for the store are refused (409 store_routing_paused) before any processor call; in-flight payments, reconciliation and refunds continue. Audited.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Request body · application/jsonrequired

reasonstringrequired
min 3 chars · max 500 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/stores/string/routing/pause" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Resume a store's routing

POST/v1/stores/{storeId}/routing/resume

Lets new payments of the store route again after a pause. Audited.

Authentication: API key (Bearer)
Permission: routing:publish
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/stores/string/routing/resume" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

A store's routing state (paused or live) and capture setting

GET/v1/stores/{storeId}/routing/state

Whether routing of the store is paused (with the time and reason) and whether payments are captured automatically or manually.

Authentication: API key (Bearer)
Permission: processor:read
Idempotency-Key: Not used
Success: 200

Path parameters

storeIdstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/stores/string/routing/state" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}