Checkout API

Povito Checkout API v1.0.0-draft.5

Hosted, embeddable checkout for Povito merchants

Download contract checkout-v1.yaml Try requests in the Sandbox explorer

30 operations, generated at build time from the contract. Keys and base URLs for each environment: Keys and environments.

Base URLs#

Environment	Base URL
Live	`https://api.checkout.povito.com/v1`
Sandbox Staging	`https://api.checkout.staging.povito.com/v1`
Local	`http://localhost:9100/v1`

Overview#

Take payments through Povito Checkout: your server creates a checkout session, the shopper pays on Povito's hosted page, and you are told the result by a signed webhook — then confirm it by reading the session.

Money is integer minor units of the currency. IQD has no minor unit (45000 is forty-five thousand dinars); USD is cents.

A webhook is a prompt to GET /checkout/sessions/{id}. The session is the only authoritative state — never act on a webhook body alone.

Test mode is a key mode. A povito_ck_test_… key drives the simulated test gateway and never moves real money; see the Testing guide.

Authentication#

`secretKey`#

HTTP bearer — Authorization: Bearer …

povito_ck_live_… or povito_ck_test_… — server-side only

`publishableKey`#

HTTP bearer — Authorization: Bearer …

povito_pk_live_… or povito_pk_test_… — safe in a browser or app; unlocks /public/* only

`customerToken`#

API key in header X-Povito-Customer-Token

Session-scoped token issued by OTP verification

Endpoints#

Sessions

GET `/checkout/sessions`#

listCheckoutSessions · secretKey

List sessions, typically by reference_id

Parameters

Name	In	Type	Notes
`reference_id`	`query`	`string`	max length 128
`status`	`query`	`SessionStatus`
`created_after`	`query`	`string` (date-time)
`limit`	`query`	`integer`	default `20` · min 1 · max 100
`cursor`	`query`	`string`

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`data`required	`array of CheckoutSession`
`next_cursor`required	`string` \| `null`

401 Missing or invalid key ErrorEnvelope · Unauthorized

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/checkout/sessions" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "data": [
    {
      "id": "cs_live_01J8Z3K9Q4M2XA7B",
      "object": "checkout.session",
      "code": "code",
      "url": "https://example.com",
      "livemode": true,
      "status": "open",
      "payment_status": "unpaid",
      "reference_id": "reference_id",
      "amount": 0,
      "currency": "Currency",
      "line_items": [
        {
          "label": null,
          "amount": null,
          "quantity": null,
          "type": null
        }
      ],
      "payment_method_types": [
        "cashondelivery"
      ],
      "customer": {
        "id": "id",
        "phone": "phone",
        "name": "name",
        "address": null
      },
      "collect": {
        "phone": "required",
        "name": "required",
        "shipping_address": "none"
      },
      "presentment": {
        "currency": null,
        "fx_rate": null
      },
      "payment": {
        "attempt_id": null,
        "method": null,
        "gateway": null,
        "gateway_reference": null,
        "captured_amount": null,
        "captured_currency": null,
        "presented_amount": null,
        "presented_currency": null,
        "fx_rate": null,
        "captured_at": null,
        "instrument": null
      },
      "refunded_amount": 0,
      "locale": "ar",
      "success_url": "https://example.com",
      "cancel_url": "https://example.com",
      "expires_at": "2026-09-12T10:30:00Z",
      "completed_at": "2026-09-12T10:30:00Z",
      "metadata": {
        "key": "string"
      },
      "created_at": "2026-09-12T10:30:00Z",
      "updated_at": "2026-09-12T10:30:00Z"
    }
  ],
  "next_cursor": "next_cursor"
}

POST `/checkout/sessions`#

createCheckoutSession · secretKey

Create a checkout session and get the URL to send the shopper to

Parameters

Name	In	Type	Notes
`Idempotency-Key`required	`header`	`string`	Same key + same body replays the first response; same key + different body is 409. A UUID is the usual choice pattern `^[A-Za-z0-9_-]{8,128}$`

Request body application/json · required

CheckoutSessionCreate

Responses

Status	Meaning	Body
`200`	An open session already exists for this reference_id in this mode; it is returned unchanged	`CheckoutSession`
`201`	Created header `Idempotent-Replayed` — `IdempotentReplayed`	`CheckoutSession`
`400`	Validation error	`ErrorEnvelope` · `BadRequest`
`401`	Missing or invalid key	`ErrorEnvelope` · `Unauthorized`
`403`	Insufficient scope, mode mismatch, or suspended merchant	`ErrorEnvelope` · `Forbidden`
`409`	Idempotency conflict, wrong state, or refund ceiling	`ErrorEnvelope` · `Conflict`
`422`	Business rule	`ErrorEnvelope` · `Unprocessable`
`429`	Too many requests header `Retry-After`	`ErrorEnvelope` · `RateLimited`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/checkout/sessions" \
  -H "Authorization: Bearer povito_ck_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "cart_01J8Z3K9Q4M2XA7B",
  "amount": 45000,
  "currency": "IQD",
  "line_items": [
    {
      "label": "Basket",
      "amount": 42000,
      "type": "charge"
    },
    {
      "label": "Delivery — Hi-Express",
      "amount": 5000,
      "type": "shipping"
    },
    {
      "label": "Coupon RAMADAN",
      "amount": 2000,
      "type": "discount"
    }
  ],
  "payment_method_types": [
    "zaincash"
  ],
  "customer": {
    "phone": "+9647800000000",
    "name": "Ali M. Ismail"
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "locale": "ar",
  "success_url": "https://povito.com/ar/checkout/payment/return",
  "cancel_url": "https://povito.com/ar/checkout",
  "metadata": {
    "cart_id": "cart_01J8Z3K9Q4M2XA7B"
  }
}'

Request body — Marketplace order, method pre-selected in the storefront (Phase 1)json

{
  "reference_id": "cart_01J8Z3K9Q4M2XA7B",
  "amount": 45000,
  "currency": "IQD",
  "line_items": [
    {
      "label": "Basket",
      "amount": 42000,
      "type": "charge"
    },
    {
      "label": "Delivery — Hi-Express",
      "amount": 5000,
      "type": "shipping"
    },
    {
      "label": "Coupon RAMADAN",
      "amount": 2000,
      "type": "discount"
    }
  ],
  "payment_method_types": [
    "zaincash"
  ],
  "customer": {
    "phone": "+9647800000000",
    "name": "Ali M. Ismail"
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "locale": "ar",
  "success_url": "https://povito.com/ar/checkout/payment/return",
  "cancel_url": "https://povito.com/ar/checkout",
  "metadata": {
    "cart_id": "cart_01J8Z3K9Q4M2XA7B"
  }
}

Response 200 — sample from the schemajson

{
  "id": "cs_live_01J8Z3K9Q4M2XA7B",
  "object": "checkout.session",
  "code": "code",
  "url": "https://example.com",
  "livemode": true,
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "payment_method_types": [
    "cashondelivery"
  ],
  "customer": {
    "id": "id",
    "phone": "phone",
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "presentment": {
    "currency": "Currency",
    "fx_rate": 1
  },
  "payment": {
    "attempt_id": "attempt_id",
    "method": "cashondelivery",
    "gateway": "gateway",
    "gateway_reference": "gateway_reference",
    "captured_amount": 0,
    "captured_currency": "captured_currency",
    "presented_amount": 0,
    "presented_currency": "Currency",
    "fx_rate": 1,
    "captured_at": "2026-09-12T10:30:00Z",
    "instrument": {
      "brand": "brand",
      "last_four": "last_four"
    }
  },
  "refunded_amount": 0,
  "locale": "ar",
  "success_url": "https://example.com",
  "cancel_url": "https://example.com",
  "expires_at": "2026-09-12T10:30:00Z",
  "completed_at": "2026-09-12T10:30:00Z",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

Response 201 — sample from the schemajson

{
  "id": "cs_live_01J8Z3K9Q4M2XA7B",
  "object": "checkout.session",
  "code": "code",
  "url": "https://example.com",
  "livemode": true,
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "payment_method_types": [
    "cashondelivery"
  ],
  "customer": {
    "id": "id",
    "phone": "phone",
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "presentment": {
    "currency": "Currency",
    "fx_rate": 1
  },
  "payment": {
    "attempt_id": "attempt_id",
    "method": "cashondelivery",
    "gateway": "gateway",
    "gateway_reference": "gateway_reference",
    "captured_amount": 0,
    "captured_currency": "captured_currency",
    "presented_amount": 0,
    "presented_currency": "Currency",
    "fx_rate": 1,
    "captured_at": "2026-09-12T10:30:00Z",
    "instrument": {
      "brand": "brand",
      "last_four": "last_four"
    }
  },
  "refunded_amount": 0,
  "locale": "ar",
  "success_url": "https://example.com",
  "cancel_url": "https://example.com",
  "expires_at": "2026-09-12T10:30:00Z",
  "completed_at": "2026-09-12T10:30:00Z",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

GET `/checkout/sessions/{id}`#

getCheckoutSession · secretKey

Authoritative session state — the verify call

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`	pattern `^cs_(live\|test)_[A-Za-z0-9]+$`

Responses

Status	Meaning	Body
`200`	OK	`CheckoutSession`
`401`	Missing or invalid key	`ErrorEnvelope` · `Unauthorized`
`403`	Insufficient scope, mode mismatch, or suspended merchant	`ErrorEnvelope` · `Forbidden`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/checkout/sessions/{id}" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "cs_live_01J8Z3K9Q4M2XA7B",
  "object": "checkout.session",
  "code": "code",
  "url": "https://example.com",
  "livemode": true,
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "payment_method_types": [
    "cashondelivery"
  ],
  "customer": {
    "id": "id",
    "phone": "phone",
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "presentment": {
    "currency": "Currency",
    "fx_rate": 1
  },
  "payment": {
    "attempt_id": "attempt_id",
    "method": "cashondelivery",
    "gateway": "gateway",
    "gateway_reference": "gateway_reference",
    "captured_amount": 0,
    "captured_currency": "captured_currency",
    "presented_amount": 0,
    "presented_currency": "Currency",
    "fx_rate": 1,
    "captured_at": "2026-09-12T10:30:00Z",
    "instrument": {
      "brand": "brand",
      "last_four": "last_four"
    }
  },
  "refunded_amount": 0,
  "locale": "ar",
  "success_url": "https://example.com",
  "cancel_url": "https://example.com",
  "expires_at": "2026-09-12T10:30:00Z",
  "completed_at": "2026-09-12T10:30:00Z",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

POST `/checkout/sessions/{id}/expire`#

expireCheckoutSession · secretKey

Close an open session

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`	pattern `^cs_(live\|test)_[A-Za-z0-9]+$`

Responses

Status	Meaning	Body
`200`	Expired	`CheckoutSession`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`
`409`	Idempotency conflict, wrong state, or refund ceiling	`ErrorEnvelope` · `Conflict`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/checkout/sessions/{id}/expire" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "cs_live_01J8Z3K9Q4M2XA7B",
  "object": "checkout.session",
  "code": "code",
  "url": "https://example.com",
  "livemode": true,
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "payment_method_types": [
    "cashondelivery"
  ],
  "customer": {
    "id": "id",
    "phone": "phone",
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "presentment": {
    "currency": "Currency",
    "fx_rate": 1
  },
  "payment": {
    "attempt_id": "attempt_id",
    "method": "cashondelivery",
    "gateway": "gateway",
    "gateway_reference": "gateway_reference",
    "captured_amount": 0,
    "captured_currency": "captured_currency",
    "presented_amount": 0,
    "presented_currency": "Currency",
    "fx_rate": 1,
    "captured_at": "2026-09-12T10:30:00Z",
    "instrument": {
      "brand": "brand",
      "last_four": "last_four"
    }
  },
  "refunded_amount": 0,
  "locale": "ar",
  "success_url": "https://example.com",
  "cancel_url": "https://example.com",
  "expires_at": "2026-09-12T10:30:00Z",
  "completed_at": "2026-09-12T10:30:00Z",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

Payment methods

GET `/payment_methods`#

listPaymentMethods · secretKey

Methods this merchant may pass in payment_method_types, in display order

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`data`required	`array of PaymentMethod`

401 Missing or invalid key ErrorEnvelope · Unauthorized

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/payment_methods" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "data": [
    {
      "code": "cashondelivery",
      "display_name": {
        "ar": "ar",
        "ku": "ku",
        "en": "en"
      },
      "flow": "redirect",
      "currencies": [
        "Currency"
      ],
      "limits": {
        "key": {
          "min": null,
          "max": null
        }
      },
      "capabilities": {
        "refunds": "none",
        "saved_instruments": true,
        "wallets": [
          "apple_pay"
        ]
      },
      "enabled": true
    }
  ]
}

Refunds

GET `/refunds`#

listRefunds · secretKey

Parameters

Name	In	Type	Notes
`session_id`	`query`	`string`
`limit`	`query`	`integer`	default `20` · min 1 · max 100
`cursor`	`query`	`string`

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`data`required	`array of Refund`
`next_cursor`required	`string` \| `null`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/refunds" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "data": [
    {
      "id": "id",
      "object": "refund",
      "livemode": true,
      "session_id": "session_id",
      "attempt_id": "attempt_id",
      "amount": 0,
      "currency": "Currency",
      "reason": "reason",
      "initiated_by": "merchant",
      "status": "requested",
      "gateway_reference": "gateway_reference",
      "failure_reason": "failure_reason",
      "metadata": {
        "key": "string"
      },
      "created_at": "2026-09-12T10:30:00Z",
      "updated_at": "2026-09-12T10:30:00Z"
    }
  ],
  "next_cursor": "next_cursor"
}

POST `/refunds`#

createRefund · secretKey

Refund part or all of a paid session

Parameters

Name	In	Type	Notes
`Idempotency-Key`required	`header`	`string`	Same key + same body replays the first response; same key + different body is 409. A UUID is the usual choice pattern `^[A-Za-z0-9_-]{8,128}$`

Request body application/json · required

RefundCreate

Responses

Status	Meaning	Body
`201`	Created header `Idempotent-Replayed` — `IdempotentReplayed`	`Refund`
`400`	Validation error	`ErrorEnvelope` · `BadRequest`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`
`409`	Idempotency conflict, wrong state, or refund ceiling	`ErrorEnvelope` · `Conflict`
`422`	Business rule	`ErrorEnvelope` · `Unprocessable`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/refunds" \
  -H "Authorization: Bearer povito_ck_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "session_id",
  "amount": 0,
  "reason": "reason",
  "metadata": {
    "key": "string"
  }
}'

Request body — sample from the schemajson

{
  "session_id": "session_id",
  "amount": 0,
  "reason": "reason",
  "metadata": {
    "key": "string"
  }
}

Response 201 — sample from the schemajson

{
  "id": "id",
  "object": "refund",
  "livemode": true,
  "session_id": "session_id",
  "attempt_id": "attempt_id",
  "amount": 0,
  "currency": "Currency",
  "reason": "reason",
  "initiated_by": "merchant",
  "status": "requested",
  "gateway_reference": "gateway_reference",
  "failure_reason": "failure_reason",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

GET `/refunds/{id}`#

getRefund · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	OK	`Refund`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/refunds/{id}" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "id",
  "object": "refund",
  "livemode": true,
  "session_id": "session_id",
  "attempt_id": "attempt_id",
  "amount": 0,
  "currency": "Currency",
  "reason": "reason",
  "initiated_by": "merchant",
  "status": "requested",
  "gateway_reference": "gateway_reference",
  "failure_reason": "failure_reason",
  "metadata": {
    "key": "string"
  },
  "created_at": "2026-09-12T10:30:00Z",
  "updated_at": "2026-09-12T10:30:00Z"
}

Webhook endpoints

Endpoints belong to one mode. A key lists and manages only endpoints of its own mode; every /webhook_endpoints/{id} operation on an endpoint of the other mode returns 404 endpoint_not_found.

GET `/webhook_endpoints`#

listWebhookEndpoints · secretKey

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`data`required	`array of WebhookEndpoint`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "data": [
    {
      "id": "id",
      "object": "webhook_endpoint",
      "url": "https://example.com",
      "events": [
        "*"
      ],
      "mode": "live",
      "status": "enabled",
      "disabled_reason": "delivery_failures",
      "description": "description",
      "created_at": "2026-09-12T10:30:00Z"
    }
  ]
}

POST `/webhook_endpoints`#

createWebhookEndpoint · secretKey

Request body application/json · required

WebhookEndpointCreate

Responses

Status	Meaning	Body
`201`	Created — `secret` is present only in this response	`WebhookEndpointWithSecret`
`400`	Validation error	`ErrorEnvelope` · `BadRequest`
`422`	Business rule	`ErrorEnvelope` · `Unprocessable`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/webhook_endpoints" \
  -H "Authorization: Bearer povito_ck_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "description": "description"
}'

Request body — sample from the schemajson

{
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "description": "description"
}

Response 201 — sample from the schemajson

{
  "id": "id",
  "object": "webhook_endpoint",
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "status": "enabled",
  "disabled_reason": "delivery_failures",
  "description": "description",
  "created_at": "2026-09-12T10:30:00Z",
  "secret": "secret"
}

GET `/webhook_endpoints/{id}`#

getWebhookEndpoint · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	OK	`WebhookEndpoint`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/webhook_endpoints/{id}" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "id",
  "object": "webhook_endpoint",
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "status": "enabled",
  "disabled_reason": "delivery_failures",
  "description": "description",
  "created_at": "2026-09-12T10:30:00Z"
}

PATCH `/webhook_endpoints/{id}`#

updateWebhookEndpoint · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Request body application/json · required

Field	Type	Notes
`url`	`string` (uri)
`events`	`array of EventType`
`status`	`string`	one of `"enabled"`, `"disabled"`
`description`	`string`	max length 200

Responses

Status	Meaning	Body
`200`	OK	`WebhookEndpoint`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl -X PATCH "https://api.checkout.staging.povito.com/v1/webhook_endpoints/{id}" \
  -H "Authorization: Bearer povito_ck_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "status": "enabled",
  "description": "description"
}'

Request body — sample from the schemajson

{
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "status": "enabled",
  "description": "description"
}

Response 200 — sample from the schemajson

{
  "id": "id",
  "object": "webhook_endpoint",
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "status": "enabled",
  "disabled_reason": "delivery_failures",
  "description": "description",
  "created_at": "2026-09-12T10:30:00Z"
}

DELETE `/webhook_endpoints/{id}`#

deleteWebhookEndpoint · secretKey

Delete an endpoint; its delivery history stays on the events

Deliveries to the endpoint stop at once. It is no longer listed or readable — 404 endpoint_not_found afterwards, including for a second DELETE — and receives no new events or redeliveries. Retries already scheduled for it are cancelled: they appear in GET /events/{id} deliveries with error: "endpoint_deleted" and no next_retry_at. Its signing secrets are destroyed. Past delivery attempts stay on the events they belong to. To pause deliveries instead, PATCH it with status: disabled.

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status	Meaning	Body
`204`	Deleted
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl -X DELETE "https://api.checkout.staging.povito.com/v1/webhook_endpoints/{id}" \
  -H "Authorization: Bearer povito_ck_test_..."

POST `/webhook_endpoints/{id}/rotate_secret`#

rotateWebhookSecret · secretKey

Issue a new secret; the old one is accepted for 24 hours

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	OK	`WebhookEndpointWithSecret`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/webhook_endpoints/{id}/rotate_secret" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "id",
  "object": "webhook_endpoint",
  "url": "https://example.com",
  "events": [
    "*"
  ],
  "mode": "live",
  "status": "enabled",
  "disabled_reason": "delivery_failures",
  "description": "description",
  "created_at": "2026-09-12T10:30:00Z",
  "secret": "secret"
}

POST `/webhook_endpoints/{id}/test`#

sendTestWebhook · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Request body application/json · required

Field	Type	Notes
`type`required	`EventType`

Responses

Status Meaning Body

202

Queued

inline schema

Field	Type	Notes
`event_id`	`string`

404 Not found (also returned for another merchant's objects) ErrorEnvelope · NotFound

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/webhook_endpoints/{id}/test" \
  -H "Authorization: Bearer povito_ck_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "*"
}'

Request body — sample from the schemajson

{
  "type": "*"
}

Response 202 — sample from the schemajson

{
  "event_id": "event_id"
}

Events

GET `/events`#

listEvents · secretKey

Parameters

Name	In	Type	Notes
`type`	`query`	`EventType`
`since`	`query`	`string` (date-time)
`limit`	`query`	`integer`	default `20` · min 1 · max 100
`cursor`	`query`	`string`

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`data`required	`array of Event`
`next_cursor`required	`string` \| `null`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/events" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "data": [
    {
      "id": "id",
      "object": "event",
      "type": "*",
      "livemode": true,
      "created_at": "2026-09-12T10:30:00Z",
      "data": {
        "object": null
      }
    }
  ],
  "next_cursor": "next_cursor"
}

GET `/events/{id}`#

getEvent · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	OK	`EventWithDeliveries`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/events/{id}" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 200 — sample from the schemajson

{
  "id": "id",
  "object": "event",
  "type": "*",
  "livemode": true,
  "created_at": "2026-09-12T10:30:00Z",
  "data": {
    "object": null
  },
  "deliveries": [
    {
      "endpoint_id": "endpoint_id",
      "attempt_no": 1,
      "status_code": 1,
      "error": "error",
      "delivered_at": "2026-09-12T10:30:00Z",
      "next_retry_at": "2026-09-12T10:30:00Z"
    }
  ]
}

POST `/events/{id}/redeliver`#

redeliverEvent · secretKey

Parameters

Name	In	Type	Notes
`id`required	`path`	`string`

Responses

Status Meaning Body

202

Queued to every matching endpoint

inline schema

Field	Type	Notes
`endpoints`required	`integer`	How many endpoints will receive it

404 Not found (also returned for another merchant's objects) ErrorEnvelope · NotFound

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/events/{id}/redeliver" \
  -H "Authorization: Bearer povito_ck_test_..."

Response 202 — sample from the schemajson

{
  "endpoints": 1
}

Public

GET `/public/sessions/{code}`#

publicGetSession · publishableKey

Page data for the hosted checkout and the drop-in

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`
`X-Povito-Customer-Token`	`header`	`string`	When valid for this session, the response carries the saved `profile`

Responses

Status	Meaning	Body
`200`	OK	`PublicSession`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`
`410`	`session_expired` or `session_canceled`	`ErrorEnvelope`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/public/sessions/{code}" \
  -H "Authorization: Bearer povito_pk_test_..."

Response 200 — sample from the schemajson

{
  "code": "code",
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "merchant": {
    "display_name": "display_name",
    "logo_url": "https://example.com",
    "accent": "accent"
  },
  "methods": [
    {
      "code": null,
      "display_name": {
        "ar": null,
        "ku": null,
        "en": null
      },
      "flow": "redirect",
      "currencies": [
        null
      ],
      "limits": {
        "key": null
      },
      "capabilities": {
        "refunds": null,
        "saved_instruments": null,
        "wallets": null
      },
      "enabled": true,
      "available": true,
      "unavailable_reason": "unavailable_reason",
      "presented_amount": 0,
      "presented_currency": "Currency"
    }
  ],
  "customer": {
    "phone": "phone",
    "phone_verified": true,
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "locale": "ar",
  "expires_at": "2026-09-12T10:30:00Z",
  "cancel_url": "https://example.com",
  "livemode": true,
  "profile": {
    "name": "name",
    "addresses": [
      null
    ],
    "instruments": [
      null
    ]
  }
}

POST `/public/sessions/{code}/otp`#

publicRequestOtp · publishableKey

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

Request body application/json · required

Field	Type	Notes
`phone`required	`PhoneE164`

Responses

Status Meaning Body

202

Sent

inline schema

Field	Type	Notes
`sent`required	`boolean`
`retry_after`required	`integer`	Seconds before a resend is accepted

429

Too many requests

header Retry-After

ErrorEnvelope · RateLimited

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/otp" \
  -H "Authorization: Bearer povito_pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+9647800000000"
}'

Request body — sample from the schemajson

{
  "phone": "+9647800000000"
}

Response 202 — sample from the schemajson

{
  "sent": true,
  "retry_after": 1
}

POST `/public/sessions/{code}/otp/verify`#

publicVerifyOtp · publishableKey

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

Request body application/json · required

Field	Type	Notes
`phone`required	`PhoneE164`
`code`required	`string`	pattern `^[0-9]{6}$`

Responses

Status Meaning Body

200

Verified — a session-scoped customer token

inline schema

Field	Type	Notes
`customer_token`required	`string`
`expires_at`required	`string` (date-time)
`profile`	`PublicCustomerProfile`

400 Validation error ErrorEnvelope · BadRequest

429

Too many requests

header Retry-After

ErrorEnvelope · RateLimited

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/otp/verify" \
  -H "Authorization: Bearer povito_pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+9647800000000",
  "code": "code"
}'

Request body — sample from the schemajson

{
  "phone": "+9647800000000",
  "code": "code"
}

Response 200 — sample from the schemajson

{
  "customer_token": "customer_token",
  "expires_at": "2026-09-12T10:30:00Z",
  "profile": {
    "name": "name",
    "addresses": [
      {
        "governorate": "governorate",
        "city": "city",
        "line": "line",
        "landmark": "landmark",
        "country": "IQ",
        "geo": {
          "lat": null,
          "lng": null
        }
      }
    ],
    "instruments": [
      {
        "id": "id",
        "object": "instrument",
        "gateway": "gateway",
        "brand": "brand",
        "last_four": "last_four",
        "expiry": "expiry",
        "status": "active"
      }
    ]
  }
}

PUT `/public/sessions/{code}/customer`#

publicSetCustomer · publishableKey + customerToken

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

Request body application/json · required

Field	Type	Notes
`name`	`string`	max length 120
`address`	`Address`

Responses

Status	Meaning	Body
`200`	OK	`PublicSession`
`400`	Validation error	`ErrorEnvelope` · `BadRequest`

Examples

Sandboxbash

curl -X PUT "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/customer" \
  -H "Authorization: Bearer povito_pk_test_..." \
  -H "X-Povito-Customer-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "name",
  "address": {
    "governorate": "governorate",
    "city": "city",
    "line": "line",
    "landmark": "landmark",
    "country": "IQ",
    "geo": {
      "lat": 1.5,
      "lng": 1.5
    }
  }
}'

Request body — sample from the schemajson

{
  "name": "name",
  "address": {
    "governorate": "governorate",
    "city": "city",
    "line": "line",
    "landmark": "landmark",
    "country": "IQ",
    "geo": {
      "lat": 1.5,
      "lng": 1.5
    }
  }
}

Response 200 — sample from the schemajson

{
  "code": "code",
  "status": "open",
  "payment_status": "unpaid",
  "reference_id": "reference_id",
  "amount": 0,
  "currency": "Currency",
  "line_items": [
    {
      "label": "label",
      "amount": 0,
      "quantity": 1,
      "type": "charge"
    }
  ],
  "merchant": {
    "display_name": "display_name",
    "logo_url": "https://example.com",
    "accent": "accent"
  },
  "methods": [
    {
      "code": null,
      "display_name": {
        "ar": null,
        "ku": null,
        "en": null
      },
      "flow": "redirect",
      "currencies": [
        null
      ],
      "limits": {
        "key": null
      },
      "capabilities": {
        "refunds": null,
        "saved_instruments": null,
        "wallets": null
      },
      "enabled": true,
      "available": true,
      "unavailable_reason": "unavailable_reason",
      "presented_amount": 0,
      "presented_currency": "Currency"
    }
  ],
  "customer": {
    "phone": "phone",
    "phone_verified": true,
    "name": "name",
    "address": {
      "governorate": "governorate",
      "city": "city",
      "line": "line",
      "landmark": "landmark",
      "country": "IQ",
      "geo": {
        "lat": null,
        "lng": null
      }
    }
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "locale": "ar",
  "expires_at": "2026-09-12T10:30:00Z",
  "cancel_url": "https://example.com",
  "livemode": true,
  "profile": {
    "name": "name",
    "addresses": [
      null
    ],
    "instruments": [
      null
    ]
  }
}

POST `/public/sessions/{code}/attempts`#

publicCreateAttempt · publishableKey + customerToken

Choose a method and start a payment attempt

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

Request body application/json · required

Field	Type	Notes
`method`required	`MethodCode`
`instrument_id`	`string`
`save_instrument`	`boolean`	default `false`

Responses

Status	Meaning	Body
`201`	Attempt started	`AttemptStart`
`409`	Idempotency conflict, wrong state, or refund ceiling	`ErrorEnvelope` · `Conflict`
`422`	Business rule	`ErrorEnvelope` · `Unprocessable`

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/attempts" \
  -H "Authorization: Bearer povito_pk_test_..." \
  -H "X-Povito-Customer-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "cashondelivery",
  "instrument_id": "instrument_id",
  "save_instrument": false
}'

Request body — sample from the schemajson

{
  "method": "cashondelivery",
  "instrument_id": "instrument_id",
  "save_instrument": false
}

Response 201 — sample from the schemajson

{
  "attempt_id": "attempt_id",
  "kind": "redirect",
  "redirect_url": "https://example.com",
  "form_post": {
    "key": "string"
  },
  "present": {
    "qr_code": "qr_code",
    "readable_code": "readable_code",
    "personal_app_link": "https://example.com",
    "business_app_link": "https://example.com",
    "valid_until": "2026-09-12T10:30:00Z"
  }
}

GET `/public/sessions/{code}/attempts/{attempt_id}`#

publicGetAttempt · publishableKey

Poll an attempt; also triggers active reconciliation with the vendor

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`
`attempt_id`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	OK	`AttemptPoll`
`404`	Not found (also returned for another merchant's objects)	`ErrorEnvelope` · `NotFound`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/attempts/{attempt_id}" \
  -H "Authorization: Bearer povito_pk_test_..."

Response 200 — sample from the schemajson

{
  "attempt_id": "attempt_id",
  "code": "code",
  "method": "cashondelivery",
  "status": "created",
  "session_status": "open",
  "payment_status": "unpaid",
  "redirect_to": "https://example.com",
  "failure_reason": "failure_reason",
  "present": {
    "qr_code": "qr_code",
    "readable_code": "readable_code",
    "personal_app_link": "https://example.com",
    "business_app_link": "https://example.com",
    "valid_until": "2026-09-12T10:30:00Z"
  },
  "cancel_url": "https://example.com"
}

GET `/public/attempts/{attempt_id}`#

publicGetAttemptById · publishableKey

Attempt lookup without the session code — for the return page on any browser

Parameters

Name	In	Type	Notes
`attempt_id`required	`path`	`string`

Responses

Status Meaning Body

200

inline schema

All fields of AttemptPoll, plus:

Field Type Notes

attempt_idrequired string

coderequired string

methodrequired MethodCode

statusrequired AttemptStatus

session_statusrequired SessionStatus

payment_statusrequired PaymentStatus

redirect_torequired string | null (uri) success_url with session_id and reference_id appended once the session completed; never a status

failure_reasonrequired string | null

presentrequired

object | null

Re-shown on reload for present flows (FIB QR). qr_code is a data URI image.

fields

Field	Type	Notes
`qr_code`	`string`
`readable_code`	`string`
`personal_app_link`	`string` (uri)
`business_app_link`	`string` (uri)
`valid_until`	`string` (date-time)

cancel_urlrequired string | null (uri)

merchantrequired

object

fields

Field	Type	Notes
`display_name`	`string`
`logo_url`	`string` \| `null` (uri)

localerequired Locale

livemoderequired boolean

404 Not found (also returned for another merchant's objects) ErrorEnvelope · NotFound

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/public/attempts/{attempt_id}" \
  -H "Authorization: Bearer povito_pk_test_..."

Response 200 — sample from the schemajson

{
  "attempt_id": "attempt_id",
  "code": "code",
  "method": "cashondelivery",
  "status": "created",
  "session_status": "open",
  "payment_status": "unpaid",
  "redirect_to": "https://example.com",
  "failure_reason": "failure_reason",
  "present": {
    "qr_code": "qr_code",
    "readable_code": "readable_code",
    "personal_app_link": "https://example.com",
    "business_app_link": "https://example.com",
    "valid_until": "2026-09-12T10:30:00Z"
  },
  "cancel_url": "https://example.com",
  "merchant": {
    "display_name": "display_name",
    "logo_url": "https://example.com"
  },
  "locale": "ar",
  "livemode": true
}

POST `/public/sessions/{code}/cancel`#

publicCancelSession · publishableKey

Parameters

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

Responses

Status Meaning Body

200

Canceled

inline schema

Field	Type	Notes
`redirect_to`	`string` \| `null` (uri)

409 Idempotency conflict, wrong state, or refund ceiling ErrorEnvelope · Conflict

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/public/sessions/{code}/cancel" \
  -H "Authorization: Bearer povito_pk_test_..."

Response 200 — sample from the schemajson

{
  "redirect_to": "https://example.com"
}

GET `/public/test-gateway/{attempt_id}`#

publicTestGatewayDescribe · publishableKey

Test mode only — what the simulated vendor page shows

Parameters

Name	In	Type	Notes
`attempt_id`required	`path`	`string`

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`attempt_id`required	`string`
`status`required	`AttemptStatus`
`amount`required	`MinorUnits`
`currency`required	`Currency`
`method`required	`MethodCode`
`return_url`required	`string` (uri)

403 Insufficient scope, mode mismatch, or suspended merchant ErrorEnvelope · Forbidden

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/public/test-gateway/{attempt_id}" \
  -H "Authorization: Bearer povito_pk_test_..."

Response 200 — sample from the schemajson

{
  "attempt_id": "attempt_id",
  "status": "created",
  "amount": 0,
  "currency": "Currency",
  "method": "cashondelivery",
  "return_url": "https://example.com"
}

POST `/public/test-gateway/{attempt_id}/decide`#

publicTestGatewayDecide · publishableKey

Test mode only — the simulated vendor page's Succeed / Fail / Cancel / Slow buttons

Parameters

Name	In	Type	Notes
`attempt_id`required	`path`	`string`

Request body application/json · required

Field	Type	Notes
`decision`required	`string`	one of `"succeeded"`, `"failed"`, `"canceled"`, `"slow"`

Responses

Status Meaning Body

200

Decision applied and the attempt verified

inline schema

Field	Type	Notes
`attempt_id`	`string`
`status`	`AttemptStatus`
`return_url`	`string` (uri)

403 Insufficient scope, mode mismatch, or suspended merchant ErrorEnvelope · Forbidden

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/public/test-gateway/{attempt_id}/decide" \
  -H "Authorization: Bearer povito_pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "succeeded"
}'

Request body — sample from the schemajson

{
  "decision": "succeeded"
}

Response 200 — sample from the schemajson

{
  "attempt_id": "attempt_id",
  "status": "created",
  "return_url": "https://example.com"
}

POST `/callbacks/{mode}/{gateway}`#

vendorCallback · no auth internal

Vendor callback target. A hint only — the attempt is verified against the vendor's status API before anything changes.

Parameters

Name	In	Type	Notes
`mode`required	`path`	`string`	one of `"live"`, `"test"`
`gateway`required	`path`	`string`

Responses

Status	Meaning	Body
`200`	Received
`401`	Signature rejected

Examples

Sandboxbash

curl -X POST "https://api.checkout.staging.povito.com/v1/callbacks/{mode}/{gateway}"

Health

GET `/health`#

getHealth · no auth

Liveness and the list of registered gateways (names only)

Responses

Status Meaning Body

200

inline schema

Field	Type	Notes
`status`required	`string`	one of `"ok"`
`version`required	`string`
`gateways`required	`array of string`

Examples

Sandboxbash

curl "https://api.checkout.staging.povito.com/v1/health"

Response 200 — sample from the schemajson

{
  "status": "ok",
  "version": "version",
  "gateways": [
    "gateways"
  ]
}

Shared parameters#

`IdempotencyKey`#

Name	In	Type	Notes
`Idempotency-Key`required	`header`	`string`	Same key + same body replays the first response; same key + different body is 409. A UUID is the usual choice pattern `^[A-Za-z0-9_-]{8,128}$`

`SessionId`#

Name	In	Type	Notes
`id`required	`path`	`string`	pattern `^cs_(live\|test)_[A-Za-z0-9]+$`

`SessionCode`#

Name	In	Type	Notes
`code`required	`path`	`string`	pattern `^[A-Z0-9]{8,32}$`

`Limit`#

Name	In	Type	Notes
`limit`	`query`	`integer`	default `20` · min 1 · max 100

`Cursor`#

Name	In	Type	Notes
`cursor`	`query`	`string`

Response headers#

`IdempotentReplayed`#

boolean — Present and true when this response was replayed from the idempotency store

Error responses#

Name	Meaning	Body
`BadRequest`	Validation error	`ErrorEnvelope`
`Unauthorized`	Missing or invalid key	`ErrorEnvelope`
`Forbidden`	Insufficient scope, mode mismatch, or suspended merchant	`ErrorEnvelope`
`NotFound`	Not found (also returned for another merchant's objects)	`ErrorEnvelope`
`Conflict`	Idempotency conflict, wrong state, or refund ceiling	`ErrorEnvelope`
`Unprocessable`	Business rule	`ErrorEnvelope`
`RateLimited`	Too many requests header `Retry-After`	`ErrorEnvelope`

Schemas#

`ErrorEnvelope`#

Field Type Notes

errorrequired

object

fields

Field Type Notes

coderequired

string

one of "validation_error", "idempotency_key_required", "amount_mismatch", "unsupported_currency", "invalid_api_key", "invalid_publishable_key", "insufficient_scope", "mode_mismatch", "merchant_suspended", "session_not_found", "attempt_not_found", "refund_not_found", "endpoint_not_found", "event_not_found", "idempotency_key_conflict", "session_not_open", "session_canceled", "attempt_in_progress", "refund_exceeds_captured", "method_not_enabled", "method_not_available", "method_not_refundable", "return_host_not_allowed", "expiry_out_of_range", "session_expired", "phone_not_verified", "otp_invalid", "otp_expired", "otp_locked", "forbidden", "rate_limited", "gateway_error", "gateway_not_configured", "internal_error"

messagerequired string

details

array of object

fields

Field	Type	Notes
`field`required	`string`
`issue`required	`string`

request_idrequired string

`Currency`#

ISO 4217. Amounts are minor units per TRANSACTED_EXPONENT (IQD = whole dinars, USD = cents)

string — ISO 4217. Amounts are minor units per TRANSACTED_EXPONENT (IQD = whole dinars, USD = cents)
pattern ^[A-Z]{3}$

`MinorUnits`#

Integer minor units of the stated currency

integer — Integer minor units of the stated currency
min 0

`PhoneE164`#

string
pattern ^\+[1-9][0-9]{6,14}$ · e.g. "+9647800000000"

`Locale`#

string
one of "ar", "ku", "en"

`MethodCode`#

PAYMENT_METHOD_CODES from povito-contracts plus card, apple_pay, google_pay, test

string — PAYMENT_METHOD_CODES from povito-contracts plus card, apple_pay, google_pay, test
one of "cashondelivery", "fib", "fib_card", "zaincash", "qicard", "fastpay", "nasspay", "asiapay", "stripe", "card", "apple_pay", "google_pay", "test"

`SessionStatus`#

string
one of "open", "processing", "completed", "expired", "canceled"

`PaymentStatus`#

string
one of "unpaid", "paid", "requires_offline_collection", "failed", "partially_refunded", "refunded"

`AttemptStatus`#

string
one of "created", "initiated", "redirected", "presented", "charging", "verifying", "succeeded", "failed", "canceled", "expired"

`LineItem`#

Field	Type	Notes
`label`required	`string`	max length 200
`amount`required	`MinorUnits`
`quantity`	`integer`	default `1` · min 1
`type`required	`string`	charge, shipping and fee add; discount subtracts; the net must equal the session amount one of `"charge"`, `"shipping"`, `"fee"`, `"discount"`

`Address`#

Field Type Notes

governorate string Iraqi governorate code (GovernorateCode in povito-contracts)

city

string

max length 120

line

string

max length 240

landmark

string

max length 240

country

string

default "IQ" · pattern ^[A-Z]{2}$

geo

object

fields

Field	Type	Notes
`lat`	`number`
`lng`	`number`

`CustomerInput`#

Field	Type	Notes
`phone`	`PhoneE164`
`name`	`string`	max length 120
`address`	`Address`

`Collect`#

Field	Type	Notes
`phone`	`string`	one of `"required"`, `"optional"`, `"none"` · default `"required"`
`name`	`string`	one of `"required"`, `"optional"`, `"none"` · default `"required"`
`shipping_address`	`string`	one of `"required"`, `"optional"`, `"none"` · default `"none"`

`Presentment`#

Only for methods that cannot present the session currency (Stripe presents USD). The rate is snapshotted and reported, never recomputed.

Field	Type	Notes
`currency`required	`Currency`
`fx_rate`required	`integer`	Micro-units — 1_000_000 = 1.0; session currency per presentment currency min 1

`CheckoutSessionCreate`#

Field	Type	Notes
`reference_id`required	`string`	min length 1 · max length 128
`amount`required	`MinorUnits`
`currency`required	`Currency`
`line_items`required	`array of LineItem`	at least 1 item
`payment_method_types`	`array of MethodCode`	Default is every enabled method for this merchant that supports the currency
`customer`	`CustomerInput`
`collect`	`Collect`
`presentment`	`Presentment`
`locale`	`Locale`
`success_url`required	`string` (uri)	Host must be on the merchant's allowed list; no status is appended
`cancel_url`	`string` (uri)
`expires_at`	`string` (date-time)	Default +60 min; min +5 min; max +24 h
`metadata`	`map of string`	at most 20 keys

`PaymentDetails`#

For cash on delivery (payment_status requires_offline_collection) captured_amount and captured_currency are null — no money moved

Field Type Notes

attempt_idrequired string

methodrequired MethodCode

gatewayrequired string

gateway_referencerequired string

captured_amountrequired

integer | null

min 0

captured_currencyrequired

string | null

pattern ^[A-Z]{3}$

presented_amountrequired MinorUnits

presented_currencyrequired Currency

fx_rate integer | null Micro-units

captured_atrequired string (date-time)

instrument

object | null

fields

Field	Type	Notes
`brand`	`string`
`last_four`	`string`	pattern `^[0-9]{4}$`

`CheckoutSession`#

Field Type Notes

idrequired

string

e.g. "cs_live_01J8Z3K9Q4M2XA7B"

objectrequired

string

one of "checkout.session"

coderequired string

urlrequired string (uri)

livemoderequired boolean

statusrequired SessionStatus

payment_statusrequired PaymentStatus

reference_idrequired string

amountrequired MinorUnits

currencyrequired Currency

line_itemsrequired array of LineItem

payment_method_typesrequired array of MethodCode

customerrequired

object

fields

Field	Type	Notes
`id`	`string` \| `null`
`phone`	`string` \| `null`
`name`	`string` \| `null`
`address`	`Address` or `null`

collect Collect

presentment Presentment or null

paymentrequired PaymentDetails or null

refunded_amount MinorUnits

locale Locale

success_urlrequired string (uri)

cancel_url string | null (uri)

expires_atrequired string (date-time)

completed_at string | null (date-time)

metadata map of string

created_atrequired string (date-time)

updated_atrequired string (date-time)

`PaymentMethod`#

Field Type Notes

coderequired MethodCode

display_namerequired

object

fields

Field	Type	Notes
`ar`required	`string`
`ku`required	`string`
`en`required	`string`

flowrequired

string

one of "redirect", "present", "charge", "offline"

currenciesrequired array of Currency

limits map of object

capabilitiesrequired

object

fields

Field	Type	Notes
`refunds`required	`string`	one of `"none"`, `"full"`, `"partial"`
`saved_instruments`required	`boolean`
`wallets`	`array of string`

enabledrequired boolean

`RefundCreate`#

Field	Type	Notes
`session_id`required	`string`
`amount`required	`MinorUnits`
`reason`required	`string`	min length 10 · max length 1500
`metadata`	`map of string`

`Refund`#

Field	Type	Notes
`id`required	`string`
`object`required	`string`	one of `"refund"`
`livemode`required	`boolean`
`session_id`required	`string`
`attempt_id`required	`string`
`amount`required	`MinorUnits`
`currency`required	`Currency`
`reason`required	`string`
`initiated_by`required	`string`	one of `"merchant"`, `"povito_admin"`
`status`required	`string`	one of `"requested"`, `"processing"`, `"succeeded"`, `"failed"`, `"rejected"`
`gateway_reference`	`string` \| `null`
`failure_reason`	`string` \| `null`
`metadata`	`map of string`
`created_at`required	`string` (date-time)
`updated_at`	`string` (date-time)

`EventType`#

string
one of "*", "checkout.session.completed", "checkout.session.expired", "checkout.session.canceled", "payment.attempt.failed", "refund.succeeded", "refund.failed", "customer.instrument.saved", "customer.instrument.revoked"

`WebhookEndpointCreate`#

Field	Type	Notes
`url`required	`string` (uri)	HTTPS only; private-network targets are refused
`events`required	`array of EventType`	at least 1 item
`mode`required	`string`	one of `"live"`, `"test"`
`description`	`string`	max length 200

`WebhookEndpoint`#

Field	Type	Notes
`id`required	`string`
`object`required	`string`	one of `"webhook_endpoint"`
`url`required	`string` (uri)
`events`required	`array of EventType`
`mode`required	`string`	one of `"live"`, `"test"`
`status`required	`string`	one of `"enabled"`, `"disabled"`
`disabled_reason`	`string` \| `null`	one of `"delivery_failures"`, `"merchant"`, `null`
`description`	`string` \| `null`
`created_at`required	`string` (date-time)

`WebhookEndpointWithSecret`#

All fields of WebhookEndpoint, plus:

Field	Type	Notes
`id`required	`string`
`object`required	`string`	one of `"webhook_endpoint"`
`url`required	`string` (uri)
`events`required	`array of EventType`
`mode`required	`string`	one of `"live"`, `"test"`
`status`required	`string`	one of `"enabled"`, `"disabled"`
`disabled_reason`	`string` \| `null`	one of `"delivery_failures"`, `"merchant"`, `null`
`description`	`string` \| `null`
`created_at`required	`string` (date-time)
`secret`required	`string`	Shown once. Verify `Povito-Signature` with it

`Event`#

Field Type Notes

idrequired string

objectrequired

string

one of "event"

typerequired EventType

livemoderequired boolean

created_atrequired string (date-time)

datarequired

object

fields

Field	Type	Notes
`object`required	`CheckoutSession` or `Refund` or `Instrument`	checkout.session.* and payment.attempt.failed carry a CheckoutSession (the latter with an extra `failed_attempt` object); refund.* a Refund; customer.instrument.* an Instrument

`EventWithDeliveries`#

All fields of Event, plus:

Field Type Notes

idrequired string

objectrequired

string

one of "event"

typerequired EventType

livemoderequired boolean

created_atrequired string (date-time)

datarequired

object

fields

Field	Type	Notes
`object`required	`CheckoutSession` or `Refund` or `Instrument`	checkout.session.* and payment.attempt.failed carry a CheckoutSession (the latter with an extra `failed_attempt` object); refund.* a Refund; customer.instrument.* an Instrument

deliveries

array of object

fields

Field	Type	Notes
`endpoint_id`	`string`
`attempt_no`	`integer`
`status_code`	`integer` \| `null`
`error`	`string` \| `null`	`http_<status>`, `timeout`, a network error, or `endpoint_deleted` for an attempt cancelled because its endpoint was deleted
`delivered_at`	`string` \| `null` (date-time)
`next_retry_at`	`string` \| `null` (date-time)

`Instrument`#

Field	Type	Notes
`id`required	`string`
`object`required	`string`	one of `"instrument"`
`gateway`required	`string`
`brand`	`string` \| `null`
`last_four`	`string` \| `null`
`expiry`	`string` \| `null`	pattern `^[0-9]{2}/[0-9]{2}$`
`status`required	`string`	one of `"active"`, `"canceled"`

`PublicCustomerProfile`#

Field	Type	Notes
`name`	`string` \| `null`
`addresses`	`array of Address`
`instruments`	`array of Instrument`

`PublicSession`#

What the page may see — never metadata, never other sessions

Field Type Notes

coderequired string

statusrequired SessionStatus

payment_statusrequired PaymentStatus

reference_id string

amountrequired MinorUnits

currencyrequired Currency

line_itemsrequired array of LineItem

merchantrequired

object

fields

Field	Type	Notes
`display_name`required	`string`
`logo_url`	`string` \| `null` (uri)
`accent`	`string` \| `null`	Contrast-checked at save time pattern `^#[0-9a-fA-F]{6}$`

methodsrequired array of PaymentMethod + object

customer

object

fields

Field	Type	Notes
`phone`	`string` \| `null`
`phone_verified`	`boolean`
`name`	`string` \| `null`
`address`	`Address` or `null`

collectrequired Collect

localerequired Locale

expires_atrequired string (date-time)

cancel_url string | null (uri)

livemoderequired boolean

profilerequired PublicCustomerProfile or null The saved profile when a still-valid X-Povito-Customer-Token accompanies the read; null otherwise

`AttemptPoll`#

Field Type Notes

attempt_idrequired string

coderequired string

methodrequired MethodCode

statusrequired AttemptStatus

session_statusrequired SessionStatus

payment_statusrequired PaymentStatus

redirect_torequired string | null (uri) success_url with session_id and reference_id appended once the session completed; never a status

failure_reasonrequired string | null

presentrequired

object | null

Re-shown on reload for present flows (FIB QR). qr_code is a data URI image.

fields

Field	Type	Notes
`qr_code`	`string`
`readable_code`	`string`
`personal_app_link`	`string` (uri)
`business_app_link`	`string` (uri)
`valid_until`	`string` (date-time)

cancel_urlrequired string | null (uri)

`AttemptStart`#

Field Type Notes

attempt_idrequired string

kindrequired

string

one of "redirect", "present", "processing", "offline"

redirect_url string | null (uri)

form_post map of string | null When present the page must auto-submit an HTML form POST of exactly these fields to redirect_url instead of navigating (NassPay)

present

object | null

fields

Field	Type	Notes
`qr_code`	`string`
`readable_code`	`string`
`personal_app_link`	`string` (uri)
`business_app_link`	`string` (uri)
`valid_until`	`string` (date-time)

Examples#

`CreateMarketplaceSession`#

Marketplace order, method pre-selected in the storefront (Phase 1)

json

{
  "reference_id": "cart_01J8Z3K9Q4M2XA7B",
  "amount": 45000,
  "currency": "IQD",
  "line_items": [
    {
      "label": "Basket",
      "amount": 42000,
      "type": "charge"
    },
    {
      "label": "Delivery — Hi-Express",
      "amount": 5000,
      "type": "shipping"
    },
    {
      "label": "Coupon RAMADAN",
      "amount": 2000,
      "type": "discount"
    }
  ],
  "payment_method_types": [
    "zaincash"
  ],
  "customer": {
    "phone": "+9647800000000",
    "name": "Ali M. Ismail"
  },
  "collect": {
    "phone": "required",
    "name": "required",
    "shipping_address": "none"
  },
  "locale": "ar",
  "success_url": "https://povito.com/ar/checkout/payment/return",
  "cancel_url": "https://povito.com/ar/checkout",
  "metadata": {
    "cart_id": "cart_01J8Z3K9Q4M2XA7B"
  }
}

Povito extensions#

Values from x-povito in the contract — the webhook signing shape and retry schedule the webhooks guide documents.

json

{
  "decisions": [
    "D-44",
    "D-45",
    "D-46",
    "D-47",
    "D-48",
    "D-49",
    "D-50",
    "D-51"
  ],
  "webhook_signature": {
    "header": "Povito-Signature",
    "format": "t=<unix>,v1=<hex>",
    "algorithm": "HMAC-SHA256(secret, `${t}.${rawBody}`)",
    "tolerance_seconds": 300,
    "retry_schedule": [
      60,
      300,
      1800,
      7200,
      21600,
      86400,
      86400
    ]
  }
}

Base URLs#

Overview#

Authentication#

secretKey#

publishableKey#

customerToken#

Endpoints#

Parameters

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Responses

Examples

Parameters

Responses

Examples

Responses

Examples

Parameters

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Responses

Examples

Responses

Examples

Request body application/json · required

Responses

Examples

Parameters

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Responses

Examples

Parameters

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Responses

Examples

Parameters

Responses

Examples

Parameters

Responses

Examples

Parameters

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Request body application/json · required

Responses

Examples

Parameters

Request body application/json · required

`secretKey`#

`publishableKey`#

`customerToken`#

`IdempotencyKey`#