Processors

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

List processor accounts (MIDs)

GET/v1/processor-accounts

Processor accounts (MIDs): connector, environment, store, currencies, weight, caps with live usage, connection test state, enabled state and the reason when disabled. Credentials are never returned.

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/processor-accounts" \
  -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"
  }
}

Connect a processor account

POST/v1/processor-accounts

Adds a processor account from the catalog. Credentials (connectorCredentials) are write-only: they go to the payment switch and are never stored or echoed by GIEP. The account is tested at once and enabled only if the test does not fail. Production accounts are refused unless the deployment allows them. Audited.

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

Request body · application/jsonrequired

storeIdstring · uuid
labelstringrequired
min 1 chars
providerstringrequired
One ofhyperswitchsimulatormamongeniusnomupayonerway
connectorstringrequired
pattern ^[a-z0-9][a-z0-9_-]{0,39}$
hyperswitchConnectorIdstring
connectorCredentialsmap<string, string>
midstring
currenciesarray<string>
Default
weightinteger
Default 0min 0 · max 100
capsobject
Fields: 5 fields
- currencystringrequired
  3 chars
- dailyAmountinteger
  min 0
- monthlyAmountinteger
  min 0
- dailyCountinteger
  min 0
- monthlyCountinteger
  min 0
supportsTokensboolean
Default false
credentialsRefstring
environmentstring
One ofsandboxproductionDefault sandbox

Responses

201Success
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 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/processor-accounts" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string",
  "provider": "hyperswitch",
  "connector": "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"
  }
}

Retrieve a processor account

GET/v1/processor-accounts/{id}

One processor account (no credentials).

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

Path parameters

idstringrequired

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/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be" \
  -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"
  }
}

Edit a processor account

PATCH/v1/processor-accounts/{id}

Label, MID, currencies, store, caps (null removes them), weight, token support, enabled. connectorCredentials rotates the credentials (write-only) and re-runs the connection test. Audited.

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

Path parameters

idstringrequired

Request body · application/jsonrequired

labelstring
min 1 chars · max 120 chars
midstringnullable
max 120 chars
currenciesarray<string>
max 50 items
storeIdstring · uuidnullable
capsobjectnullable
Fields: 5 fields
- currencystringrequired
  3 chars
- dailyAmountinteger
  min 0
- monthlyAmountinteger
  min 0
- dailyCountinteger
  min 0
- monthlyCountinteger
  min 0
weightinteger
min 0 · max 100
supportsTokensboolean
enabledboolean
environmentstring
One ofsandboxproduction
connectorCredentialsmap<string, string>

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 PATCH "$GIEP_API_URL/v1/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string",
  "mid": "string",
  "currencies": [
    "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"
  }
}

Archive a processor account (soft delete)

DELETE/v1/processor-accounts/{id}

409 processor_in_flight while a payment on the account is in flight or awaiting capture. The account is disabled first and kept for history and refunds.

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

Path parameters

idstringrequired

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 DELETE "$GIEP_API_URL/v1/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be" \
  -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"
  }
}

Disable a processor account

POST/v1/processor-accounts/{id}/disable

Stops routing new payments to the account at once (payments in flight finish normally) and switches the connector off in the payment switch. A reason of at least 3 characters is required. Audited.

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

Path parameters

idstringrequired

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/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be/disable" \
  -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"
  }
}

Enable a processor account

POST/v1/processor-accounts/{id}/enable

Refused (422) for an archived account or one whose last connection test failed.

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

Path parameters

idstringrequired

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/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be/enable" \
  -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"
  }
}

Test the processor connection

POST/v1/processor-accounts/{id}/test-connection

Sandbox Hyperswitch accounts: a minimum-amount authorisation with the published test card, voided at once. Production accounts and GIEP-side adapters: unverified. A failure disables the account until a test passes. Audited.

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

Path parameters

idstringrequired

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/processor-accounts/9d512fad-cae6-4e57-a39c-d145c-1be/test-connection" \
  -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"
  }
}

Processors that can be added (platform catalog)

GET/v1/processor-catalog

Connector, display name, credential fields the form asks for (values are write-only), supported operations and the environments this deployment allows.

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/processor-catalog" \
  -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"
  }
}