Billing

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

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: Not used
Success: 200

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 "Content-Type: application/json" \
  -d '{
  "emails": [
    "[email protected]"
  ]
}'

// 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"
  }
}

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.

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

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

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

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.

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

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

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

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.

{
  "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"
  }
}

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.

{
  "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 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.

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

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

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

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.

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

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

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