Skip to content

Billing

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

Low-balance thresholds and whether the wallet is under them

GET/v1/billing/low-balance

Thresholds GIEP staff set per currency. below is true from the moment a fee took the wallet under the threshold until a top-up or credit brings it back. Readable while blocked.

Authentication
API key (Bearer)
Permission
billing: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/billing/low-balance" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Set statement and billing-notice recipients (empty = owners)

PUT/v1/billing/recipients

Email addresses for weekly statements and billing notices. An empty list sends them to the owners. Requires billing:manage. Audited.

Authentication
API key (Bearer)
Permission
billing:manage
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • emailsarray<string> · emailrequired
    max 10 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/billing/recipients" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-recipients-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "ana@example.com"
  ]
}'
// JSON object. The OpenAPI document does not list its fields.

Service restriction state and the estimate behind it

GET/v1/billing/service-restriction

Whether you opted in, any staff override, and per currency the wallet balance against the estimated fees of the next subscription billing run. While restricted is true new renewal runs pause with reason insufficient_balance; hosted checkout and refunds are never blocked. Readable while blocked.

Authentication
API key (Bearer)
Permission
billing: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/billing/service-restriction" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Opt in or out of pausing renewal runs on insufficient balance

PUT/v1/billing/service-restriction

Owners and admins only. When enabled and the wallet cannot cover the estimated fees of the next billing run, new renewal runs pause until you top up. Audited.

Authentication
API key (Bearer)
Permission
billing:manage
Idempotency-Key
Required
Success
200

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • enabledbooleanrequired

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/billing/service-restriction" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-service-restriction-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
// JSON object. The OpenAPI document does not list its fields.

Billing status: amounts owed, overdue, block state and how to pay

GET/v1/billing/status

Readable while the merchant is blocked for non-payment (MON-012), like the wallet and statements.

Authentication
API key (Bearer)
Permission
billing: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/billing/status" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Usage for a month and the GIEP fees posted for it

GET/v1/billing/usage

Payments, subscription renewals, alerts, messages sent (Module 6, messages: deliveries handed to the provider) and AI calls (Module 8, aiCalls: model attempts) in the calendar month (?month=YYYY-MM, UTC, default this month), and the fees posted per kind from the ledger (integer minor units with currency).

Authentication
API key (Bearer)
Permission
billing: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/billing/usage" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Fee schedules that apply to you

GET/v1/fee-schedules

The fee schedule versions that apply to the merchant (transaction, alert, refund and platform fees per currency: basis points, fixed, minimum, maximum, effective from). Set by GIEP staff; read-only here.

Authentication
API key (Bearer)
Permission
billing: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/fee-schedules" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

The GIEP Payments application (status `none` before a draft exists)

GET/v1/giep-payments/application

Business details, owners, document references, expected volume, partner reference, decision and status history.

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/giep-payments/application" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Save the application draft (while draft or needs info)

PUT/v1/giep-payments/application

Documents are object-storage references (s3://...), never files. Ownership in basis points may not exceed 100%. Audited.

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

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

Request body · application/jsonrequired

  • businessobjectrequired
    Fields: 6 fields
    • legalNamestringrequired
      min 2 chars · max 200 chars
    • registrationNumberstring
      max 100 chars
    • countrystringrequired
      pattern ^[A-Z]{2}$
    • websitestring · uri
      max 300 chars
    • descriptionstring
      max 2000 chars
    • mccstring
      pattern ^\d{4}$
  • ownersarray<object>required
    max 10 items
    Each item has 3 fields
    • namestringrequired
      min 2 chars · max 200 chars
    • ownershipBpsintegerrequired
      min 0 · max 10000
    • countrystringrequired
      pattern ^[A-Z]{2}$
  • documentsarray<object>required
    max 20 items
    Each item has 2 fields
    • kindstringrequired
      max 50 chars
    • refstringrequired
      pattern ^s3:\/\/[\w./-]+$
  • expectedMonthlyVolumeobject
    Fields: 2 fields
    • amountintegerrequired
      greater than 0
    • currencystringrequired
      3 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 PUT "$GIEP_API_URL/v1/giep-payments/application" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-application-v1" \
  -H "Content-Type: application/json" \
  -d '{
  "business": {
    "legalName": "string",
    "country": "US"
  },
  "owners": [
    {
      "name": "string",
      "ownershipBps": 1,
      "country": "US"
    }
  ],
  "documents": [
    {
      "kind": "string",
      "ref": "1042"
    }
  ]
}'
// JSON object. The OpenAPI document does not list its fields.

Submit the application to the acquiring partner

POST/v1/giep-payments/application/submit

Idempotent at the partner (one key per application and submission round): a retried submit is the same partner application. The decision arrives later by a signed partner webhook. 503 while no partner is configured.

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

Headers

  • Idempotency-Keystringrequired

    Required with an API key (SELL-033): 8-255 characters of A-Z a-z 0-9 _ - : . The same key with the same request returns the stored response without running it again; with a different request 422 idempotency_key_reused; while the first is still running 409 request_in_progress. Signed-in workspace sessions may omit it.

    min 8 chars · max 255 chars · pattern ^[A-Za-z0-9_:.-]+$

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/giep-payments/application/submit" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Idempotency-Key: order-1042-submit-v1"
// JSON object. The OpenAPI document does not list its fields.

Export ledger postings (CSV or NDJSON, streamed)

GET/v1/ledger/export

Your wallet and receivable postings with their entries, one consistent snapshot. account is wallet or receivable. Audited.

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

Query parameters

  • formatstring
    One ofcsvndjsonDefault csv
  • fromany
  • toany
  • currencystring
    3 chars
  • accountstring
    min 1 chars · max 200 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 GET "$GIEP_API_URL/v1/ledger/export" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

List weekly statements

GET/v1/statements

Weekly statements, newest first, optionally for one currency: period, opening and closing wallet balance, fees by kind and amount owed. Readable while the account is paused for non-payment.

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

Query parameters

  • currencystring
    3 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 GET "$GIEP_API_URL/v1/statements" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Retrieve a statement

GET/v1/statements/{id}

One statement with its wallet and receivable movements. Readable while the account is paused for non-payment.

Authentication
API key (Bearer)
Permission
billing: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/statements/d75ce063-5d0b-48fd-a934-a300-567" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.

Wallet balances

GET/v1/wallet

Wallet (prepaid balance for GIEP fees) and receivable (fees owed to GIEP) balances per currency, and recent ledger postings. Readable while the account is paused for non-payment.

Authentication
API key (Bearer)
Permission
billing: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/wallet" \
  -H "Authorization: Bearer $GIEP_API_KEY"
// JSON object. The OpenAPI document does not list its fields.
Billing · API reference · GIEP