---
openapi: 3.0.3
info:
title: Inttegro API
description: Machine-readable reference for the public Inttegro API
version: 0.1.0-beta38
x-inttegro-collection-version: 0.1.0-beta38
contact:
name: Inttegro Engineering
url: "https://inttegro.com"
email: "engineering@inttegro.com"
servers:
- url: "https://api.inttegro.com"
description: Production
security:
- bearerAuth: []
paths:
/otp/initiate:
post:
summary: Initiate OTP transaction
description: |
Generate a one-time password and deliver it by SMS or email. Store the returned transaction ID
and use it with the recipient's submitted code at the verification endpoint. Retry an
uncertain initiation with the same idempotency key and body.
operationId: initiateOTP
tags:
- OTP
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateOTPRequest'
responses:
'200':
description: OTP transaction initiated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateOTPResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: OTP request was invalid, reused an existing idempotency key, or could not start a transaction
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/otp/verify:
post:
summary: Verify OTP token
description: |
Check the code submitted by the recipient and record the attempt. A completed request
returns a `pass` or `fail` verdict; retry an uncertain verification with the same
idempotency key and body.
operationId: verifyOTP
tags:
- OTP
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyOTPRequest'
responses:
'200':
description: Verification attempt completed (check verdict in response)
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyOTPResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: OTP verification was rejected by transaction state or could not be completed safely
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/otp/lookup:
post:
summary: Lookup OTP transaction
description: |
Retrieve the delivery, verification, and expiry state of an OTP transaction by ID.
The generated token is never returned by this endpoint.
operationId: lookupOTP
tags:
- OTP
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupOTPRequest'
responses:
'200':
description: OTP transaction retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/LookupOTPResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: OTP transaction was not found or could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/chimes/send:
post:
summary: Send a Chime
description: Send one SMS or email notification immediately.
operationId: sendChime
tags: [Chimes]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendChimeRequest'
responses:
'200':
description: Chime sent
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ChimeResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Referenced template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Referenced template is not usable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Chime could not be sent or the idempotency key conflicts
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Chime cooldown is active.
headers:
Retry-After:
description: Seconds until the same cooldown key can be used again.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Chime send failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Chime send hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/chimes/lookup:
post:
summary: Look up a Chime
description: Retrieve a sent Chime and its current transmission state.
operationId: lookupChime
tags: [Chimes]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupChimeRequest'
responses:
'200':
description: Chime found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ChimeResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Chime was not found or could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/chimes/page:
post:
summary: Page through Chimes
description: Retrieve Chimes, optionally filtered by customer or recipient address.
operationId: pageChimes
tags: [Chimes]
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PageChimesRequest'
responses:
'200':
description: Chime page found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PageChimesResponse'
'400':
description: Invalid page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Chime page request was invalid or the page could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/chimes/schedule:
post:
summary: Schedule Chimes
description: Schedule one or more SMS or email notifications for future delivery.
operationId: scheduleChime
tags: [Chimes]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleChimeRequest'
responses:
'200':
description: Chimes scheduled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Referenced template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Referenced template is not usable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Schedule could not be created or the idempotency key conflicts
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Scheduling failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Scheduling hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/chimes/broadcast:
post:
summary: Broadcast Chimes
description: Start an asynchronous SMS or email broadcast to one or more recipients.
operationId: broadcastChime
tags: [Chimes]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastRequest'
responses:
'202':
description: Broadcast accepted
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Referenced template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Referenced template is not usable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Broadcast could not be accepted or the idempotency key conflicts
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Broadcast creation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Broadcast creation hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/schedules/lookup:
post:
summary: Look up a scheduled Chime
operationId: lookupSchedule
tags: [Schedules]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupScheduleRequest'
responses:
'200':
description: Schedule found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleLookupResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Schedule was not found or could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/schedules/cancel:
post:
summary: Cancel a scheduled Chime
description: Cancel a schedule before execution wins the cancellation race.
operationId: cancelSchedule
tags: [Schedules]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelScheduleRequest'
responses:
'200':
description: Schedule canceled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleCancelResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Schedule was not found, already completed, already canceled, or could not be canceled safely
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/broadcasts/lookup:
post:
summary: Look up a broadcast
operationId: lookupBroadcast
tags: [Broadcasts]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupBroadcastRequest'
responses:
'200':
description: Broadcast found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/LookupBroadcastResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Broadcast was not found or could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/broadcasts/cancel:
post:
summary: Cancel a broadcast
description: Cancel a broadcast before execution wins the cancellation race.
operationId: cancelBroadcast
tags: [Broadcasts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelBroadcastRequest'
responses:
'200':
description: Broadcast canceled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastCancelResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Broadcast was not found, already completed, already canceled, or could not be canceled safely
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/create:
post:
summary: Create a message template
description: |
Creates an app-scoped reusable SMS or email message template. The API generates
the template `id`; clients must not supply an `id`, `template_id`, or template key.
operationId: createMessageTemplate
tags:
- Message Templates
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageTemplateRequest'
responses:
'200':
description: Message template created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Service unavailable - retryable create failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/update:
post:
summary: Update a message template
description: |
Updates a reusable message template and creates a new draft version. Published
versions remain stable until the draft is explicitly published.
operationId: updateMessageTemplate
tags:
- Message Templates
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMessageTemplateRequest'
responses:
'200':
description: Message template updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Message template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Message template is archived
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Service unavailable - retryable update failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/publish:
post:
summary: Publish a message template
description: Publishes the current draft version of a reusable message template.
operationId: publishMessageTemplate
tags:
- Message Templates
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateIDRequest'
responses:
'200':
description: Message template published successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Message template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Message template is archived
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Service unavailable - retryable publish failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/archive:
post:
summary: Archive a message template
description: Archives a reusable message template so it cannot be updated or used for new sends.
operationId: archiveMessageTemplate
tags:
- Message Templates
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateIDRequest'
responses:
'200':
description: Message template archived successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Message template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Service unavailable - retryable archive failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/lookup:
post:
summary: Look up a message template
description: Retrieves a reusable message template by its API-generated `id`.
operationId: lookupMessageTemplate
tags:
- Message Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateIDRequest'
responses:
'200':
description: Message template retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplateEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Message template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/page:
post:
summary: Page message templates
description: |
Retrieves app-scoped templates newest-updated first. Purpose and locale filters are
applied after selecting the backing page, so filtered results can be sparse.
operationId: pageMessageTemplates
tags:
- Message Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageMessageTemplatesRequest'
responses:
'200':
description: Message templates retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageTemplatesPageEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: No message-template page is available
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/message_templates/render_preview:
post:
summary: Render a message template preview
description: Renders a draft-aware preview of a reusable message template with bundled variables.
operationId: renderMessageTemplatePreview
tags:
- Message Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RenderMessageTemplatePreviewRequest'
responses:
'200':
description: Message template rendered successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/RenderMessageTemplatePreviewResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'400':
description: Bad request - validation failed or unsafe rendered output
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Message template not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Message template is archived
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/customers/create:
post:
summary: Create a customer
description: Create a reusable customer profile for orders and saved payment methods.
operationId: createCustomer
tags: [Customers]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerRequest'
responses:
'200':
description: Customer created
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Customer creation failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Customer creation or balance lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/lookup:
post:
summary: Look up a customer
operationId: lookupCustomer
tags: [Customers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupCustomerRequest'
responses:
'200':
description: Customer found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Customer not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Customer lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/update:
post:
summary: Update a customer
description: Replace any supplied customer profile fields while leaving omitted fields unchanged.
operationId: updateCustomer
tags: [Customers]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerRequest'
responses:
'200':
description: Customer updated
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Customer update failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Customer update or balance lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/page:
post:
summary: Page through customers
description: Retrieve a page of customers for the authenticated application.
operationId: pageCustomers
tags: [Customers]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageCustomersRequest'
responses:
'200':
description: Customer page found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
page:
$ref: '#/components/schemas/CustomerPage'
'400':
description: Invalid page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Customer page unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Customer page or balance lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/checkout/lookup:
post:
summary: Look up checkout
description: |
Retrieve either the current public checkout representation of a finalized Order or
the client-safe amount-selection policy for a Purchase Intent. Send exactly one
reference. A Purchase Intent lookup supports collecting an amount before creating
an Order. An Order lookup can also return its amount-selection policy when that
finalized Order still has an editable customer-selected price and payment has not
begun.
operationId: lookupCheckoutOrder
tags: [Checkout]
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLookupRequest'
responses:
'200':
description: Checkout Order or amount-selection policy found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLookupResponse'
'400':
description: Invalid checkout lookup request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Checkout reference was not found or cannot be used
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/checkout/select_amount:
post:
summary: Select an amount and prepare a checkout Order
description: |
Send exactly one checkout reference with the payer-selected amount. A
`purchase_intent_id` validates the Purchase Intent policy and creates the finalized
Order used by Checkout. An `order_id` validates the amount against that Order's
customer-selected price policy and updates the same Order while payment remains
pristine. The Order cannot be changed after payment begins. Suggested amounts are
conveniences, not an allow-list. Retry an uncertain request with the same
idempotency key and body.
operationId: selectCheckoutAmount
tags: [Checkout]
security: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSelectAmountRequest'
responses:
'200':
description: Finalized Checkout Order created, updated, or replayed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'400':
description: Invalid amount-selection request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Another request is currently using the same idempotency key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Purchase Intent or selected amount cannot be used
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Checkout Order preparation failed transiently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/checkout/pay:
post:
summary: Pay a checkout order
description: |
Attempt payment for a finalized Order without API-key authentication. The Order ID
identifies the immutable customer and commercial terms. A saved `payment_method_id`
must belong to that customer. Alternatively, provide new mobile-money details; new
billing details describe that payment method and do not replace the Order's shipping
address.
Retry an uncertain request with the same idempotency key and body.
operationId: payCheckoutOrder
tags: [Checkout]
security: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutPayRequest'
responses:
'200':
description: Checkout payment result
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'400':
description: Checkout payment request cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'409':
description: Another request is currently using the same idempotency key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: The idempotency key was reused with a different request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Checkout payment or idempotency storage failed transiently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'504':
description: Checkout payment timed out
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/checkout/confirm_payment:
post:
summary: Confirm a checkout payment
description: |
Submit the payer's confirmation token for a checkout payment that requires customer
confirmation. Retry an uncertain request with the same idempotency key and body.
operationId: confirmCheckoutPayment
tags: [Checkout]
security: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutConfirmPaymentRequest'
responses:
'200':
description: Checkout payment confirmation result
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'400':
description: Invalid checkout payment confirmation request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Another request is currently using the same idempotency key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Checkout payment confirmation failed or the idempotency key conflicts
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'503':
description: Checkout payment confirmation failed transiently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'504':
description: Checkout payment confirmation timed out
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/checkout/request_confirmation:
post:
summary: Request checkout payment confirmation
description: |
Ask Inttegro to send or resend the confirmation challenge required by the Order's
current payment. Retry an uncertain request with the same idempotency key and body.
operationId: requestCheckoutConfirmation
tags: [Checkout]
security: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderReferenceRequest'
responses:
'200':
description: Checkout confirmation request result
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'400':
description: Checkout confirmation request cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'409':
description: Another request is currently using the same idempotency key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: The idempotency key was reused with a different request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Checkout confirmation request or idempotency storage failed transiently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'504':
description: Checkout confirmation request timed out
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/orders/create:
post:
summary: Create a new order
description: |
Creates a new order in Inttegro. This endpoint supports two flows:
1. New customer flow: Provide `customer_data` to create a new customer and order
2. Existing customer flow: Provide `customer_id` and optionally `payment_method_id` for known customers
The order can be configured to execute payment immediately or require manual payment later.
operationId: createOrder
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateOrderNewCustomer'
- $ref: '#/components/schemas/CreateOrderExistingCustomer'
responses:
'200':
description: Order created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Another operation claimed or updated a resource before order creation could safely finish
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order creation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Order creation hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/lookup:
post:
summary: Lookup an order
description: Retrieves details of an existing order by its ID. The order may or may not exist.
operationId: lookupOrder
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order to lookup
example: "JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt"
responses:
'200':
description: Order found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
example:
order:
id: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
status: "completed"
initiated_at: "2025-09-14T16:24:41.137708909Z"
sealed_at: "2025-09-14T16:24:41.312701813Z"
completed_at: "2025-09-14T16:29:45Z"
line_item_group:
line_items:
type: "product"
product:
id: "BydaofEe1IdJro0BVjlm89PxeENo8GsqX09yVtBL"
name: "Gorgeous Granite Salad"
type: "physical"
price:
currency: "ghs"
value: 100
quantity: 1
tax_code: "pink"
custom_data:
size: "56"
color: "blue"
total:
currency: "ghs"
value: 200
payment:
id: "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl"
status: "paid"
statement_descriptor: "STATEMENT"
amount:
currency: "ghs"
value: 200
payment_method:
id: "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6"
customer_id: "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn"
type: "mobile_money"
mobile_money:
network: "mtn"
account_number: "0594870087"
verified: true
created_at: "2025-09-14T16:24:41.171905592Z"
latest_attempt:
payment_method_type: "mobile_money"
payment_method_id: "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6"
reference: "68c6ecbc3bf0a6548973b598"
status: "succeeded"
initiated_at: "2025-09-14T16:26:36.627271781Z"
succeeded_at: "2025-09-14T16:29:45Z"
initiated_at: "2025-09-14T16:24:41.240462376Z"
executed_at: "2025-09-14T16:26:36.626961042Z"
paid_at: "2025-09-14T16:29:45Z"
invoice_settings:
number: "INV-1001"
memo: "Thanks for your order."
footer: "Payment due within 7 days."
custom_data:
purchase_order: "PO-7"
customer:
id: "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn"
name: "Anita Segnom"
email_address: "yaw@konadu.ie"
phone_number: "+233559714200"
'400':
description: Order lookup failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
/orders/update:
post:
summary: Update an order
description: |
Updates mutable fields on an existing order and returns the same response shape as
`/orders/lookup`.
Use this endpoint to replace the order's full line item set, update the order number,
receipt number, invoice settings, or statement descriptor, replace order-level `custom_data`,
switch to a different saved payment method, tokenize a new payment method, clear the current
payment method, or explicitly open, seal, or reseal the order via `finalize`.
`line_items` is a full replacement field, not a sparse merge. `payment_method_id`,
`payment_method_data`, and `clear_payment_method` are mutually exclusive. `custom_data`
is metadata-only and does not require reopen or reseal by itself. Completed, paid,
canceled, and expired orders cannot be updated.
When mutating seal-sensitive fields on a sealed order, set `finalize: false` to
reopen the order and leave it editable, or set `finalize: true` to apply the changes
and reseal in the same request. If payment confirmation or execution has already
started, Inttegro rejects edits that would change the order's economics or payment
configuration.
operationId: updateOrder
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying the update twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
clear_payment_method:
type: boolean
description: |
Clears the currently attached payment method. Mutually exclusive with
`payment_method_id` and `payment_method_data`.
default: false
custom_data:
$ref: '#/components/schemas/CustomData'
invoice_settings:
$ref: '#/components/schemas/InvoiceSettings'
finalize:
type: boolean
description: |
Explicit seal decision. Set to `false` to reopen a sealed order and leave it
open, or `true` to seal or reseal the order after applying the requested
mutations.
line_items:
type: array
description: |
Full replacement for the order's line items. Omit this field to keep the
current line items unchanged.
items:
$ref: '#/components/schemas/LineItem'
number:
type: string
description: Replacement order number.
example: "ORDER-12345-REV2"
receipt_number:
type: string
description: |
Replacement receipt number. Once set, it cannot be unset; provide a
different non-empty value to change it. No uniqueness is enforced.
example: "RCPT-12345-REV2"
order_id:
type: string
description: Unique identifier of the order to update.
example: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
payment_method_data:
allOf:
- $ref: '#/components/schemas/PaymentMethodData'
description: |
New payment method details to tokenize and attach to the order. Currently
only `mobile_money` is supported for order updates. When using inline mobile
money details, include `billing_details.name` and
`billing_details.address.country`.
payment_method_id:
type: string
description: |
ID of a saved payment method to attach to the order. Mutually exclusive
with `payment_method_data` and `clear_payment_method`.
example: "pm_xyz123abc456"
statement_descriptor:
type: string
description: Replacement payment statement descriptor for the order's payment.
example: "ORDER 12345"
maxLength: 22
statement_descriptor_prefix:
type: string
description: Static prefix used to build the replacement descriptor as `prefix*order_id`. Mutually exclusive with `statement_descriptor`.
example: "LINE"
minLength: 2
maxLength: 10
responses:
'200':
description: Order updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Bad request - invalid parameters or mutation precondition not met
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/pay:
post:
summary: Pay for an order
description: |
Initiates payment for an existing order. Supports two payment flows:
1. Use saved payment method: Provide only `order_id` to charge a previously saved payment method
2. Provide new payment details: Include `payment_method_data` with payment information
operationId: payOrder
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without initiating payment twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order to pay
example: "GKj7A8lM5wEGRUvbqpI4bkDFsQvpqVyh5fqePNnb"
payment_method_data:
$ref: '#/components/schemas/PaymentMethodData'
payment_method_id:
type: string
description: ID of a saved payment method to use for this payment
example: "pm_xyz123abc456"
paid_out_of_band:
type: boolean
description: |
Set to true if payment was received outside Inttegro (cash, bank transfer, check).
Marks the payment as paid offline. Mutually exclusive with payment_method_id and
payment_method_data. Defaults to false.
default: false
example: false
responses:
'200':
description: Payment initiated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: Another operation updated or claimed the payment before this request could safely proceed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order payment failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Order payment hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/confirm_payment:
post:
summary: Confirm payment with token
description: Confirms a pending payment using a verification token (e.g., OTP sent to customer's phone)
operationId: confirmPayment
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without confirming the payment twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
- payment_id
- confirmation_id
- token
properties:
order_id:
type: string
description: Unique identifier of the order
example: "JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt"
payment_id:
type: string
description: Unique identifier of the payment being confirmed
example: "pay_123"
confirmation_id:
type: string
description: Unique identifier of the confirmation challenge
example: "conf_123"
token:
type: string
description: Verification token (OTP) sent to customer
example: "302673"
responses:
'200':
description: Payment confirmed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Invalid token or order
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: Another operation updated or claimed the payment before confirmation could safely finish
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'500':
description: Order payment confirmation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'503':
description: Order payment confirmation hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
/orders/request_confirmation:
post:
summary: Request payment confirmation
description: Requests a new confirmation token to be sent to the customer for payment verification
operationId: requestConfirmation
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without sending another confirmation request.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order
example: "kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi"
responses:
'200':
description: Confirmation request sent successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Order confirmation request is invalid or cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'500':
description: Order confirmation request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Order confirmation request hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
/orders/cancel:
post:
summary: Cancel an order
description: |
Cancels an existing order. `execute_refund` records whether a refund was requested
as part of the cancellation evidence; this endpoint does not move funds or create a refund.
operationId: cancelOrder
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without canceling the order twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order to cancel
reason:
type: string
description: Optional reason for cancelling the order
execute_refund:
type: boolean
description: Whether the cancellation evidence should record that a refund was requested. This does not execute a refund.
default: false
responses:
'200':
description: Order cancelled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'400':
description: Order cancellation request is invalid or cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'500':
description: Order cancellation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/finalize:
post:
summary: Finalize an order
description: |
Finalizes an order to make it ready for payment. This endpoint seals the current order
state and activates the hosted checkout page that you can share with customers.
Use this when you've finished building the cart and want to present it to the customer
for payment. The response includes the `sealed_at` timestamp marking when the order was
finalized. If you later need to change line items, payment method,
statement descriptor, or order number, use `/orders/update` with an explicit `finalize`
decision to reopen or reseal the order.
operationId: finalizeOrder
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without finalizing the order twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order to finalize
example: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
responses:
'200':
description: Order finalized successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
example:
order:
number: "ORDER-12345"
status: "requires_payment"
payment_id: "pay_xyz123abc456"
customer_id: "cus_abc123def456"
sealed_at: "2025-01-25T10:30:00Z"
initiated_at: "2025-01-25T10:25:00Z"
expires_at: "2025-02-01T10:25:00Z"
line_item_group:
line_items:
type: "product"
product:
id: "prod_123"
name: "Premium Widget"
quantity: 2
price:
currency: "GHS"
value: 5000
total:
currency: "GHS"
value: 10000
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Order finalization request is invalid or cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order finalization failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Order finalization hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/complete:
post:
summary: Complete an order
description: |
Marks an order as completed, transitioning it to the `completed` state. An order can only
be completed if its associated payment has been successfully paid.
Use the `paid_out_of_band` parameter when payment happened offline (outside the Inttegro
platform) to force the payment status to paid before completing the order. This is useful
for cash payments, bank transfers, or other out-of-band payment methods.
Once completed, the order status becomes `completed` and the `completed_at` timestamp is set.
operationId: completeOrder
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without completing the order twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order_id
properties:
order_id:
type: string
description: Unique identifier of the order to complete
example: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
paid_out_of_band:
type: boolean
description: |
Set to true if payment was received outside Inttegro
(e.g., cash, bank transfer, check). When true, the associated payment
will be marked as paid offline before completing the order.
default: false
example: false
responses:
'200':
description: Order completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
example:
order:
number: "ORDER-12345"
status: "completed"
payment_id: "pay_xyz123abc456"
customer_id: "cus_abc123def456"
completed_at: "2025-01-25T11:00:00Z"
sealed_at: "2025-01-25T10:30:00Z"
initiated_at: "2025-01-25T10:25:00Z"
expires_at: "2025-02-01T10:25:00Z"
line_item_group:
line_items:
type: "product"
product:
id: "prod_123"
name: "Premium Widget"
quantity: 2
price:
currency: "GHS"
value: 5000
total:
currency: "GHS"
value: 10000
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Order completion request is invalid or cannot be satisfied
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Another operation updated or claimed the payment before completion could safely finish
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order completion failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orders/send_invoice:
post:
summary: Send an order invoice
description: |
Sends the hosted invoice link for an existing order through Chime. The request
body contains only `order_id`; delivery options are resolved from the order
customer.
If the customer has both a phone number and an email address, Inttegro sends
both SMS and email Chimes. If only one contact method exists, Inttegro sends
to that channel. The order must be finalized before Inttegro can send the
hosted invoice link.
This is an idempotent endpoint. Send retry keys with the `Idempotency-Key`
header.
operationId: sendOrderInvoice
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without sending duplicate invoice Chimes.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryRequest'
responses:
'200':
description: Invoice link sent successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'207':
description: Partial success - at least one channel sent and at least one channel failed.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'400':
description: Bad request or unmet precondition. Possible codes include `draft_mode_order_has_no_invoice`, `order_delivery_contact_missing`, and `order_not_found`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order invoice delivery failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Transient delivery failure. Possible codes include `order_delivery_auth_failed`, `order_delivery_failed`, and `order_delivery_history_failed`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
/orders/send_receipt:
post:
summary: Send an order receipt
description: |
Sends the hosted receipt link for an existing paid order through Chime. The
request body contains only `order_id`; receipt delivery never uses the invoice
PDF path.
If the customer has both a phone number and an email address, Inttegro sends
both SMS and email Chimes. If only one contact method exists, Inttegro sends
to that channel. The order must be paid before a receipt can be sent.
This is an idempotent endpoint. Send retry keys with the `Idempotency-Key`
header.
operationId: sendOrderReceipt
tags:
- Orders
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without sending duplicate receipt Chimes.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryRequest'
responses:
'200':
description: Receipt link sent successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'207':
description: Partial success - at least one channel sent and at least one channel failed.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'400':
description: Bad request or unmet precondition. Possible codes include `order_delivery_contact_missing`, `order_not_found`, and `order_receipt_missing`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order receipt delivery failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Transient delivery failure. Possible codes include `order_delivery_auth_failed`, `order_delivery_failed`, and `order_delivery_history_failed`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentDeliveryResponse'
/orders/page:
post:
summary: Page through orders
description: |
Retrieve a paginated list of the most recent orders for the authenticated application.
Orders are sorted by `initiated_at` in descending order. Page numbers are
zero-based, so page 0 contains the freshest activity.
operationId: pageOrders
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- page_size
properties:
page_number:
type: integer
minimum: 0
maximum: 10
description: Zero-based page index to fetch (0-10 inclusive)
default: 0
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of orders per page (1-256)
customer_id:
type: string
description: |
When provided, restricts results to orders belonging
to this customer. The customer must belong to the
authenticated application.
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
page:
type: object
properties:
number:
type: integer
description: The page number returned
size:
type: integer
description: The number of orders in this page
orders:
type: array
items:
$ref: '#/components/schemas/Order'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Invalid order page request or precondition failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Order page lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Order page lookup failed transiently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/refunds/create:
post:
summary: Create a refund
description: |
Starts a refund for one or more paid order line items. Refund processing is
asynchronous: a successful request returns the new refund in `pending` status.
Retry an uncertain request with the same URL, idempotency key, and body.
operationId: createRefund
tags:
- Refunds
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRefundRequest'
responses:
'200':
description: Refund created
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/RefundResponse'
'400':
description: Invalid refund request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: The refund conflicts with current order or line-item state
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: The refund could not be accepted
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Refund creation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Refund creation hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/refunds/cancel:
post:
summary: Cancel a refund
description: |
Cancels a pending refund before processing claims it. Cancellation releases the
merchant balance hold and restores the refundable capacity reserved against its
order line items. An optional cancellation reason is retained with the refund.
Repeating cancellation returns the same canceled refund without replacing the
first successful reason or actor. Actor provenance is derived from authentication,
stored for audit, and omitted from the public request and Refund representation.
operationId: cancelRefund
tags:
- Refunds
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelRefundRequest'
responses:
'200':
description: Refund canceled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/RefundResponse'
'400':
description: Invalid refund cancellation request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Refund not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: Refund cannot be canceled or the idempotency key is still being processed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: The idempotency key was previously used with a different request body
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Refund cancellation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Refund cancellation or idempotency storage is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/refunds/lookup:
post:
summary: Look up a refund
description: Returns the current lifecycle state and amounts for one refund.
operationId: lookupRefund
tags:
- Refunds
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupRefundRequest'
responses:
'200':
description: Refund found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/RefundResponse'
'400':
description: Invalid refund lookup request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Refund not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Refund lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/refunds/page:
post:
summary: Page through refunds
description: Returns refunds in pages of the requested size. Page numbering starts at 1.
operationId: pageRefunds
tags:
- Refunds
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageRefundsRequest'
responses:
'200':
description: Refund page returned
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/RefundPageResponse'
'400':
description: Invalid refund page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'500':
description: Refund page lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Refund page lookup hit a transient dependency failure
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/apps/create:
post:
summary: Create an application
description: Creates an Inttegro application, initial secret key, and direct parent-child relationship for the authenticated creator app.
operationId: createApplication
tags:
- Apps
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
description: Display name for the application.
alias:
type: string
description: Optional short name for the application.
description:
type: string
description: Optional application description.
legal_entity_type:
type: string
description: Caller-defined legal-entity label. Common values are `government`, `non_profit`, `business`, and `individual`.
placement_parent_application_id:
type: string
description: Optional application under which the new app should be placed.
relationship_policy:
type: object
additionalProperties: false
description: Optional direct-placement relationship policy. Omitted values default to parent management and child credentials.
properties:
child_standing:
type: string
description: Initial standing assigned to the child in this relationship.
management:
type: string
enum:
- parent
- child
default: parent
description: Who can manage the child app and its resources through this relationship.
credentials:
type: string
enum:
- child
- parent
default: child
description: Who can create, rotate, or disable the child app's API keys after creation. Defaults to child. In V1, apps/create still returns the initial child key to the caller.
responses:
'200':
description: Application created successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
required:
- app
properties:
app:
type: object
required:
- id
- name
- created_at
- capabilities
properties:
id:
type: string
name:
type: string
alias:
type: string
description:
type: string
created_at:
type: string
format: date-time
capabilities:
$ref: '#/components/schemas/ApplicationCapabilityProjection'
secret_key:
type: object
properties:
id:
type: string
token_type:
type: string
issued_at:
type: string
format: date-time
token:
type: string
relationship:
type: object
description: Identifies the created app's direct placement relationship.
required: [created_at, id, kind, parent, status]
properties:
id:
type: string
kind:
type: string
enum:
- placement
parent:
type: object
additionalProperties: false
required: [id, name]
description: Application that directly contains the created app.
properties:
id:
type: string
name:
type: string
alias:
type: string
status:
type: string
enum:
- active
- inactive
- suspended
- revoked
created_at:
type: string
format: date-time
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Application request was invalid or creation could not be completed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/apps/capabilities:
post:
summary: Retrieve the authenticated application's commerce capabilities
description: Returns the current payment and payout capability states for the authenticated application. Restricted states include the public reason and the requirements currently due.
operationId: lookupApplicationCapabilities
tags:
- Apps
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: false
responses:
'200':
description: Application capabilities retrieved successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationCapabilitiesResponse'
'400':
description: Application capabilities request was invalid.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authorization is required.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'403':
description: Application-scoped authorization is required or the capability endpoint is not enabled for this application.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: The application's required capability configuration is unavailable or invalid.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Application capabilities are temporarily unavailable.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/apps/lookup:
post:
summary: Retrieve the authenticated application
description: Retrieves the application associated with the API key used to authenticate the request.
operationId: lookupApplication
tags:
- Apps
responses:
'200':
description: Application retrieved successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
required:
- app
properties:
app:
type: object
required:
- id
- name
- created_at
- capabilities
properties:
id:
type: string
name:
type: string
alias:
type: string
description:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
archived_at:
type: string
format: date-time
capabilities:
$ref: '#/components/schemas/ApplicationCapabilityProjection'
relationship:
type: object
description: Identifies the authenticated app's direct placement relationship. Omitted for root apps.
required: [created_at, id, kind, parent, status]
properties:
id:
type: string
kind:
type: string
enum:
- placement
parent:
type: object
additionalProperties: false
required: [id, name]
description: Application that directly contains the authenticated app.
properties:
id:
type: string
name:
type: string
alias:
type: string
status:
type: string
enum:
- active
- inactive
- suspended
- revoked
created_at:
type: string
format: date-time
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Application details could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/apps/update:
post:
summary: Update the authenticated application
description: Updates one or more mutable attributes of the application associated with the API key used to authenticate the request.
operationId: updateApplication
tags:
- Apps
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
minProperties: 1
additionalProperties: false
properties:
name:
type: string
description: Display name for the application. Cannot be empty.
alias:
type: string
description: Short name for the application. Use an empty string to clear it.
description:
type: string
description: Application description. Use an empty string to clear it.
legal_entity_type:
type: string
description: Caller-defined legal-entity label. Send an empty string to clear it.
responses:
'200':
description: Application updated successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
required:
- app
properties:
app:
type: object
required:
- id
- name
- created_at
- capabilities
properties:
id:
type: string
name:
type: string
alias:
type: string
description:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
capabilities:
$ref: '#/components/schemas/ApplicationCapabilityProjection'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Application request was invalid or changes could not be saved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/generate:
post:
summary: Generate a secret key
description: |
Generates a new active secret key for the authenticated application. The full bearer
token is returned only in this response and cannot be retrieved later. Store it before
returning success from your provisioning flow. Existing keys remain active, and this
operation is not idempotent: retrying an uncertain request can create another key.
operationId: generateSecretKey
tags:
- API Keys
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSecretKeyRequest'
responses:
'200':
description: Secret key generated successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateSecretKeyResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key request was invalid or no usable key token could be generated
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/page:
post:
summary: Page secret keys
description: Lists public metadata for secret keys that belong to the authenticated application, newest first. Bearer tokens are never returned.
operationId: pageSecretKeys
tags:
- API Keys
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PageSecretKeysRequest'
responses:
'200':
description: Secret keys listed successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PageSecretKeysResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key page request was invalid or key data could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/lookup:
post:
summary: Retrieve a secret key
description: Retrieves public metadata for a secret key owned by the authenticated application. The bearer token is never returned.
operationId: lookupSecretKey
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupSecretKeyRequest'
responses:
'200':
description: Secret key retrieved successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/LookupSecretKeyResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Secret key not found for the authenticated application
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key lookup request was invalid or key data could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/update:
post:
summary: Update a secret key
description: Updates the label of a secret key owned by the authenticated application. Send an empty label to clear it. The bearer token is never returned.
operationId: updateSecretKey
tags:
- API Keys
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSecretKeyRequest'
responses:
'200':
description: Secret key updated successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSecretKeyResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Secret key not found for the authenticated application
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A request with this idempotency key is still in progress
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key update request was invalid or changes could not be saved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Idempotency or key storage is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/destroy:
post:
summary: Revoke a secret key
description: Revokes a secret key owned by the authenticated application. A revoked key cannot authenticate future requests but remains visible as public metadata.
operationId: destroySecretKey
tags:
- API Keys
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DestroySecretKeyRequest'
responses:
'200':
description: Secret key revoked successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/DestroySecretKeyResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Secret key not found for the authenticated application
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A request with this idempotency key is still in progress
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key revoke request was invalid or revocation could not be completed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Idempotency or key storage is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/keys/usage:
post:
summary: Retrieve secret key usage
description: Retrieves recent authentication outcomes for a secret key owned by the authenticated application. Each activity row contains only the key ID, event time, and outcome; bearer tokens are never returned.
operationId: lookupSecretKeyUsage
tags:
- API Keys
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SecretKeyUsageRequest'
responses:
'200':
description: Secret key usage retrieved successfully.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/SecretKeyUsageResponse'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Secret key not found for the authenticated application
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Secret key usage request was invalid or activity could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/create:
post:
summary: Create a financial account
description: Create a wallet, Ghana bank account, or Dosh account managed through Inttegro.
operationId: createFinancialAccount
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountCreateRequest'
responses:
'200':
description: Financial account created
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountCreateResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid account details
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/lookup:
post:
summary: Lookup a financial account
description: Retrieve a financial account by ID.
operationId: lookupFinancialAccount
tags: [Financial Accounts]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountIDRequest'
responses:
'200':
description: Financial account found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccount'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid account ID
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/page:
post:
summary: Page through financial accounts
description: Retrieve a page of financial accounts for the authenticated application.
operationId: pageFinancialAccounts
tags: [Financial Accounts]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountPageRequest'
responses:
'200':
description: Financial account page
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
page:
$ref: '#/components/schemas/FinancialAccountPage'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid page parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account page failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/connect:
post:
summary: Connect a financial account
description: Connect an existing wallet, Ghana bank account, or Dosh account for collections or payouts.
operationId: connectFinancialAccount
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountCreateRequest'
responses:
'200':
description: Financial account connected
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountConnectedResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid account details
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/update:
post:
summary: Update a financial account
description: Update the account label, description, reference, owner, or custom data.
operationId: updateFinancialAccount
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountUpdateRequest'
responses:
'200':
description: Financial account updated
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountUpdateResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid update
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/enable_push:
post:
summary: Enable push capability
description: Allow the account to receive payouts and other supported transfers.
operationId: enableFinancialAccountPush
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountIDRequest'
responses:
'200':
description: Push capability enabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountConnectedResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - push cannot be enabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/disable_push:
post:
summary: Disable push capability
description: Stop the account from receiving payouts and other supported transfers.
operationId: disableFinancialAccountPush
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountDisableRequest'
responses:
'200':
description: Push capability disabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountConnectedResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - push cannot be disabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/disconnect:
post:
summary: Disconnect a financial account
description: Disconnect the account from new Inttegro activity.
operationId: disconnectFinancialAccount
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountDisableRequest'
responses:
'200':
description: Financial account disconnected
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountCompactResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - account cannot be disconnected
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/reconnect:
post:
summary: Reconnect a financial account
description: Reconnect a previously disconnected account.
operationId: reconnectFinancialAccount
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountIDRequest'
responses:
'200':
description: Financial account reconnected
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountCompactResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - account cannot be reconnected
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/enable_pull:
post:
summary: Enable pull capability
description: Allow supported charges to pull funds from the account.
operationId: enableFinancialAccountPull
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountEnablePullRequest'
responses:
'200':
description: Pull capability enabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountConnectedResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - pull cannot be enabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financial_accounts/disable_pull:
post:
summary: Disable pull capability
description: Stop supported charges from pulling funds from the account. The pull configuration and its mandate are removed.
operationId: disableFinancialAccountPull
tags: [Financial Accounts]
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialAccountIDRequest'
responses:
'200':
description: Pull capability disabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
account:
$ref: '#/components/schemas/FinancialAccountConnectedResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - pull cannot be disabled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - financial account request failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/balances:
post:
summary: Retrieve your balance
description: |
Fetch the latest GHS balance snapshot plus live operational holds for your application.
The response separates payout-eligible funds, funds that are still pending, deliberate
refund and reserved buckets, and funds committed to in-flight payouts or refunds.
operationId: lookupBalances
tags:
- Balances
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
responses:
'200':
description: Balance retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceSnapshotResponse'
'400':
description: Bad request - the JSON body must be an empty object
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Balance snapshot could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/balance_transactions/lookup:
post:
summary: Look up a balance transaction
description: Retrieves one balance transaction by its unique identifier.
operationId: lookupBalanceTransaction
tags:
- Balance Transactions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- transaction_id
additionalProperties: false
properties:
transaction_id:
type: string
minLength: 1
description: Unique identifier of the balance transaction
responses:
'200':
description: Balance transaction retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceTransactionResponse'
'400':
description: Bad request - invalid JSON, unknown field, or missing transaction_id
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Balance transaction could not be retrieved, including when it does not exist
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/balance_transactions/page:
post:
summary: Page through balance transactions
description: |
Retrieve a paginated list of balance transactions for the authenticated application.
Transactions are sorted by created_at in descending order, so page 1 always contains
the most recent activity.
operationId: pageBalanceTransactions
tags:
- Balance Transactions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- page_number
- page_size
additionalProperties: false
properties:
page_number:
type: integer
minimum: 0
maximum: 10
description: Page number to fetch. Use 1 for the first page; 0 is accepted but returns an empty page.
example: 1
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of transactions per page (1-256)
example: 20
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceTransactionPageResponse'
'400':
description: Bad request - invalid JSON, unknown field, or invalid pagination values
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Balance transactions could not be retrieved
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/payouts/schedule:
post:
summary: Schedule a payout
description: |
Create and schedule a payout to move funds from your available balance to a
connected financial account. The request chooses the destination, caps the
maximum amount that may leave your balance, and optionally delays execution
until a future timestamp.
operationId: schedulePayout
tags:
- Payouts
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulePayoutRequest'
responses:
'200':
description: Payout scheduled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutResponse'
'400':
description: Bad request - invalid schedule parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'500':
description: Internal server error - payout scheduling failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/lookup:
post:
summary: Lookup a payout
description: |
Retrieve the current state of a payout by ID. Use this to monitor execution,
inspect timestamps, review bundled balance transactions, and reconcile the
final amount that moved to the destination account.
operationId: lookupPayout
tags:
- Payouts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupPayoutRequest'
responses:
'200':
description: Payout found successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutResponse'
'400':
description: Bad request - invalid payout identifier
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'500':
description: Internal server error - payout lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/set_destinations:
post:
summary: Set payout destinations
description: |
Configure which financial account should be used for payouts in each currency.
This endpoint accepts a map of currency codes to financial account IDs. Each financial
account must be owned by your application, have push operations enabled, and its currency
must match the currency key in the destinations map.
operationId: setPayoutDestinations
tags:
- Payouts
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetPayoutDestinationsRequest'
responses:
'200':
description: Payout destinations set successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutSettingsMutationResponse'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid destination settings
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout settings update failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/settings:
post:
summary: Get payout settings
description: |
Retrieve the current payout settings for your application, including configured
payout destinations and schedule information.
operationId: getPayoutSettings
tags:
- Payouts
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Send an empty JSON object.
additionalProperties: false
responses:
'200':
description: Payout settings retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutSettingsLookupResponse'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid request body
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout settings lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/disable:
post:
summary: Disable automatic payouts
description: |
Disables automatic payouts for your application by switching the payout schedule
to manual mode. When automatic payouts are disabled, the system will not
automatically schedule payouts - you must manually trigger them using the
/payouts/schedule endpoint. Balance transactions must still be at least 7 days
old before they can be paid out, but the payout will only occur when you
explicitly request it.
operationId: disableAutomaticPayouts
tags:
- Payouts
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Send an empty JSON object.
additionalProperties: false
responses:
'200':
description: Automatic payouts disabled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PayoutSettingsMutationResponse'
example:
settings:
id: "ps_1234567890abcdef"
schedule:
id: "PAYOUT_SCHEDULE_MANUAL_11_21_2025"
name: "manual"
type: "manual"
interval: "manual"
schedule_on: "never"
description: "Manual payout schedule. Used when automatic payouts are disabled."
spec:
id: "PAYOUT_SCHEDULE_SPEC_MANUAL_11_21_2025"
t_plus: "168h"
label: "manual"
abide: "strictly"
destinations:
ghs: "fa_1234567890abcdef"
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid request body
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout settings update failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/enable:
post:
summary: Enable automatic payouts
description: |
Re-enable automatic payouts for your application. Inttegro restores the
configured automatic payout schedule so eligible balance transactions can be
queued without a manual scheduling request.
operationId: enableAutomaticPayouts
tags:
- Payouts
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Send an empty JSON object.
additionalProperties: false
responses:
'200':
description: Automatic payouts enabled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutSettingsMutationResponse'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid request body
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout settings update failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/page:
post:
summary: Page through payouts
description: Retrieve a page of payouts for the authenticated application.
operationId: pagePayouts
tags:
- Payouts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PagePayoutsRequest'
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutPageResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - invalid page parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payouts/cancel:
post:
summary: Cancel a scheduled payout
description: |
Cancel a payout that is still scheduled for a future execution time. A payout
that has started processing, completed, was already canceled, or whose execution
time has passed cannot be canceled.
operationId: cancelPayout
tags:
- Payouts
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelPayoutRequest'
responses:
'200':
description: Payout canceled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutResponse'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Bad request - payout cannot be canceled
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error - payout cancellation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/files/create:
post:
summary: Create a file
description: |
Upload a file to Inttegro for the authorized application. The request must be multipart form data and include a binary `file` part plus a `purpose`.
operationId: createFile
tags:
- Files
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateFileRequest'
responses:
'200':
description: File created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: Idempotency or storage quota conflict
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File upload is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/files/lookup:
post:
summary: Lookup a file
description: Retrieves metadata for one file owned by the authorized application.
operationId: lookupFile
tags:
- Files
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupFileRequest'
responses:
'200':
description: File retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File lookup is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/files/page:
post:
summary: Page files
description: Lists files for the authorized application, optionally filtered by purpose, status, and creation window.
operationId: pageFiles
tags:
- Files
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageFilesRequest'
responses:
'200':
description: File page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FilePageResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'503':
description: File page is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/files/contents:
post:
summary: Deliver file contents
description: Streams original file bytes for a file owned by the authorized application, or returns a 303 redirect to a short-lived signed delivery URL when delivery is redirect.
operationId: streamFileContents
tags:
- Files
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FileContentsRequest'
responses:
'200':
description: Original file bytes
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/octet-stream:
schema:
type: string
format: binary
'303':
description: Redirect to a short-lived signed delivery URL
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Location:
schema:
type: string
format: uri
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'422':
description: The stored file representation cannot be delivered
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'424':
description: File contents could not be read
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File delivery is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/files/delete:
post:
summary: Delete a file
description: Tombstones a file and schedules backing-object cleanup when allowed by reference policy.
operationId: deleteFile
tags:
- Files
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteFileRequest'
responses:
'200':
description: File deleted successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File not found or already deleted
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'409':
description: File still has live references
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File deletion is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_links/create:
post:
summary: Create a file link
description: Creates a revocable public capability URL for an existing file.
operationId: createFileLink
tags:
- File links
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFileLinkRequest'
responses:
'200':
description: File link created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFileLinkResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File-link creation is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_links/lookup:
post:
summary: Lookup a file link
description: Retrieves a file link without exposing token material.
operationId: lookupFileLink
tags:
- File links
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupFileLinkRequest'
responses:
'200':
description: File link retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileLinkResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File link not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File-link lookup is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_links/page:
post:
summary: Page file links
description: Lists file links for the authorized application, optionally filtered by file or status.
operationId: pageFileLinks
tags:
- File links
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageFileLinksRequest'
responses:
'200':
description: File link page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileLinkPageResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'503':
description: File-link page is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_links/revoke:
post:
summary: Revoke a file link
description: Revokes an active file link so its public capability URL can no longer serve the file.
operationId: revokeFileLink
tags:
- File links
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RevokeFileLinkRequest'
responses:
'200':
description: File link revoked successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileLinkResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File link not found or inactive
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File-link revocation is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_links/open:
get:
summary: Open a public file link
description: Opens a token-protected public file link. Depending on delivery policy, this either streams bytes or redirects to a short-lived provider URL.
operationId: openFileLink
tags:
- File links
security: []
parameters:
- name: id
in: query
required: true
schema:
type: string
description: Public file link capability ID.
- name: token
in: query
required: true
schema:
type: string
description: Bearer token paired with the capability ID.
responses:
'200':
description: File bytes
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/octet-stream:
schema:
type: string
format: binary
'302':
description: Redirect to short-lived file URL
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: File link not found or token invalid
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'403':
description: File-link access policy rejected the request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'410':
description: File link is inactive, expired, or exhausted
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'422':
description: The stored file representation cannot be delivered
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'424':
description: File contents could not be read
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: File delivery is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/create:
post:
summary: Create an upload request
description: Creates a delegated upload request that can collect one file from a user or customer under purpose, size, format, expiry, and attempt constraints.
operationId: createUploadRequest
tags:
- File upload requests
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUploadRequestRequest'
responses:
'200':
description: Upload request created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: Upload-request state or idempotency conflict
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: Upload-request creation is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/lookup:
post:
summary: Lookup an upload request
description: Retrieves a delegated upload request for the authorized application.
operationId: lookupUploadRequest
tags:
- File upload requests
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupUploadRequestRequest'
responses:
'200':
description: Upload request retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestWithAttemptResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Upload request not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: Upload-request lookup is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/page:
post:
summary: Page upload requests
description: Lists delegated upload requests for the authorized application.
operationId: pageUploadRequests
tags:
- File upload requests
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PageUploadRequestsRequest'
responses:
'200':
description: Upload request page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestPageResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'503':
description: Upload-request page is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/cancel:
post:
summary: Cancel an upload request
description: Cancels an active delegated upload request so its public upload URL can no longer accept files.
operationId: cancelUploadRequest
tags:
- File upload requests
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelUploadRequestRequest'
responses:
'200':
description: Upload request canceled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Upload request not found or inactive
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'409':
description: Upload-request state changed concurrently
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: Upload-request cancellation is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/review:
post:
summary: Review an upload request attempt
description: Records a manual approval or rejection for the latest submitted upload attempt.
operationId: reviewUploadRequestAttempt
tags:
- File upload requests
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewUploadRequestAttemptRequest'
responses:
'200':
description: Upload attempt reviewed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestWithAttemptResponse'
'400':
description: Invalid request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'404':
description: Upload request or attempt not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'409':
description: The attempt is stale or incompatible with the requested decision
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: Upload review is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/upload_requests/upload:
post:
summary: Fulfill an upload request
description: Public capability endpoint used by a delegated uploader to submit the requested file. This request does not use API-key authentication.
operationId: fulfillUploadRequest
tags:
- File upload requests
security: []
parameters:
- name: id
in: query
required: true
schema:
type: string
description: Public upload request capability ID.
- name: token
in: query
required: true
schema:
type: string
description: Bearer token paired with the capability ID.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FulfillUploadRequestRequest'
responses:
'200':
description: Upload request fulfilled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillUploadRequestResponse'
'400':
description: Uploaded file failed request validation
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UploadRequestValidationErrorResponse'
'404':
description: Upload request not found or capability token is invalid
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'409':
description: File quota is insufficient
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'410':
description: Upload request is inactive, expired, or exhausted
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
'503':
description: Capability upload is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/FileApiError'
/file_references/reconcile:
post:
summary: Reconcile file references
description: Replaces the complete set of live file references for one Inttegro resource. Omitting `references` or sending an empty array clears the set.
operationId: reconcileFileReferences
tags:
- File references
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FileReferenceReconcileRequest'
responses:
'200':
description: File references reconciled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FileReferenceReconcileResponse'
'400':
description: Invalid request or idempotency key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - missing or invalid API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'409':
description: A request with this idempotency key is still in progress
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: The idempotency key was reused with a different request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: File-reference reconciliation is temporarily unavailable
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/payment_methods/tokenize:
post:
summary: Tokenize a payment method
description: |
Save a mobile-money payment method for an existing customer without charging it.
Direct tokenization currently supports `mobile_money`; send the wallet details
and owner identity described by the request schema.
The returned payment method can be reused only while it is active, unarchived,
and non-ephemeral. This operation supports idempotency.
operationId: tokenizePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without saving the payment method twice.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenizeMobileMoneyPaymentMethodRequest'
responses:
'200':
description: Payment method tokenized successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'400':
description: Invalid payment method tokenization request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Payment method tokenization failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/lookup:
post:
summary: Lookup a payment method
description: |
Retrieve details for a specific payment method by ID. Returns the full
payment method object including verification status, creation timestamp,
masked account details, and owner details when captured.
operationId: lookupPaymentMethod
tags:
- Payment Methods
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to fetch
example: "pm_xyz789"
responses:
'200':
description: Payment method found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'400':
description: Invalid payment method lookup request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
/payment_methods/page:
post:
summary: Page payment methods
description: |
Retrieve a paginated list of payment methods for the authenticated
application.
If `customer_id` is supplied, the page is scoped to payment methods
that belong to that customer. The supplied customer must belong to
your authenticated application.
operationId: pagePaymentMethods
tags:
- Payment Methods
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodPageRequest'
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodPageResponse'
'400':
description: Invalid payment methods page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Payment methods page lookup failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/update:
post:
summary: Update a payment method
description: |
Update mutable payment method metadata for the authenticated
application.
Supported updates:
- `custom_data` merges into existing metadata
- `owner` applies patch semantics and updates only the
provided owner fields
- `active` toggles whether the payment method can be reused
- `archived` archives or unarchives the payment method
**Custom Data Merge Semantics:**
- New keys are added to existing custom_data
- Existing keys are updated with new values
- JSON null explicitly deletes the key
- Keys not present in the update are preserved
When adding a new owner address to a payment method that does
not already have one, `owner.address.country` is required.
Archived payment methods reject all updates except a pure
unarchive request. Unarchiving leaves the payment method
inactive until you activate it again.
operationId: updatePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying the update twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to update
example: "pm_xyz789"
custom_data:
$ref: '#/components/schemas/CustomDataPatch'
active:
type: boolean
description: Set to `true` to activate the payment method or `false` to mark it inactive.
example: true
archived:
type: boolean
description: Set to `true` to archive the payment method or `false` to unarchive it.
example: false
owner:
type: object
description: Owner details to patch onto the payment method.
properties:
name:
type: string
description: Full legal name of the account holder.
example: "Jane Mensah"
address:
type: object
description: Postal address for the payment method owner.
properties:
city:
type: string
description: City or locality.
example: "Accra"
country:
type: string
description: Two-letter ISO country code. Required when adding a brand new owner address.
example: "GH"
line1:
type: string
description: First address line.
example: "1 High Street"
line2:
type: string
description: Second address line.
example: "Osu"
name:
type: string
description: Recipient name for the address, if different from owner name.
example: "Jane Mensah"
phone_number:
type: string
description: Phone number for the address.
example: "+233201234567"
post_code:
type: string
description: Postal or ZIP code.
example: "GA-123-4567"
region:
type: string
description: Region, state, or province.
example: "Greater Accra"
responses:
'200':
description: Payment method updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Invalid payment method update request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/activate:
post:
summary: Activate a payment method
description: |
Mark an inactive payment method as active so it can be reused in
new payment flows.
operationId: activatePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying activation twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to activate
example: "pm_xyz789"
responses:
'200':
description: Payment method activated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Invalid payment method activation request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/disactivate:
post:
summary: Deactivate a payment method
description: |
Mark an active payment method as inactive so it cannot be reused
in new payment flows until reactivated.
operationId: disactivatePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying deactivation twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to mark inactive
example: "pm_xyz789"
responses:
'200':
description: Payment method marked inactive successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Invalid payment method deactivation request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/archive:
post:
summary: Archive a payment method
description: |
Archive a payment method. Archived payment methods become
inactive immediately and reject further updates until they are
unarchived.
operationId: archivePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying archival twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to archive
example: "pm_xyz789"
responses:
'200':
description: Payment method archived successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Invalid payment method archive request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/unarchive:
post:
summary: Unarchive a payment method
description: |
Unarchive an archived payment method so it can be updated again.
Unarchiving does not automatically reactivate the payment
method.
operationId: unarchivePaymentMethod
tags:
- Payment Methods
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying unarchival twice.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- payment_method_id
properties:
payment_method_id:
type: string
description: ID of the payment method to unarchive
example: "pm_xyz789"
responses:
'200':
description: Payment method unarchived successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
'404':
description: Payment method not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'400':
description: Invalid payment method unarchive request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payment_methods/settings:
post:
summary: Get payment method settings
description: |
Retrieve payment method acceptance settings for your application. Returns
configuration for all supported payment types (mobile money, bank accounts,
cards, Motito) including whether each type is enabled and requires customer
confirmation.
Use this to:
- Show only enabled payment methods in checkout
- Require explicit consent when confirms_use is true
- Display acceptance preferences to merchants
operationId: getPaymentMethodSettings
tags:
- Payment Methods
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Send an empty JSON object.
properties: {}
responses:
'200':
description: Settings retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
required:
- settings
properties:
settings:
$ref: '#/components/schemas/PaymentMethodSettings'
'400':
description: Invalid payment method settings request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Missing or invalid authentication
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Payment method settings lookup failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/create:
post:
summary: Create a product
description: |
Creates a new product in your catalog. Products represent items you sell—physical goods,
digital downloads, services, or subscriptions. Each product includes pricing, description,
and fulfillment details.
Product types:
- **physical**: Tangible goods requiring shipping (requires shipment details)
- **digital**: Electronic content (e-books, software, media) delivered via download/stream
- **service**: Intangible offerings (consulting, subscriptions, memberships)
- **voucher**: Gift cards, credits, or promotional codes
- **custom**: Custom product types for specialized use cases
- **cause**: Donation or charitable contribution products
operationId: createProduct
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductRequest'
responses:
'200':
description: Product created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/add_price:
post:
summary: Add a price to a product
description: |
Creates a new price for an existing product owned by the authenticated application.
Key points:
- The target product must belong to your authenticated application
- Archived products cannot accept new prices
- Customer-selected price definitions are available only to Commerce internal services and Upper private beta organizations and applications
- The response returns the created price only
operationId: addProductPrice
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddProductPriceRequest'
responses:
'200':
description: Price created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/AddProductPriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed or product is archived
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/lookup:
post:
summary: Lookup a product
description: |
Retrieves a product's details by ID. Returns the complete product record including
pricing, description, category, shipment details, and all metadata.
operationId: lookupProduct
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupProductRequest'
responses:
'200':
description: Product found successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Product lookup failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/update:
post:
summary: Update a product
description: |
Update the mutable description, classification, fulfillment, dimension, media,
attribute, and custom-data fields of an existing product. If `type` is supplied,
it must equal the existing type. `images` and `media` are mutually exclusive.
Inline `price` updates are not supported; use the Prices API. An ID-only request
succeeds without changing the product, and archived products can still be updated.
operationId: updateProduct
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductRequest'
responses:
'200':
description: Product updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed or immutable field changed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/publish:
post:
summary: Publish a product
description: |
Mark a product active and record its publication time. Publishing can also reactivate
an archived product; the archive timestamp remains part of its history.
operationId: publishProduct
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductActionRequest'
responses:
'200':
description: Product published successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Product is already published
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/unpublish:
post:
summary: Unpublish a product
description: |
Mark a product inactive for catalog lifecycle purposes. Existing prices and purchase
intents are not disabled by this operation.
operationId: unpublishProduct
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductActionRequest'
responses:
'200':
description: Product unpublished successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Product is already unpublished
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/archive:
post:
summary: Archive a product
description: |
Archive a product and mark it inactive. Archive blocks `/products/add_price`, but the
current API still permits lookup, update, publish, catalog-ID order snapshots, and
purchase-intent resolution for the product.
operationId: archiveProduct
tags:
- Products
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductActionRequest'
responses:
'200':
description: Product archived successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ProductResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Product is already archived
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/products/page:
post:
summary: Page through products
description: |
Retrieve a paginated list of products for the authenticated application.
No response ordering is guaranteed.
operationId: pageProducts
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- page_number
properties:
page_number:
type: integer
minimum: 1
maximum: 10
description: 1-based page index to fetch (1-10 inclusive)
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of products per page (1-256)
default: 256
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
properties:
page:
type: object
properties:
number:
type: integer
description: The page number returned
size:
type: integer
description: The number of products in this page
products:
type: array
items:
$ref: '#/components/schemas/Product'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Invalid product page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/purchase_intents/create:
post:
summary: Create a purchase intent
description: |
Creates a controlled, shareable Buy link for a catalog product without
requiring you to build a product page, cart, or checkout UI. The returned
`sale_...` ID becomes `https://pages.inttegro.com/buy/{purchase_intent_id}`.
An order is created only when a customer checks out from that link.
This operation supports idempotency. Reuse the same `Idempotency-Key` and
request body when retrying an uncertain request.
operationId: createPurchaseIntent
tags:
- Purchase Intents
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without creating a duplicate Buy link.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePurchaseIntentRequest'
responses:
'200':
description: Purchase intent created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseIntentResponse'
'400':
description: Invalid request, quantity range, price availability, or product-price relationship
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Product or price not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Purchase intent creation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/purchase_intents/update:
post:
summary: Update a purchase intent
description: |
Changes quantity bounds or expiry without changing what an already-shared
Buy link sells. `reactivate: true` clears cancellation state and any existing
elapsed expiry. Product, price, usage mode, and variant selection remain
immutable after creation.
This operation supports idempotency. Reuse the same `Idempotency-Key` and
request body when retrying an uncertain request.
operationId: updatePurchaseIntent
tags:
- Purchase Intents
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying the update twice.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePurchaseIntentRequest'
responses:
'200':
description: Purchase intent updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseIntentResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Purchase intent not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Purchase intent update failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/purchase_intents/cancel:
post:
summary: Cancel a purchase intent
description: |
Stops a Buy link from creating new orders immediately. Cancellation is an
explicit merchant action and is distinct from time-driven expiry. Repeating
cancellation for an already inactive intent returns its current state, but a
single-use intent that already created an order cannot be canceled.
This operation supports idempotency. Reuse the same `Idempotency-Key` and
request body when retrying an uncertain request.
operationId: cancelPurchaseIntent
tags:
- Purchase Intents
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying cancellation twice.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelPurchaseIntentRequest'
responses:
'200':
description: Purchase intent canceled successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseIntentResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Purchase intent not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Purchase intent cancellation failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/purchase_intents/lookup:
post:
summary: Lookup a purchase intent
description: |
Resolves the offer behind a hosted Buy link using only its opaque ID. Public
lookup requires no API key and returns active or expired intents; canceled
and used single-use intents are returned as not found. When the owning
application authenticates the request, lookup is application-scoped, returns
all lifecycle states.
operationId: lookupPurchaseIntent
tags:
- Purchase Intents
security:
- {}
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LookupPurchaseIntentRequest'
responses:
'200':
description: Purchase intent found successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PurchaseIntentResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Purchase intent not found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Purchase intent lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/purchase_intents/page:
post:
summary: List purchase intents
description: |
Lists purchase intents for the authenticated application, newest first.
Pagination is numbered. The response `page.size` is the number of records
actually returned, not the requested limit, and no total count or next-page
token is included.
operationId: pagePurchaseIntents
tags:
- Purchase Intents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PagePurchaseIntentsRequest'
responses:
'200':
description: Purchase intents listed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PagePurchaseIntentsResponse'
'400':
description: Bad request - invalid pagination parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: A purchase intent could not be hydrated
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Purchase intent page lookup failed unexpectedly
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/create:
post:
summary: Create a price
description: |
Creates a new price in your catalog. Fixed prices may optionally be associated with a product;
customer-selected prices must be associated with a product. Multiple prices can exist for the
same product to support different currencies, markets, or customer segments.
Key points:
- Price amounts are immutable after creation (create new price to change amount)
- Product association (product_id) is optional for fixed prices, required for customer-selected prices, and immutable once set
- Customer-selected price definitions are available only to Commerce internal services and Upper private beta organizations and applications
- Label and about fields can be updated later
- Amount must be a positive integer representing the smallest currency unit (cents, pence, etc.)
operationId: createPrice
tags:
- Prices
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogPriceParams'
responses:
'200':
description: Price created successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/lookup:
post:
summary: Lookup a price
description: |
Retrieves a price's details by ID. Returns the complete price record including
amount, currency, associated product, label, description, and timestamps.
operationId: lookupPrice
tags:
- Prices
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- price_id
properties:
price_id:
type: string
description: The unique identifier of the price to lookup
example: "pr_xyz789"
responses:
'200':
description: Price found
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Price lookup failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/page:
post:
summary: Page through prices
description: |
Retrieve a paginated list of prices for the authenticated application.
Results are sorted by created_at in descending order, so page 1 contains
the most recently created prices and subsequent pages step back in time.
If `product_id` is supplied, the page is scoped to prices that belong
to that product. The product must belong to your authenticated application.
operationId: pagePrices
tags:
- Prices
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PricePageRequest'
responses:
'200':
description: Page retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PricePageResponse'
'400':
description: Invalid price page request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - validation failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/update:
post:
summary: Update a price
description: |
Updates an existing price's metadata. Only label and about fields can be modified.
Amount and product association are not accepted by this operation; create a new
price when either must differ.
operationId: updatePrice
tags:
- Prices
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- price_id
properties:
price_id:
type: string
description: The unique identifier of the price to update
example: "pr_xyz789"
label:
type: string
description: Short label for this price (max 100 characters)
example: "Premium pricing"
about:
type: string
description: Longer description of this price (max 500 characters)
example: "Premium pricing tier for enterprise customers"
responses:
'200':
description: Price updated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Cannot modify immutable field (product_id or amount)
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/activate:
post:
summary: Activate a price
description: |
Reactivates an inactive price so it can be used again in new flows.
Key points:
- The price must belong to the authenticated application
- Archived prices cannot be activated
- Already-active prices return an error
operationId: activatePrice
tags:
- Prices
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PriceActionRequest'
responses:
'200':
description: Price activated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - price archived or already active
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/deactivate:
post:
summary: Deactivate a price
description: |
Marks a price as inactive so it can no longer be used for new default-price assignments or other active catalog flows.
Key points:
- The price must belong to the authenticated application
- Archived prices cannot be deactivated
- Already-inactive prices return an error
operationId: deactivatePrice
tags:
- Prices
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PriceActionRequest'
responses:
'200':
description: Price deactivated successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Bad request - invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: Unprocessable entity - price archived or already inactive
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/prices/archive:
post:
summary: Archive a price
description: |
Archive a price and mark it inactive. An archived price cannot be activated or
deactivated, and attempting to archive it again returns a lifecycle error.
operationId: archivePrice
tags:
- Prices
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without archiving the price twice.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PriceActionRequest'
responses:
'200':
description: Price archived successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/PriceResponse'
'400':
description: Invalid price archive request
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - invalid or missing API key
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
'422':
description: Price archive failed
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/spec/countries:
post:
summary: Get country specifications
description: |
Retrieve country specifications including supported currencies, payment methods,
payout schedules, legal entity types, financial account types, ID document
types, and country-specific bank reference data for all configured countries.
Use this to:
- Build country-specific onboarding flows
- Validate payment methods by country
- Display appropriate ID document types
- Show available payout schedules per country
- Populate country-specific bank and branch selectors
This is a public endpoint that does not require authentication.
operationId: listCountrySpecs
tags:
- Specifications
security: []
requestBody:
required: false
content:
application/json:
schema:
type: object
description: No request body required
additionalProperties: false
responses:
'200':
description: Country specifications retrieved successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
type: object
required: [countries]
properties:
countries:
$ref: '#/components/schemas/CountrySpecifications'
example:
countries:
gh:
country_code: "gh"
country_name: "Ghana"
currencies: ["ghs", "usd"]
payment_methods: ["mobile_money", "bank_account", "payment_card", "motito"]
payout_schedules: ["weekly", "manual"]
bt_aging_specs: ["twenty_four_hourly", "forty_eight_hourly", "hundred_sixty_eight_hourly"]
legal_entity_types:
- "individual"
- "business"
financial_account_types: ["wallet", "bank_account"]
id_document_types: ["ghana_card", "passport"]
banks:
bank_account_type: "ghana_bank_account"
code_scheme: "sort_code"
items:
- id: "absa_gh_ltd"
name: "ABSA (GH) LTD"
swift_code: "BARCGHAC"
sort_code_prefix: "03"
branches:
- id: "absa_gh_ltd_kasoa_branch"
name: "ABSA (GH) LTD-KASOA BRANCH"
sort_code: "030101"
'400':
description: Invalid request body
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/customers/search:
post:
summary: Search customers
description: |
Search customers owned by the authenticated application. Customer searches support
the route-local `kind` filter and facet. Results are projections for discovery;
retrieve a customer by ID before making decisions that require canonical state.
operationId: searchCustomers
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchRequest'
example:
text: Ama Mensah
filters:
- field: kind
operator: in
values: [registered, guest]
facets:
- field: kind
limit: 10
page_size: 25
responses:
'200':
description: Customer search completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchResponse'
'400':
description: Search parameters or cursor are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Customer search is temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/financial_accounts/search:
post:
summary: Search financial accounts
description: |
Search financial accounts owned by the authenticated application. Financial-account
searches support the route-local `type`, `status`, and `currency` filters and facets.
Results are projections for discovery; retrieve an account by ID before acting on it.
operationId: searchFinancialAccounts
tags:
- Financial Accounts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchRequest'
example:
filters:
- field: status
operator: eq
values: [active]
- field: currency
operator: in
values: [ghs, usd]
facets:
- field: type
limit: 10
sort:
field: updated_at
direction: desc
page_size: 25
responses:
'200':
description: Financial-account search completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchResponse'
'400':
description: Search parameters or cursor are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Financial-account search is temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/orders/search:
post:
summary: Search orders
description: |
Search orders owned by the authenticated application. Order searches support the
route-local `status` filter and facet. Results are projections for discovery;
retrieve an order by ID before making decisions that require canonical state.
operationId: searchOrders
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchRequest'
example:
text: INV-1042 Ama Mensah
filters:
- field: status
operator: in
values: [paid, requires_payment]
facets:
- field: status
limit: 10
sort:
field: relevance
direction: desc
page_size: 25
responses:
'200':
description: Order search completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchResponse'
'400':
description: Search parameters or cursor are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Order search is temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/payouts/search:
post:
summary: Search payouts
description: |
Search payouts owned by the authenticated application. Payout searches support the
route-local `status` and `currency` filters and facets. Results are projections for
discovery; retrieve a payout by ID before acting on it.
operationId: searchPayouts
tags:
- Payouts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchRequest'
example:
filters:
- field: status
operator: in
values: [scheduled, processing]
facets:
- field: currency
limit: 10
sort:
field: updated_at
direction: desc
page_size: 25
responses:
'200':
description: Payout search completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchResponse'
'400':
description: Search parameters or cursor are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Payout search is temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
/products/search:
post:
summary: Search products
description: |
Search products owned by the authenticated application. Product searches support
the route-local `type`, `status`, and `category` filters and facets, and may sort by
`relevance`, `updated_at`, or `published_at`. Results are projections for discovery;
retrieve a product by ID before making decisions that require canonical state.
operationId: searchProducts
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchRequest'
example:
text: utility sneakers
filters:
- field: status
operator: eq
values: [active]
facets:
- field: category
limit: 10
sort:
field: published_at
direction: desc
page_size: 25
responses:
'200':
description: Product search completed successfully
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSearchResponse'
'400':
description: Search parameters or cursor are invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'503':
description: Product search is temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Inttegro API key supplied in the Authorization header.
headers:
RequestId:
description: Unique Inttegro request identifier for support, tracing, and reconciliation.
schema:
type: string
example: req_01hzz8y7q5r4q4f6r6q6k2z3w1
RetryAfter:
description: Seconds to wait before retrying a temporarily unavailable or rate-limited request.
schema:
type: string
example: "30"
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
schema:
type: string
description: Stable key used to replay safe retries without applying the mutation twice.
schemas:
ApplicationCapabilityRequirement:
type: object
additionalProperties: false
required: [code, description, due_at]
properties:
code:
type: string
pattern: '^[a-z][a-z0-9_]*$'
description: Stable public identifier for the requirement.
description:
type: string
description: Public explanation of what must be completed.
due_at:
type: string
format: date-time
nullable: true
description: Requirement deadline, or null when no deadline applies.
ApplicationCapabilityRequirements:
type: object
additionalProperties: false
required: [currently_due]
properties:
currently_due:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ApplicationCapabilityRequirement'
EnabledApplicationCapability:
type: object
additionalProperties: false
required: [status, status_changed_at]
properties:
status:
type: string
enum: [enabled]
status_changed_at:
type: string
format: date-time
RestrictedApplicationCapability:
type: object
additionalProperties: false
required: [status, status_reason, status_changed_at, requirements]
properties:
status:
type: string
enum: [restricted]
status_reason:
type: string
enum: [setup_incomplete, account_under_review, account_restricted, account_inactive]
status_changed_at:
type: string
format: date-time
requirements:
$ref: '#/components/schemas/ApplicationCapabilityRequirements'
PendingReviewApplicationCapability:
type: object
additionalProperties: false
required: [status, status_reason, status_changed_at]
properties:
status:
type: string
enum: [pending_review]
status_reason:
type: string
enum: [setup_incomplete, account_under_review, account_restricted, account_inactive]
status_changed_at:
type: string
format: date-time
ApplicationCapabilitiesResponse:
type: object
additionalProperties: false
required: [capabilities]
properties:
capabilities:
type: object
additionalProperties: false
required: [payments, payouts]
properties:
payments:
oneOf:
- $ref: '#/components/schemas/EnabledApplicationCapability'
- $ref: '#/components/schemas/RestrictedApplicationCapability'
payouts:
oneOf:
- $ref: '#/components/schemas/EnabledApplicationCapability'
- $ref: '#/components/schemas/RestrictedApplicationCapability'
- $ref: '#/components/schemas/PendingReviewApplicationCapability'
ApplicationCapabilityProjection:
type: object
description: Public capability states currently available to the application. Newly created applications can return an empty object until capabilities become available. New capability keys may appear over time.
properties:
payments:
oneOf:
- $ref: '#/components/schemas/EnabledApplicationCapability'
- $ref: '#/components/schemas/RestrictedApplicationCapability'
payouts:
oneOf:
- $ref: '#/components/schemas/EnabledApplicationCapability'
- $ref: '#/components/schemas/RestrictedApplicationCapability'
- $ref: '#/components/schemas/PendingReviewApplicationCapability'
additionalProperties: true
ResourceSearchRequest:
type: object
additionalProperties: false
description: |
A resource-local search request. Send `text`, at least one filter, or both. Field
names are unqualified and depend on the endpoint. The application and resource type
are derived by Inttegro and cannot be supplied by the caller. To continue a search,
repeat the same request and add the returned `next_cursor`.
anyOf:
- required: [text]
- required: [filters]
properties:
text:
type: string
minLength: 1
maxLength: 512
description: Words, identifiers, or names to search for.
filters:
type: array
maxItems: 20
uniqueItems: true
items:
$ref: '#/components/schemas/ResourceSearchFilter'
facets:
type: array
maxItems: 10
uniqueItems: true
items:
$ref: '#/components/schemas/ResourceSearchFacet'
sort:
$ref: '#/components/schemas/ResourceSearchSort'
page_size:
type: integer
minimum: 1
maximum: 100
default: 20
cursor:
type: string
maxLength: 8192
description: Opaque continuation value returned as `next_cursor` by the preceding page.
ResourceSearchFilter:
type: object
additionalProperties: false
required: [field, operator, values]
properties:
field:
type: string
description: Unqualified route-local field name documented by the selected endpoint.
operator:
type: string
enum: [eq, in]
description: "`eq` requires exactly one value; `in` matches any supplied value."
values:
type: array
minItems: 1
maxItems: 20
uniqueItems: true
items:
type: string
minLength: 1
maxLength: 256
ResourceSearchFacet:
type: object
additionalProperties: false
required: [field]
properties:
field:
type: string
description: Unqualified route-local field to group and count.
limit:
type: integer
minimum: 1
maximum: 50
default: 10
ResourceSearchSort:
type: object
additionalProperties: false
required: [field, direction]
properties:
field:
type: string
enum: [relevance, updated_at, published_at]
description: "`published_at` is supported only by product search."
direction:
type: string
enum: [asc, desc]
description: Relevance supports descending order only.
ResourceSearchResponse:
type: object
additionalProperties: false
required: [search]
properties:
search:
$ref: '#/components/schemas/ResourceSearchPage'
ResourceSearchPage:
type: object
additionalProperties: false
required: [resource_types, sort, page_size, result_count, has_more, total, resource_totals, results, facets, freshness]
properties:
resource_types:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/SearchResourceType'
sort:
$ref: '#/components/schemas/ResourceSearchSort'
page_size:
type: integer
minimum: 1
maximum: 100
result_count:
type: integer
minimum: 0
maximum: 100
has_more:
type: boolean
total:
$ref: '#/components/schemas/ResourceSearchTotal'
resource_totals:
type: array
items:
$ref: '#/components/schemas/ResourceSearchResourceTotal'
results:
type: array
description: Search projections for discovery, not canonical resource snapshots.
maxItems: 100
items:
$ref: '#/components/schemas/ResourceSearchResult'
facets:
type: array
maxItems: 10
items:
$ref: '#/components/schemas/ResourceSearchFacetResult'
next_cursor:
type: string
maxLength: 8192
freshness:
$ref: '#/components/schemas/ResourceSearchFreshness'
SearchResourceType:
type: string
enum: [customer, financial_account, order, payout, product]
ResourceSearchTotal:
type: object
additionalProperties: false
required: [value, relation]
properties:
value:
type: integer
format: int64
minimum: 0
relation:
type: string
enum: [exact, lower_bound]
ResourceSearchResourceTotal:
type: object
additionalProperties: false
required: [resource_type, value, relation]
properties:
resource_type:
$ref: '#/components/schemas/SearchResourceType'
value:
type: integer
format: int64
minimum: 0
relation:
type: string
enum: [exact, lower_bound]
ResourceSearchResourceReference:
type: object
additionalProperties: false
required: [type, id]
properties:
type:
$ref: '#/components/schemas/SearchResourceType'
id:
type: string
ResourceSearchAmount:
type: object
additionalProperties: false
required: [currency, value]
properties:
currency:
type: string
description: ISO 4217 currency code.
value:
type: integer
format: int64
minimum: 0
description: Amount in the currency's minor unit.
ResourceSearchResult:
type: object
additionalProperties: false
required: [resource, title, updated_at]
properties:
resource:
$ref: '#/components/schemas/ResourceSearchResourceReference'
title:
type: string
summary:
type: string
status:
type: string
customer_name:
type: string
amount:
$ref: '#/components/schemas/ResourceSearchAmount'
url:
type: string
format: uri
updated_at:
type: string
format: date-time
ResourceSearchFacetBucket:
type: object
additionalProperties: false
required: [value, count]
properties:
value:
type: string
count:
type: integer
format: int64
minimum: 0
ResourceSearchFacetResult:
type: object
additionalProperties: false
required: [field, buckets]
properties:
field:
type: string
description: The same unqualified route-local field requested by the caller.
buckets:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/ResourceSearchFacetBucket'
ResourceSearchResourceFreshness:
type: object
additionalProperties: false
required: [resource_type, state]
properties:
resource_type:
$ref: '#/components/schemas/SearchResourceType'
state:
type: string
enum: [current, delayed, partial, unknown, unavailable]
observed_at:
type: string
format: date-time
last_indexed_at:
type: string
format: date-time
ResourceSearchFreshness:
type: object
additionalProperties: false
required: [state]
properties:
state:
type: string
enum: [current, delayed, partial, unknown, unavailable]
observed_at:
type: string
format: date-time
resources:
type: array
maxItems: 1
items:
$ref: '#/components/schemas/ResourceSearchResourceFreshness'
CustomData:
type: object
description: Merchant-defined string values attached to a resource. SDKs expose this as a semantic collection rather than a raw map.
additionalProperties:
type: string
CustomDataInput:
type: object
description: Merchant-defined values accepted on resource creation. Values are serialized to strings before storage.
additionalProperties: true
CustomDataPatch:
type: object
description: Changes to merchant-defined data. JSON null removes a key; every other JSON value is serialized to a string.
additionalProperties: true
JSONData:
type: object
description: Deliberately extensible JSON object whose keys and values are defined by the selected integration or resource subtype.
additionalProperties: true
ResponseMeta:
type: object
description: Curated response metadata. This is body metadata and does not replace native HTTP status or response headers.
additionalProperties: true
properties:
request_id:
type: string
description: Inttegro request identifier for this API response.
example: req_01hzz8y7q5r4q4f6r6q6k2z3w1
debug:
type: object
description: Optional debug information returned only when explicitly enabled and authorized.
additionalProperties: true
FileMetadata:
type: object
description: System-managed string metadata attached to a file resource.
additionalProperties:
type: string
MessageHeaders:
type: object
description: Validated provider-neutral email headers.
additionalProperties:
type: string
PayoutDestinations:
type: object
description: Supported currency-to-financial-account destination assignments.
additionalProperties: false
properties:
ghs:
type: string
description: Financial account that receives Ghana cedi payouts. Send an empty string to remove the assignment.
example: "fa_1234567890abcdef"
ProductDimensionDetails:
type: object
description: Named string measurements or descriptors for a product dimension.
additionalProperties:
type: string
VariantValues:
type: object
description: Product variant attribute selections keyed by attribute name.
additionalProperties:
type: string
BalanceSnapshot:
type: object
description: The latest GHS balance snapshot for the application.
additionalProperties: false
required: [ghs]
properties:
ghs:
$ref: '#/components/schemas/CurrencyBalanceSnapshot'
CustomerBalanceValue:
type: object
required: [as_of, available]
additionalProperties: false
properties:
as_of:
type: string
format: date-time
available:
$ref: '#/components/schemas/Amount'
CustomerBalance:
type: object
description: Available customer balances keyed by lowercase currency code.
additionalProperties:
$ref: '#/components/schemas/CustomerBalanceValue'
CountrySpecifications:
type: object
description: Country specifications keyed by country code.
additionalProperties:
$ref: '#/components/schemas/CountrySpecification'
GenerateSecretKeyRequest:
type: object
description: Optional public input for secret key generation.
additionalProperties: false
properties:
label:
type: string
description: Optional human-readable label. Surrounding whitespace is trimmed; an empty value creates an unlabeled key.
example: Production checkout
GenerateSecretKeyResponse:
type: object
additionalProperties: false
required:
- key
properties:
key:
$ref: '#/components/schemas/GeneratedSecretKey'
GeneratedSecretKey:
type: object
description: Newly generated secret key. The token is returned once and cannot be retrieved later.
additionalProperties: false
required:
- id
- token_type
- issued_at
- token
properties:
id:
type: string
description: Secret key identifier.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
label:
type: string
description: Optional human-readable label for the secret key.
example: Production checkout
token_type:
type: string
enum: [bearer]
example: bearer
issued_at:
type: string
format: date-time
token:
type: string
description: One-time bearer token for the generated key.
PageSecretKeysRequest:
type: object
additionalProperties: false
properties:
page:
type: integer
minimum: 0
description: Page number alias. Omitted or 0 is normalized to 1.
example: 1
number:
type: integer
minimum: 0
description: Page number. Omitted or 0 is normalized to 1.
example: 1
size:
type: integer
minimum: 0
description: Requested page size. Omitted or 0 becomes 50; values above 100 are capped at 100.
example: 20
PageSecretKeysResponse:
type: object
additionalProperties: false
required:
- page
properties:
page:
$ref: '#/components/schemas/SecretKeyPage'
LookupSecretKeyRequest:
type: object
additionalProperties: false
required: [secret_key_id]
properties:
secret_key_id:
type: string
description: Secret key identifier. Typed `sk_...` IDs are accepted.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
LookupSecretKeyResponse:
type: object
additionalProperties: false
required:
- key
properties:
key:
$ref: '#/components/schemas/SecretKey'
UpdateSecretKeyRequest:
type: object
required: [label, secret_key_id]
additionalProperties: false
properties:
label:
type: string
description: Human-readable label for the secret key. Send an empty string to clear the label.
example: Production checkout
secret_key_id:
type: string
description: Secret key identifier to update.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
UpdateSecretKeyResponse:
type: object
additionalProperties: false
required:
- key
properties:
key:
$ref: '#/components/schemas/SecretKey'
DestroySecretKeyRequest:
type: object
additionalProperties: false
required: [secret_key_id]
properties:
secret_key_id:
type: string
description: Secret key identifier to revoke.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
DestroySecretKeyResponse:
type: object
additionalProperties: false
required:
- key
properties:
key:
$ref: '#/components/schemas/SecretKey'
SecretKeyUsageRequest:
type: object
additionalProperties: false
required: [secret_key_id]
properties:
number:
type: integer
minimum: 0
description: Page number. Omitted or 0 is normalized to 1.
page:
type: integer
minimum: 0
description: Page number alias. Omitted or 0 is normalized to 1.
secret_key_id:
type: string
description: Secret key identifier whose recent activity should be returned.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
size:
type: integer
minimum: 0
description: Requested page size. Omitted or 0 becomes 50; values above 100 are capped at 100.
SecretKeyUsageResponse:
type: object
additionalProperties: false
required:
- key
- usage
properties:
key:
$ref: '#/components/schemas/SecretKey'
usage:
$ref: '#/components/schemas/SecretKeyUsagePage'
SecretKey:
type: object
description: Public secret key metadata. The bearer token is never returned by read or mutation endpoints.
additionalProperties: false
required:
- id
- token_type
- issued_at
- status
- active
properties:
id:
type: string
description: Application-scoped secret key identifier.
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
label:
type: string
description: Optional human-readable label for the secret key.
example: Production checkout
token_type:
type: string
enum: [bearer]
example: bearer
issued_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
description: Omitted until the label is changed.
expires_at:
type: string
format: date-time
description: Omitted for keys without a fixed expiry.
status:
type: string
enum: [active, revoked, expired]
active:
type: boolean
revoked_at:
type: string
format: date-time
description: Omitted until the key is revoked.
last_used_at:
type: string
format: date-time
description: Most recent recorded authentication when available; otherwise omitted.
usage_count:
type: integer
minimum: 0
description: Number of recorded authentications when available; omitted when zero.
SecretKeyPage:
type: object
additionalProperties: false
required:
- number
- size
- count
- total
- has_more
- keys
properties:
number:
type: integer
minimum: 1
size:
type: integer
minimum: 0
count:
type: integer
minimum: 0
total:
type: integer
minimum: 0
has_more:
type: boolean
keys:
type: array
items:
$ref: '#/components/schemas/SecretKey'
SecretKeyUsagePage:
type: object
additionalProperties: false
required:
- number
- size
- count
- total
- has_more
- rows
properties:
number:
type: integer
minimum: 1
size:
type: integer
minimum: 0
count:
type: integer
minimum: 0
total:
type: integer
minimum: 0
has_more:
type: boolean
rows:
type: array
items:
$ref: '#/components/schemas/SecretKeyUsageRow'
SecretKeyUsageRow:
type: object
description: Public authentication outcome associated with the selected key.
additionalProperties: false
required:
- secret_key_id
- occurred_at
- auth_result
properties:
secret_key_id:
type: string
example: sk_2xC7k9gK5yQnZ4w8P1sT6vR3
occurred_at:
type: string
format: date-time
auth_result:
type: string
enum: [succeeded, failed]
FileServiceHealthResponse:
type: object
required:
- service
- status
- environment
- checked_at
properties:
service:
type: string
example: files
status:
type: string
example: ok
environment:
type: string
example: prod
checked_at:
type: string
format: date-time
FileServiceReadyResponse:
type: object
required:
- service
- status
- environment
- files_base_url
- checked_at
properties:
service:
type: string
example: files
status:
type: string
example: ready
environment:
type: string
example: prod
files_base_url:
type: string
format: uri
example: "https://api.inttegro.com"
checked_at:
type: string
format: date-time
FileApiError:
type: object
description: Standard error response shape for file API endpoints.
properties:
message:
type: string
fix_code:
type: string
detail:
type: string
cause:
type: string
type:
type: string
code:
type: string
url:
type: string
format: uri
CreateFileRequest:
type: object
required:
- file
- purpose
properties:
file:
type: string
format: binary
description: Binary file part to store.
purpose:
type: string
description: File purpose policy to apply.
example: product_image
title:
type: string
description: Optional display title for the file.
example: Hero product image
custom_data:
type: string
description: JSON object encoded as a string. Values must be strings.
example: '{"product_id":"prod_123"}'
LookupFileRequest:
type: object
required:
- file_id
properties:
file_id:
type: string
example: file_2xC7k9gK5yQnZ4w8P1sT6vR3
PageFilesRequest:
type: object
properties:
purpose:
type: string
example: product_image
status:
type: string
enum: [uploading, processing, available, failed, deleted]
example: available
page_number:
type: integer
minimum: 1
example: 1
page_size:
type: integer
minimum: 1
example: 25
created_after:
type: string
format: date-time
created_before:
type: string
format: date-time
FileContentsRequest:
type: object
required:
- file_id
properties:
file_id:
type: string
example: file_2xC7k9gK5yQnZ4w8P1sT6vR3
disposition:
type: string
enum: [attachment, inline]
default: attachment
delivery:
type: string
enum: [stream, redirect]
default: stream
DeleteFileRequest:
type: object
required:
- file_id
properties:
file_id:
type: string
example: file_2xC7k9gK5yQnZ4w8P1sT6vR3
FileResponse:
type: object
required: [file]
properties:
file:
$ref: '#/components/schemas/FileObject'
FilePageResponse:
type: object
required: [page]
properties:
page:
$ref: '#/components/schemas/FilePage'
FilePage:
type: object
required:
- number
- size
- files
properties:
number:
type: integer
example: 1
size:
type: integer
example: 1
files:
type: array
items:
$ref: '#/components/schemas/FileObject'
FileObject:
type: object
description: Public file metadata. Storage provider details, object keys, and idempotency internals are not exposed.
required:
- id
- purpose
- status
- scan_status
- content_type
- size
- checksum_sha256
- created_by
- source
- storage
- created_at
- updated_at
properties:
id:
type: string
example: file_2xC7k9gK5yQnZ4w8P1sT6vR3
purpose:
type: string
example: product_image
status:
type: string
enum: [uploading, processing, available, failed, deleted]
scan_status:
type: string
enum: [pending, passed, failed, skipped]
name:
type: string
example: Hero image
filename:
type: string
example: hero.png
content_type:
type: string
example: image/png
size:
type: integer
format: int64
description: Original byte size.
example: 384221
checksum_sha256:
type: string
example: 02c26c6e49b2c332c8fb95d9f6a7c4f2d9e3f1f5a63f0b1a9d2a0ba
created_by:
$ref: '#/components/schemas/FileActor'
source:
$ref: '#/components/schemas/FileSource'
media:
$ref: '#/components/schemas/FileMedia'
storage:
$ref: '#/components/schemas/PublicFileStorage'
delivery:
$ref: '#/components/schemas/FileDelivery'
latest_error:
$ref: '#/components/schemas/FileLatestError'
custom_data:
$ref: '#/components/schemas/CustomData'
metadata:
$ref: '#/components/schemas/FileMetadata'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
available_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
FileUploadReceipt:
type: object
required: [content_type, created_at, id, size, status]
properties:
content_type:
type: string
created_at:
type: string
format: date-time
filename:
type: string
id:
type: string
name:
type: string
size:
type: integer
format: int64
minimum: 0
status:
type: string
enum: [uploading, processing, available, failed, deleted]
FileActor:
type: object
required: [type]
properties:
type:
type: string
example: api_key
id:
type: string
name:
type: string
email:
type: string
format: email
FileSource:
type: object
properties:
type:
type: string
enum: [direct, upload_request, service]
example: direct
service:
type: string
upload_request_id:
type: string
FileMedia:
type: object
properties:
kind:
type: string
example: image
width:
type: integer
format: int64
height:
type: integer
format: int64
duration_ms:
type: integer
format: int64
page_count:
type: integer
format: int64
frame_count:
type: integer
format: int64
color_space:
type: string
has_alpha:
type: boolean
codec:
type: string
aspect_ratio:
type: string
PublicFileStorage:
type: object
required:
- encoding
- stored_size
properties:
encoding:
type: string
enum: [identity, br]
description: Encoding of the stored representation.
stored_size:
type: integer
format: int64
description: Stored byte size after any lossless encoding.
FileDelivery:
type: object
description: Purpose-authorized public delivery metadata for browser-rendered assets. Callers should store file IDs as canonical references and treat these URLs as render URLs.
properties:
public_url:
type: string
format: uri
description: Unsigned CDN URL for public-safe assets such as product images.
example: https://assets.inttegro.com/public/assets/file_2xC7k9gK5yQnZ4w8P1sT6vR3/original
cache_control:
type: string
example: public, max-age=31536000, immutable
content_type:
type: string
example: image/png
FileLatestError:
type: object
properties:
code:
type: string
message:
type: string
retryable:
type: boolean
at:
type: string
format: date-time
CreateFileLinkRequest:
type: object
required:
- file_id
properties:
file_id:
type: string
example: file_2xC7k9gK5yQnZ4w8P1sT6vR3
delivery:
$ref: '#/components/schemas/FileLinkDelivery'
access:
$ref: '#/components/schemas/FileLinkAccessRequest'
created_by:
$ref: '#/components/schemas/FileActorInput'
custom_data:
$ref: '#/components/schemas/CustomData'
expires_at:
type: string
format: date-time
LookupFileLinkRequest:
type: object
required:
- id
properties:
id:
type: string
example: flink_8pQz3LkY6mN2vT9sB4cD1eF0
PageFileLinksRequest:
type: object
properties:
file_id:
type: string
status:
type: string
enum: [active, revoked, expired, disabled]
page_number:
type: integer
minimum: 1
page_size:
type: integer
minimum: 1
RevokeFileLinkRequest:
type: object
required:
- id
properties:
id:
type: string
revoked_by:
$ref: '#/components/schemas/FileActorInput'
CreateFileLinkResponse:
type: object
required: [file_link, url]
properties:
file_link:
$ref: '#/components/schemas/FileLinkObject'
url:
type: string
format: uri
description: Public capability URL. Treat as bearer-secret material.
FileLinkResponse:
type: object
required: [file_link]
properties:
file_link:
$ref: '#/components/schemas/FileLinkObject'
FileLinkPageResponse:
type: object
required: [page]
properties:
page:
$ref: '#/components/schemas/FileLinkPage'
FileLinkPage:
type: object
required: [file_links, number, size]
properties:
number:
type: integer
size:
type: integer
file_links:
type: array
items:
$ref: '#/components/schemas/FileLinkObject'
FileLinkObject:
type: object
description: Public file link metadata. Token hashes and provider URLs are not exposed.
required: [access, active, created_at, created_by, delivery, expires_at, file_id, id, kind, purpose, status, updated_at]
properties:
id:
type: string
kind:
type: string
enum: [public]
file_id:
type: string
purpose:
type: string
status:
type: string
enum: [active, revoked, expired, disabled]
active:
type: boolean
delivery:
$ref: '#/components/schemas/FileLinkDelivery'
access:
$ref: '#/components/schemas/FileLinkAccess'
created_by:
$ref: '#/components/schemas/FileLinkActor'
revoked_by:
$ref: '#/components/schemas/FileLinkActor'
custom_data:
$ref: '#/components/schemas/CustomData'
metadata:
$ref: '#/components/schemas/FileMetadata'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
revoked_at:
type: string
format: date-time
FileLinkActor:
type: object
required: [type]
properties:
email:
type: string
format: email
id:
type: string
name:
type: string
type:
type: string
FileActorInput:
type: object
properties:
email:
type: string
id:
type: string
name:
type: string
type:
type: string
FileLinkDelivery:
type: object
properties:
mode:
type: string
enum: [redirect, download, inline]
default: download
filename:
type: string
content_type:
type: string
disposition:
type: string
FileLinkAccessRequest:
type: object
properties:
max_accesses:
type: integer
format: int64
allow_download:
type: boolean
allowed_origins:
type: array
items:
type: string
allowed_ip_ranges:
type: array
items:
type: string
FileLinkAccess:
type: object
properties:
max_accesses:
type: integer
format: int64
access_count:
type: integer
format: int64
last_accessed_at:
type: string
format: date-time
allow_download:
type: boolean
allowed_origins:
type: array
items:
type: string
CreateUploadRequestRequest:
type: object
required:
- purpose
properties:
purpose:
type: string
example: support_document
constraints:
$ref: '#/components/schemas/UploadRequestConstraints'
display:
$ref: '#/components/schemas/UploadRequestDisplay'
subject:
$ref: '#/components/schemas/FileParty'
recipient:
$ref: '#/components/schemas/FileParty'
resource:
$ref: '#/components/schemas/FileResource'
requester:
$ref: '#/components/schemas/FileActorInput'
attempts:
$ref: '#/components/schemas/UploadRequestAttemptsRequest'
custom_data:
$ref: '#/components/schemas/CustomData'
expires_at:
type: string
format: date-time
LookupUploadRequestRequest:
type: object
required:
- id
properties:
id:
type: string
example: uplreq_1gK9pQ4vL8mN2sT5wX7yZ0
PageUploadRequestsRequest:
type: object
properties:
purpose:
type: string
status:
type: string
enum: [pending, uploading, fulfilled, expired, canceled, failed]
resource:
$ref: '#/components/schemas/FileResource'
page_number:
type: integer
minimum: 1
page_size:
type: integer
minimum: 1
CancelUploadRequestRequest:
type: object
required:
- id
properties:
id:
type: string
canceled_by:
$ref: '#/components/schemas/FileActorInput'
FulfillUploadRequestRequest:
type: object
required:
- file
properties:
file:
type: string
format: binary
ReviewUploadRequestAttemptRequest:
oneOf:
- $ref: '#/components/schemas/ReviewUploadRequestAttemptByIDRequest'
- $ref: '#/components/schemas/ReviewUploadRequestAttemptByOrdinalRequest'
ReviewUploadRequestAttemptByIDRequest:
type: object
required: [attempt_id, decision, id]
additionalProperties: false
properties:
attempt_id:
type: string
minLength: 1
decision:
type: string
enum: [approved, rejected]
id:
type: string
minLength: 1
public_message:
type: string
reasons:
type: array
items:
$ref: '#/components/schemas/UploadRequestReviewReasonInput'
ReviewUploadRequestAttemptByOrdinalRequest:
type: object
required: [attempt_ordinal, decision, id]
additionalProperties: false
properties:
attempt_ordinal:
type: integer
format: int64
minimum: 1
decision:
type: string
enum: [approved, rejected]
id:
type: string
minLength: 1
public_message:
type: string
reasons:
type: array
items:
$ref: '#/components/schemas/UploadRequestReviewReasonInput'
UploadRequestReviewReasonInput:
type: object
required: [code, message]
additionalProperties: false
properties:
code:
type: string
minLength: 1
message:
type: string
minLength: 1
param:
type: string
UploadRequestResponse:
type: object
required: [upload_request]
properties:
upload_request:
$ref: '#/components/schemas/UploadRequestObject'
UploadRequestWithAttemptResponse:
type: object
required: [upload_request]
properties:
upload_request:
$ref: '#/components/schemas/UploadRequestWithAttemptObject'
UploadRequestPageResponse:
type: object
required: [page]
properties:
page:
$ref: '#/components/schemas/UploadRequestPage'
UploadRequestPage:
type: object
required: [number, size, upload_requests]
properties:
number:
type: integer
size:
type: integer
upload_requests:
type: array
items:
$ref: '#/components/schemas/UploadRequestObject'
FulfillUploadRequestResponse:
type: object
required: [file, upload_request]
properties:
upload_request:
$ref: '#/components/schemas/UploadRequestWithAttemptObject'
file:
$ref: '#/components/schemas/FileUploadReceipt'
UploadRequestValidationErrorResponse:
type: object
required: [error, upload_request]
properties:
upload_request:
$ref: '#/components/schemas/UploadRequestWithAttemptObject'
error:
type: object
required:
- code
- message
- retryable
properties:
code:
type: string
param:
type: string
message:
type: string
retryable:
type: boolean
UploadRequestObject:
type: object
description: Public upload request metadata. Token hashes are not exposed.
required: [active, attempts, constraints, created_at, display, expires_at, id, purpose, recipient, requester, resource, status, subject, updated_at]
properties:
id:
type: string
purpose:
type: string
status:
type: string
enum: [pending, uploading, fulfilled, expired, canceled, failed]
active:
type: boolean
file_id:
type: string
upload_url:
type: string
format: uri
description: Public capability URL returned when available. Treat as bearer-secret material.
constraints:
$ref: '#/components/schemas/UploadRequestConstraints'
display:
$ref: '#/components/schemas/UploadRequestDisplay'
subject:
$ref: '#/components/schemas/FileParty'
recipient:
$ref: '#/components/schemas/FileParty'
resource:
$ref: '#/components/schemas/FileResource'
requester:
$ref: '#/components/schemas/UploadRequestActor'
attempts:
$ref: '#/components/schemas/UploadRequestAttempts'
latest_error:
$ref: '#/components/schemas/UploadRequestLatestError'
canceled_by:
$ref: '#/components/schemas/UploadRequestActor'
custom_data:
$ref: '#/components/schemas/CustomData'
metadata:
$ref: '#/components/schemas/FileMetadata'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
uploading_at:
type: string
format: date-time
fulfilled_at:
type: string
format: date-time
expired_at:
type: string
format: date-time
canceled_at:
type: string
format: date-time
UploadRequestWithAttemptObject:
allOf:
- $ref: '#/components/schemas/UploadRequestObject'
- type: object
properties:
attempt:
$ref: '#/components/schemas/UploadRequestAttempt'
UploadRequestConstraints:
type: object
properties:
min_size:
type: integer
format: int64
max_size:
type: integer
format: int64
exact_size:
type: integer
format: int64
content_types:
type: array
items:
type: string
extensions:
type: array
items:
type: string
filename:
type: string
UploadRequestDisplay:
type: object
properties:
title:
type: string
description:
type: string
help_text:
type: string
FileParty:
type: object
properties:
type:
type: string
id:
type: string
name:
type: string
email:
type: string
format: email
FileResource:
type: object
properties:
type:
type: string
example: product
id:
type: string
name:
type: string
UploadRequestAttemptsRequest:
type: object
properties:
max_attempts:
type: integer
format: int64
minimum: 0
UploadRequestAttempts:
type: object
required: [attempt_count, failed_attempt_count]
properties:
max_attempts:
type: integer
format: int64
attempt_count:
type: integer
format: int64
failed_attempt_count:
type: integer
format: int64
last_attempted_at:
type: string
format: date-time
UploadRequestActor:
type: object
required: [type]
properties:
email:
type: string
id:
type: string
name:
type: string
type:
type: string
UploadRequestAttempt:
type: object
required: [attempted_at, id, ordinal, status, upload_request_id]
properties:
attempted_at:
type: string
format: date-time
content_type:
type: string
declared_size:
type: integer
format: int64
minimum: 0
error:
$ref: '#/components/schemas/UploadRequestLatestError'
failed_at:
type: string
format: date-time
file_id:
type: string
filename:
type: string
id:
type: string
ordinal:
type: integer
format: int64
minimum: 1
review:
$ref: '#/components/schemas/UploadRequestReview'
status:
type: string
succeeded_at:
type: string
format: date-time
upload_request_id:
type: string
UploadRequestReview:
type: object
required: [created_at, decision, reviewed_at, type]
properties:
created_at:
type: string
format: date-time
decision:
type: string
enum: [approved, rejected]
file_id:
type: string
public_message:
type: string
reasons:
type: array
items:
$ref: '#/components/schemas/UploadRequestReviewReason'
reviewed_at:
type: string
format: date-time
type:
type: string
enum: [automatic, manual]
UploadRequestReviewReason:
type: object
required: [code, message]
properties:
code:
type: string
minLength: 1
message:
type: string
minLength: 1
param:
type: string
UploadRequestLatestError:
type: object
properties:
code:
type: string
param:
type: string
message:
type: string
retryable:
type: boolean
at:
type: string
format: date-time
FileReferenceReconcileRequest:
type: object
additionalProperties: false
required:
- resource_type
- resource_id
properties:
resource_type:
type: string
minLength: 1
description: Non-blank resource type after trimming.
example: product
resource_id:
type: string
minLength: 1
description: Non-blank resource ID after trimming.
example: prod_123
references:
type: array
items:
$ref: '#/components/schemas/FileReferenceInput'
FileReferenceInput:
type: object
additionalProperties: false
required:
- file_id
- field
properties:
file_id:
type: string
minLength: 1
description: Non-blank file ID after trimming.
field:
type: string
minLength: 1
description: Non-blank resource field after trimming.
example: media.gallery[0]
reference:
type: string
description: Caller-supplied file or file link reference.
reference_kind:
type: string
description: Caller-defined reference kind; `file` and `file_link` are recommended.
purpose:
type: string
FileReferenceReconcileResponse:
type: object
required: [reconciled]
additionalProperties: false
properties:
reconciled:
type: boolean
enum: [true]
PaymentNextAction:
type: object
additionalProperties: false
description: Next action required to complete a payment
nullable: true
required:
- type
properties:
type:
type: string
enum: [confirm_payment, execute, redirect, authorize_payment, request_confirmation]
description: Type of action required
example: "confirm_payment"
confirm_payment:
type: object
additionalProperties: false
description: Details for customer payment confirmation
required: [expires_at, scheme, confirmed, status]
properties:
expires_at:
type: string
format: date-time
description: When the confirmation request expires
example: "2025-10-24T21:16:11.917533316Z"
scheme:
type: string
description: Authentication scheme used
example: "zcommerce_defined_auth"
request:
type: object
additionalProperties: false
description: Confirmation request details
required: [id, recipient, sent_via, token_size, sender_id]
properties:
id:
type: string
description: Unique identifier for the confirmation request
example: "Jmjup0uRSVI2LvllHfdJ"
recipient:
type: string
description: Recipient of the confirmation token
example: "0242057831"
sent_via:
type: string
enum: [sms, email, push]
description: Channel used to send the token
example: "sms"
token_size:
type: integer
description: Number of digits in the token
example: 6
sender_id:
type: string
description: Sender ID for the message
example: "zverify"
status:
type: string
description: Current request status
attempt:
type: object
additionalProperties: false
description: Latest confirmation attempt
required: [status, confirmed, reason, created_at]
properties:
status:
type: string
description: Attempt status
example: "pending"
confirmed:
type: boolean
description: Whether the confirmation has succeeded
example: false
reason:
type: string
description: Reason for the current attempt state
example: "awaiting_customer_confirmation"
executed_at:
type: string
format: date-time
description: When the attempt was executed
created_at:
type: string
format: date-time
description: When the attempt was created
confirmed:
type: boolean
description: Whether the payment confirmation has completed
example: false
status:
type: string
description: Confirmation status
example: "pending"
redirect:
type: object
additionalProperties: false
description: Details for redirect action
required: [redirect_url, valid_until]
properties:
redirect_url:
type: string
format: uri
description: URL to redirect the customer to
example: "https://pages.inttegro.com/authorize?order_id=3deNYydEjIGCqK1tGlAPwJYSCsZnQ4XGF"
valid_until:
type: string
format: date-time
description: When the redirect URL expires
latest_visit:
type: object
additionalProperties: false
description: Latest redirect visit details
required: [user_agent, ip_address, at]
properties:
user_agent:
type: string
ip_address:
type: string
at:
type: string
format: date-time
authorize:
type: object
additionalProperties: false
description: Details for authorization action
required: [beneficiary, scheme, expires_at]
properties:
beneficiary:
type: string
description: Beneficiary requiring authorization
scheme:
type: string
description: Authorization scheme
expires_at:
type: string
format: date-time
description: When the authorization request expires
request_confirmation:
type: object
additionalProperties: false
description: Details for requesting a fresh customer confirmation.
properties:
last_request:
type: object
additionalProperties: false
required: [id, recipient, sent_via, token_size, sender_id]
properties:
id:
type: string
recipient:
type: string
sent_via:
type: string
enum: [sms, email, push]
token_size:
type: integer
sender_id:
type: string
status:
type: string
after:
type: string
format: date-time
CreateOrderNewCustomer:
type: object
required:
- customer_data
- line_items
properties:
customer_data:
$ref: '#/components/schemas/CustomerData'
payment_method_data:
$ref: '#/components/schemas/PaymentMethodData'
description: New payment instrument details to use when executing payment for the order.
number:
type: string
description: Optional order number for reference. When omitted, Inttegro uses the generated order ID.
example: "ORDER-NUMBER-2"
receipt_number:
type: string
description: Optional receipt number for downstream reconciliation. Uses the same length rules as `number`.
example: "RCPT-NUMBER-2"
statement_descriptor:
type: string
description: Optional statement descriptor shown on the customer's bank statement
example: "STMTDESC"
maxLength: 22
statement_descriptor_prefix:
type: string
description: Optional static prefix used to build the statement descriptor as `prefix*order_id`. Mutually exclusive with `statement_descriptor`.
example: "LINE"
minLength: 2
maxLength: 10
execute_payment:
type: boolean
description: Whether to execute payment immediately after order creation
default: false
finalize:
type: boolean
description: Whether to explicitly finalize the order. When true, the order is finalized regardless of payment state. When false or omitted, finalization follows default heuristics (finalize if payment is executable).
default: false
request_meta:
type: object
description: Optional metadata controlling request processing
properties:
idempotency_key:
type: string
description: Unique key to prevent duplicate order creation
checkout_settings:
type: object
description: Checkout and payment flow configuration. Strongly recommended to provide both redirect_url and cancel_url for a delightful customer experience.
properties:
redirect_url:
type: string
format: uri
description: URL to redirect customer after payment completion
example: "https://example.com/order/complete"
cancel_url:
type: string
format: uri
description: URL to redirect customer if they cancel payment
example: "https://example.com/order/cancelled"
invoice_settings:
$ref: '#/components/schemas/InvoiceSettings'
payout_settings:
$ref: '#/components/schemas/OrderPayoutSettingsRequest'
line_items:
type: array
description: Items included in the order. Product line items may use inline product data, `product_id` with explicit `price`, or `product_id` with `price_id`.
minItems: 1
items:
$ref: '#/components/schemas/LineItem'
custom_data:
$ref: '#/components/schemas/CustomData'
billing_details:
$ref: '#/components/schemas/BillingDetails'
shipping:
$ref: '#/components/schemas/Shipping'
CreateOrderExistingCustomer:
type: object
required:
- customer_id
- line_items
properties:
customer_id:
type: string
description: ID of existing customer
example: "cu_dZjC0hAsYi2dObveagp6pJLoXvgmicoBQj8KuNOZ"
payment_method_id:
type: string
description: ID of saved payment method to use
example: "OaNWqiOeYa5OJMcxUPZC1pLCW94Ne3toks4HIVPRa"
payment_method_data:
$ref: '#/components/schemas/PaymentMethodData'
description: New payment instrument details to use instead of a saved payment method.
receipt_number:
type: string
description: Optional receipt number for downstream reconciliation. Uses the same length rules as `number`.
example: "RCPT-NUMBER-2"
statement_descriptor:
type: string
description: Optional statement descriptor shown on the customer's bank statement
maxLength: 22
statement_descriptor_prefix:
type: string
description: Optional static prefix used to build the statement descriptor as `prefix*order_id`. Mutually exclusive with `statement_descriptor`.
example: "LINE"
minLength: 2
maxLength: 10
execute_payment:
type: boolean
description: Whether to execute payment immediately
default: false
finalize:
type: boolean
description: Whether to explicitly finalize the order. When true, the order is finalized regardless of payment state. When false or omitted, finalization follows default heuristics (finalize if payment is executable).
default: false
request_meta:
type: object
description: Optional metadata controlling request processing
properties:
idempotency_key:
type: string
description: Unique key to prevent duplicate order creation
checkout_settings:
type: object
description: Checkout and payment flow configuration. Strongly recommended to provide both redirect_url and cancel_url for a delightful customer experience.
properties:
redirect_url:
type: string
format: uri
description: URL to redirect customer after payment completion
example: "https://example.com/order/complete"
cancel_url:
type: string
format: uri
description: URL to redirect customer if they cancel payment
example: "https://example.com/order/cancelled"
invoice_settings:
$ref: '#/components/schemas/InvoiceSettings'
payout_settings:
$ref: '#/components/schemas/OrderPayoutSettingsRequest'
line_items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/LineItem'
custom_data:
$ref: '#/components/schemas/CustomData'
billing_details:
$ref: '#/components/schemas/BillingDetails'
shipping:
$ref: '#/components/schemas/Shipping'
InvoiceSettings:
type: object
description: Order-level invoice rendering data. Pages uses this data when rendering invoice web and download views.
properties:
number:
type: string
description: Optional invoice number. When omitted, invoice delivery falls back to the order number and then the order ID for labels.
example: "INV-1001"
memo:
type: string
description: Optional invoice memo.
example: "Thanks for your order."
footer:
type: string
description: Optional invoice footer.
example: "Payment due within 7 days."
custom_data:
$ref: '#/components/schemas/CustomData'
OrderPayoutSettingsRequest:
type: object
properties:
destination:
type: object
required: [financial_account_id]
properties:
financial_account_id:
type: string
description: Same-currency financial account with push capability enabled
enable_fx:
type: boolean
enum: [false]
default: false
description: Omit this field or set it to false. Cross-currency payouts are not currently available.
CustomerData:
type: object
required:
- name
- email_address
- phone_number
properties:
name:
type: string
description: Customer's full name
example: "Customer Name"
email_address:
type: string
format: email
description: Customer's email address
example: "customer@example.com"
phone_number:
type: string
description: Customer's phone number
example: "0559714200"
reference:
type: string
description: External reference ID for the customer
custom_data:
$ref: '#/components/schemas/CustomDataInput'
CustomerAddressInput:
type: object
required: [country]
properties:
city:
type: string
country:
type: string
line1:
type: string
line2:
type: string
name:
type: string
phone_number:
type: string
post_code:
type: string
region:
type: string
CreateCustomerRequest:
type: object
required: [name]
properties:
billing_address:
$ref: '#/components/schemas/CustomerAddressInput'
custom_data:
$ref: '#/components/schemas/CustomDataInput'
email_address:
type: string
minLength: 3
maxLength: 254
name:
type: string
maxLength: 200
phone_number:
type: string
minLength: 7
maxLength: 20
reference:
type: string
minLength: 1
maxLength: 100
shipping_address:
$ref: '#/components/schemas/CustomerAddressInput'
title:
type: string
minLength: 1
maxLength: 20
UpdateCustomerRequest:
type: object
required: [customer_id]
properties:
billing_address:
$ref: '#/components/schemas/CustomerAddressInput'
custom_data:
$ref: '#/components/schemas/CustomDataInput'
customer_id:
type: string
email_address:
type: string
minLength: 3
maxLength: 254
name:
type: string
minLength: 1
maxLength: 200
phone_number:
type: string
minLength: 7
maxLength: 20
reference:
type: string
minLength: 1
maxLength: 100
shipping_address:
$ref: '#/components/schemas/CustomerAddressInput'
suffix:
type: string
minLength: 1
maxLength: 10
title:
type: string
minLength: 1
maxLength: 20
PageCustomersRequest:
type: object
required: [page_number]
properties:
page_number:
type: integer
minimum: 1
maximum: 10
page_size:
type: integer
minimum: 1
maximum: 256
default: 256
LookupCustomerRequest:
type: object
required:
- customer_id
properties:
customer_id:
type: string
minLength: 1
maxLength: 100
description: The customer identifier (with or without cu_ prefix)
example: "cu_abc123xyz"
Customer:
type: object
required: [balance, created_at, fingerprint, guest, id, name]
properties:
balance:
$ref: '#/components/schemas/CustomerBalance'
billing_address:
$ref: '#/components/schemas/CustomerAddress'
created_at:
type: string
format: date-time
custom_data:
$ref: '#/components/schemas/CustomData'
email_address:
type: string
fingerprint:
type: string
description: Application-scoped value for spotting possible duplicate customer records. Matching nonempty fingerprints within the same application indicate that the records likely belong to the same buyer. Compare fingerprints only within that application, and continue to use each customer ID for API operations.
guest:
type: boolean
id:
type: string
name:
type: string
phone_number:
type: string
reference:
type: string
shipping_address:
$ref: '#/components/schemas/CustomerAddress'
suffix:
type: string
title:
type: string
updated_at:
type: string
format: date-time
CustomerAddress:
type: object
required: [country]
properties:
city:
type: string
country:
type: string
line1:
type: string
line2:
type: string
name:
type: string
phone_number:
type: string
post_code:
type: string
region:
type: string
CustomerResponse:
type: object
properties:
customer:
$ref: '#/components/schemas/Customer'
error:
$ref: '#/components/schemas/Error'
CustomerPage:
type: object
required: [customers, number, size]
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
number:
type: integer
size:
type: integer
description: Number of customers returned
ProductAttribute:
type: object
required: [name, value]
properties:
name:
type: string
maxLength: 100
value:
type: string
maxLength: 500
ProductDimensions:
type: object
maxProperties: 1
description: At most one of `physical`, `digital`, or `custom`.
properties:
physical:
type: object
properties:
weight_unit:
type: string
weight:
type: number
minimum: 0
size:
type: number
minimum: 0
description: Legacy alias for weight in requests.
volume_unit:
type: string
volume:
type: number
minimum: 0
length:
type: number
minimum: 0
height:
type: number
minimum: 0
width:
type: number
minimum: 0
digital:
type: object
properties:
bytes:
type: number
minimum: 0
size_unit:
type: string
size:
type: number
minimum: 0
custom:
type: object
properties:
size_unit:
type: string
size:
type: number
minimum: 0
details:
$ref: '#/components/schemas/ProductDimensionDetails'
ProductMedia:
type: object
properties:
hero_image:
type: string
thumbnail:
type: string
web_page_url:
type: string
brand_logo:
type: string
infographic:
type: string
promo_video:
type: string
demo_video:
type: string
gallery:
type: array
items:
type: string
downloads:
type: array
items:
type: string
ProductShipmentInput:
type: object
required: [type]
properties:
type:
type: string
enum: [delivery, download, render, stream]
ProductShipment:
type: object
additionalProperties: false
required: [type]
properties:
type:
type: string
enum: [delivery, download, render, service, stream]
delivery:
$ref: '#/components/schemas/ProductDelivery'
download:
$ref: '#/components/schemas/ProductDownload'
render:
$ref: '#/components/schemas/ProductRender'
service:
$ref: '#/components/schemas/ProductService'
stream:
$ref: '#/components/schemas/ProductStream'
ProductDelivery:
type: object
additionalProperties: false
description: Delivery fulfillment marker.
ProductDownload:
type: object
additionalProperties: false
description: Download fulfillment marker.
ProductRender:
type: object
additionalProperties: false
description: Rendered fulfillment marker.
ProductService:
type: object
additionalProperties: false
description: Service fulfillment marker.
ProductStream:
type: object
additionalProperties: false
description: Streaming fulfillment marker.
CreateProductRequest:
type: object
required:
- type
- name
properties:
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type - determines fulfillment requirements
example: "physical"
reference:
type: string
minLength: 1
maxLength: 100
description: External reference or SKU from your system
example: "SKU-12345"
name:
type: string
minLength: 1
maxLength: 100
description: Customer-facing product name
example: "Premium Cotton T-Shirt"
description:
type: string
maxLength: 200
description: Short product description or tagline
example: "Comfortable everyday wear"
about:
type: string
maxLength: 5000
description: Full product description with details and features
example: "Made from 100% organic cotton, this premium t-shirt..."
tax_code:
type: string
maxLength: 50
description: Tax classification code for tax calculations
example: "TXCD001"
category:
type: string
maxLength: 100
description: Product category for organization
shipment:
$ref: '#/components/schemas/ProductShipmentInput'
dimensions:
$ref: '#/components/schemas/ProductDimensions'
unit_dimension:
type: string
maxLength: 20
media:
$ref: '#/components/schemas/ProductMedia'
attributes:
type: array
description: Product attributes (size, color, material, etc.)
items:
$ref: '#/components/schemas/ProductAttribute'
publish:
type: boolean
description: Whether to publish the product immediately
custom_data:
$ref: '#/components/schemas/CustomData'
LookupProductRequest:
type: object
required:
- product_id
properties:
product_id:
type: string
description: Product ID to lookup
example: "prod_abc123"
UpdateProductRequest:
type: object
required:
- product_id
allOf:
- not:
required: [images, media]
properties:
product_id:
type: string
description: Product ID to update
example: "prod_abc123"
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type. If provided, it must equal the existing type.
name:
type: string
minLength: 1
maxLength: 100
description: Product name
description:
type: string
maxLength: 200
description: Short description
about:
type: string
description: Full description
tax_code:
type: string
description: Tax classification code
category:
type: string
description: Product category
shipment:
$ref: '#/components/schemas/ProductShipmentInput'
dimensions:
$ref: '#/components/schemas/ProductDimensions'
unit_dimension:
type: string
maxLength: 20
media:
$ref: '#/components/schemas/ProductMedia'
images:
type: array
description: Legacy image list. Mutually exclusive with `media`.
items:
type: string
attributes:
type: array
description: Product attributes
items:
$ref: '#/components/schemas/ProductAttribute'
custom_data:
$ref: '#/components/schemas/CustomData'
AddProductPriceRequest:
type: object
required:
- product_id
oneOf:
- title: Fixed amount
required: [type, fixed_amount]
properties:
type:
enum: [fixed_amount]
not:
anyOf:
- required: [amount]
- required: [customer_selected_amount]
- title: Customer-selected amount
required: [type, customer_selected_amount, product_id]
properties:
type:
enum: [customer_selected_amount]
not:
anyOf:
- required: [amount]
- required: [fixed_amount]
properties:
product_id:
type: string
description: Product ID to attach the new price to
example: "prod_abc123"
label:
type: string
maxLength: 100
description: Optional short label for the new price
example: "Wholesale"
about:
type: string
maxLength: 500
description: Optional internal description for the new price
example: "Preferred rate for repeat buyers"
type:
type: string
enum: [fixed_amount, customer_selected_amount]
description: Price definition discriminator.
fixed_amount:
description: Required when type is fixed_amount.
$ref: '#/components/schemas/AmountParams'
customer_selected_amount:
description: Required when type is customer_selected_amount. Available only to Commerce internal services and Upper private beta organizations and applications.
$ref: '#/components/schemas/CustomerSelectedAmountParams'
AddProductPriceResponse:
type: object
properties:
price:
$ref: '#/components/schemas/CatalogPrice'
error:
$ref: '#/components/schemas/Error'
ProductPriceSummary:
type: object
required:
- id
- active
- type
oneOf:
- title: Fixed amount
required: [nominal, fixed_amount]
properties:
type:
enum: [fixed_amount]
not:
anyOf:
- required: [amount]
- required: [customer_selected_amount]
- title: Customer-selected amount
required: [customer_selected_amount]
properties:
type:
enum: [customer_selected_amount]
not:
anyOf:
- required: [nominal]
- required: [fixed_amount]
properties:
id:
type: string
description: Unique price identifier with pr_ prefix
example: "pr_xyz789"
active:
type: boolean
description: Whether this price is active and usable in new flows
example: true
label:
type: string
nullable: true
description: Short label for this price
example: "Wholesale"
type:
type: string
enum: [fixed_amount, customer_selected_amount]
description: Price definition discriminator
nominal:
deprecated: true
description: Legacy fixed price amount. Present only for fixed_amount prices.
$ref: '#/components/schemas/Amount'
fixed_amount:
description: Fixed price amount. Present only for fixed_amount prices.
$ref: '#/components/schemas/Amount'
customer_selected_amount:
description: Customer-selected amount configuration. Present only for customer_selected_amount prices.
$ref: '#/components/schemas/CustomerSelectedAmount'
ProductActionRequest:
type: object
required:
- product_id
properties:
product_id:
type: string
description: Product ID to perform action on
example: "prod_abc123"
ProductResponse:
type: object
properties:
product:
$ref: '#/components/schemas/Product'
error:
$ref: '#/components/schemas/Error'
UpdateProductResponse:
type: object
properties:
product:
$ref: '#/components/schemas/UpdatedProduct'
UpdatedProduct:
type: object
required: [id, name, type, created_at]
properties:
id:
type: string
description: Product identifier returned by the update operation.
name:
type: string
description:
type: string
about:
type: string
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
reference:
type: string
tax_code:
type: string
category:
type: string
custom_data:
$ref: '#/components/schemas/CustomData'
dimensions:
$ref: '#/components/schemas/ProductDimensions'
prices:
type: array
items:
$ref: '#/components/schemas/ProductPriceSummary'
unit_dim:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
CreatePurchaseIntentRequest:
type: object
required:
- quantity
allOf:
- oneOf:
- required:
- product
- required:
- product_id
- oneOf:
- required:
- price
- required:
- price_id
properties:
product:
type: object
description: Product selection with optional variant-set configuration. Use this instead of product_id.
required:
- id
properties:
id:
type: string
description: Product ID to sell through the Buy link
example: "prod_abc123"
variant_set_id:
type: string
description: Optional variant set ID the hosted checkout may use for sibling product selection
example: "pg_variantset123"
product_id:
type: string
description: App-owned product ID to sell through the Buy link when not using product
example: "prod_abc123"
price:
type: object
description: Price selection for the Buy link. Send exactly one of id or nominal and at most one of original or original_id.
allOf:
- oneOf:
- required:
- id
- required:
- nominal
- not:
properties:
original: {}
original_id: {}
required:
- original
- original_id
properties:
id:
type: string
description: Active, unarchived app-owned price ID that belongs to the selected product
example: "pr_xyz789"
nominal:
description: Inline offer amount when no price ID is provided
$ref: '#/components/schemas/PriceParams'
original:
type: object
description: Optional original price used for comparison display
allOf:
- oneOf:
- required:
- id
- required:
- nominal
properties:
id:
type: string
description: App-owned comparison price ID that belongs to the selected product
example: "pr_original123"
nominal:
description: Inline original price amount
$ref: '#/components/schemas/PriceParams'
original_id:
type: string
description: App-owned comparison price ID when not using original.id
example: "pr_original123"
price_id:
type: string
description: Active, unarchived app-owned price ID that belongs to the selected product
example: "pr_xyz789"
quantity:
type: object
description: Quantity bounds the Buy link should enforce. Omit max when the Buy link has no upper quantity bound. When present, max must be greater than or equal to min.
required:
- min
properties:
min:
type: integer
minimum: 1
description: Minimum quantity the customer can buy
example: 1
max:
type: integer
minimum: 1
description: Optional maximum quantity the customer can buy. It must be greater than or equal to min.
example: 5
usage:
type: object
description: Optional link-use policy. Omit to create a reusable Buy link.
not:
properties:
multi_use: {}
single_use: {}
required:
- single_use
- multi_use
properties:
single_use:
type: boolean
description: Creating the first order consumes the Buy link
example: true
multi_use:
type: boolean
description: The Buy link may create multiple orders
example: true
expires_at:
type: string
format: date-time
description: Future RFC3339 timestamp after which the Buy link stops accepting purchases
example: "2030-12-01T09:00:00Z"
presentation:
$ref: '#/components/schemas/CreatePurchaseIntentPresentation'
UpdatePurchaseIntentRequest:
type: object
anyOf:
- required:
- id
- required:
- purchase_intent_id
properties:
expires_at:
type: string
format: date-time
nullable: true
description: RFC3339 expiry timestamp, including a past time for immediate expiry, or null to clear expiry
id:
type: string
minLength: 1
description: Purchase intent ID to update. Send this or purchase_intent_id.
example: "sale_ABCXYZ"
quantity:
type: object
description: Replacement quantity bounds. Omit the object to preserve the current bounds. Within the object, min is required and omitting max removes the upper bound. When present, max must be greater than or equal to min.
required:
- min
properties:
min:
type: integer
minimum: 1
description: Minimum quantity the customer can buy
example: 1
max:
type: integer
minimum: 1
description: Optional maximum quantity the customer can buy. It must be greater than or equal to min.
example: 3
purchase_intent_id:
type: string
minLength: 1
description: Alias for id. If both are present, this value takes precedence.
example: "sale_ABCXYZ"
reactivate:
type: boolean
description: |
Clears the state that prevents new purchases. For canceled
Buy links this removes inactive_at. For expired Buy links this
clears an existing elapsed expires_at value. It does not remove
the order claim from a used single-use intent.
example: true
presentation:
$ref: '#/components/schemas/UpdatePurchaseIntentPresentation'
CreatePurchaseIntentPresentation:
type: object
description: Optional merchant-authored copy for the hosted Buy page. Omit it to use product-aware defaults.
required:
- buy_page
properties:
buy_page:
type: object
required:
- text
properties:
text:
type: object
minProperties: 1
properties:
checkout_section_title:
type: string
minLength: 1
maxLength: 80
description: Plain, single-line title shown above the Buy page form
example: Support this cause
amount_field_label:
type: string
minLength: 1
maxLength: 64
description: Plain, single-line label for a customer-selected amount field
example: Your contribution
primary_action_label:
type: string
minLength: 1
maxLength: 48
description: Plain, single-line label used for the ready primary action. Validation and loading labels remain system-owned.
example: Continue to contribute
UpdatePurchaseIntentPresentation:
type: object
description: Sparse Buy page copy update. Omit a field to preserve it, or send null to restore the product-aware default.
required:
- buy_page
properties:
buy_page:
type: object
required:
- text
properties:
text:
type: object
minProperties: 1
properties:
checkout_section_title:
type: string
nullable: true
minLength: 1
maxLength: 80
amount_field_label:
type: string
nullable: true
minLength: 1
maxLength: 64
primary_action_label:
type: string
nullable: true
minLength: 1
maxLength: 48
CancelPurchaseIntentRequest:
type: object
anyOf:
- required:
- id
- required:
- purchase_intent_id
properties:
id:
type: string
minLength: 1
description: Purchase intent ID to cancel. Send this or purchase_intent_id.
example: "sale_ABCXYZ"
purchase_intent_id:
type: string
minLength: 1
description: Alias for id. If both are present, this value takes precedence.
example: "sale_ABCXYZ"
LookupPurchaseIntentRequest:
type: object
required:
- id
properties:
id:
type: string
minLength: 1
description: Purchase intent ID to look up
example: "sale_ABCXYZ"
PagePurchaseIntentsRequest:
type: object
required:
- page_number
- page_size
properties:
page_number:
type: integer
minimum: 1
maximum: 10
description: One-based page number to retrieve
example: 1
page_size:
type: integer
minimum: 1
maximum: 256
description: Maximum number of purchase intents to return on this page
example: 20
PagePurchaseIntentsResponse:
type: object
additionalProperties: false
required:
- page
properties:
page:
type: object
additionalProperties: false
required:
- number
- purchase_intents
- size
properties:
number:
type: integer
description: One-based page number returned
example: 1
purchase_intents:
type: array
items:
$ref: '#/components/schemas/PurchaseIntent'
size:
type: integer
description: Number of purchase intents actually returned
example: 2
PurchaseIntentResponse:
type: object
additionalProperties: false
required:
- purchase_intent
properties:
purchase_intent:
$ref: '#/components/schemas/PurchaseIntent'
PurchaseIntentMerchant:
type: object
description: Merchant identity captured for the hosted checkout. Individual fields are omitted when unavailable.
properties:
app_name:
type: string
example: "Tea House"
organization_id:
type: string
example: "org_abc123"
organization_name:
type: string
example: "Tea House Ltd"
PurchaseIntentOriginalPrice:
type: object
required:
- active
- nominal
properties:
active:
type: boolean
description: Whether the resolved comparison price is active
example: true
id:
type: string
description: Catalog price ID when the comparison price is not inline
example: "pr_original123"
label:
type: string
description: Catalog price label when available
example: "Regular price"
nominal:
$ref: '#/components/schemas/Amount'
PurchaseIntentPrice:
type: object
required:
- active
- nominal
properties:
active:
type: boolean
description: Whether the resolved price can be used
example: true
id:
type: string
description: Catalog price ID when the offer price is not inline
example: "pr_xyz789"
label:
type: string
description: Catalog price label when available
example: "Campaign price"
nominal:
$ref: '#/components/schemas/Amount'
original:
$ref: '#/components/schemas/PurchaseIntentOriginalPrice'
PurchaseIntentProduct:
allOf:
- $ref: '#/components/schemas/PriceEmbeddedProduct'
- type: object
properties:
prices:
type: array
description: Non-archived catalog prices currently attached to the product
items:
$ref: '#/components/schemas/ProductPriceSummary'
variant_set_id:
type: string
description: Variant set configured for this Buy link
example: "pg_variantset123"
PurchaseIntentUsage:
type: object
description: Exactly one of multi_use or single_use is returned as true. Order is present after a single-use intent is consumed.
properties:
multi_use:
type: boolean
example: true
order:
$ref: '#/components/schemas/PurchaseIntentUsageOrder'
single_use:
type: boolean
example: true
PurchaseIntentUsageOrder:
type: object
required:
- created_at
- id
properties:
created_at:
type: string
format: date-time
description: When order creation consumed the single-use Buy link
id:
type: string
description: Order that consumed the Buy link
example: "or_abc123"
PurchaseIntentVariantAxis:
type: object
required:
- key
- label
- position
properties:
key:
type: string
example: "size"
label:
type: string
example: "Size"
position:
type: integer
example: 0
PurchaseIntentVariant:
type: object
required:
- active
- product_id
- variant_values
properties:
active:
type: boolean
example: true
position:
type: integer
example: 0
price:
$ref: '#/components/schemas/PurchaseIntentPrice'
product:
$ref: '#/components/schemas/PurchaseIntentProduct'
product_id:
type: string
example: "prod_variant123"
variant_values:
$ref: '#/components/schemas/VariantValues'
PurchaseIntentVariantSet:
type: object
required:
- active
- id
- name
- variant_axes
- variants
properties:
active:
type: boolean
example: true
default_product_id:
type: string
example: "prod_abc123"
description:
type: string
example: "Choose a tin size"
id:
type: string
example: "pg_variantset123"
name:
type: string
example: "Tin size"
reference:
type: string
example: "matcha-tin-size"
variant_axes:
type: array
items:
$ref: '#/components/schemas/PurchaseIntentVariantAxis'
variants:
type: array
items:
$ref: '#/components/schemas/PurchaseIntentVariant'
PurchaseIntent:
type: object
additionalProperties: false
required:
- allow_variants
- created_at
- id
- quantity
- status
- usage
properties:
allow_variants:
type: boolean
description: Whether the intent was configured with a variant set
example: false
created_at:
type: string
format: date-time
description: Creation timestamp
expires_at:
type: string
format: date-time
description: Timestamp at or after which the Buy link is expired
id:
type: string
description: Unique purchase intent identifier with sale_ prefix. Append it to https://pages.inttegro.com/buy/ to build the hosted Buy link.
example: "sale_ABCXYZ"
inactive_at:
type: string
format: date-time
description: When the Buy link was explicitly canceled
merchant:
$ref: '#/components/schemas/PurchaseIntentMerchant'
price:
$ref: '#/components/schemas/PurchaseIntentPrice'
presentation:
$ref: '#/components/schemas/PurchaseIntentPresentation'
product:
$ref: '#/components/schemas/PurchaseIntentProduct'
quantity:
type: object
description: Quantity bounds enforced by the hosted checkout. max is omitted when the offer has no upper bound.
required:
- min
properties:
min:
type: integer
minimum: 1
description: Minimum quantity the hosted checkout allows
example: 1
max:
type: integer
minimum: 1
description: Optional maximum quantity the hosted checkout allows. It is always greater than or equal to min when present.
example: 5
status:
type: string
enum: [active, expired, inactive, used]
description: Effective lifecycle state derived from expiry, cancellation, and single-use order creation
example: "active"
updated_at:
type: string
format: date-time
description: Last mutation timestamp
usage:
$ref: '#/components/schemas/PurchaseIntentUsage'
variant_set:
$ref: '#/components/schemas/PurchaseIntentVariantSet'
PurchaseIntentPresentation:
type: object
additionalProperties: false
properties:
buy_page:
type: object
additionalProperties: false
properties:
text:
type: object
additionalProperties: false
properties:
checkout_section_title:
type: string
amount_field_label:
type: string
primary_action_label:
type: string
Product:
type: object
required:
- id
- type
- name
- active
- created_at
properties:
id:
type: string
description: Unique product identifier with prod_ prefix
example: "prod_abc123xyz"
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type
example: "physical"
reference:
type: string
nullable: true
description: External reference or SKU
example: "SKU-12345"
name:
type: string
description: Product name
example: "Premium Cotton T-Shirt"
description:
type: string
nullable: true
description: Short description
example: "Comfortable everyday wear"
about:
type: string
nullable: true
description: Full product description
tax_code:
type: string
nullable: true
description: Tax classification code
category:
type: string
description: Product category
prices:
type: array
nullable: true
description: Non-archived prices that belong to this product
items:
$ref: '#/components/schemas/ProductPriceSummary'
shipment:
$ref: '#/components/schemas/ProductShipment'
media:
$ref: '#/components/schemas/ProductMedia'
attributes:
type: array
description: Product attributes
items:
$ref: '#/components/schemas/ProductAttribute'
dimensions:
$ref: '#/components/schemas/ProductDimensions'
custom_data:
$ref: '#/components/schemas/CustomData'
active:
type: boolean
description: Whether product is published and available
example: true
created_at:
type: string
format: date-time
description: Product creation timestamp
updated_at:
type: string
format: date-time
nullable: true
description: Last update timestamp
archived_at:
type: string
format: date-time
nullable: true
description: Archive timestamp (if archived)
published_at:
type: string
format: date-time
description: When the product was published
unit_dim:
type: string
description: Unit dimension label
PriceEmbeddedProduct:
type: object
required:
- id
- type
- name
- active
- created_at
properties:
id:
type: string
description: Unique product identifier with prod_ prefix
example: "prod_abc123xyz"
about:
type: string
description: Full product description
example: "Starter plan for solo businesses"
active:
type: boolean
description: Whether product is published and available
example: true
archived_at:
type: string
format: date-time
nullable: true
description: Archive timestamp (if archived)
example: null
attributes:
type: array
nullable: true
description: Product attributes
items:
type: object
required:
- name
- value
properties:
name:
type: string
description: Attribute name
example: "tier"
value:
type: string
description: Attribute value
example: "starter"
category:
type: string
description: Product category
example: "software"
created_at:
type: string
format: date-time
description: Product creation timestamp
example: "2024-01-15T10:30:00Z"
custom_data:
$ref: '#/components/schemas/CustomData'
description:
type: string
description: Short description
example: "Standard monthly subscription"
dimensions:
description: Product dimensions and size metadata
$ref: '#/components/schemas/ProductDimensions'
media:
description: Product media assets
$ref: '#/components/schemas/ProductMedia'
name:
type: string
description: Product name
example: "Starter plan"
published_at:
type: string
format: date-time
nullable: true
description: When the product was published
example: "2024-01-15T10:35:00Z"
reference:
type: string
description: External reference or SKU
example: "plan-starter-monthly"
shipment:
description: Shipment and fulfillment details
$ref: '#/components/schemas/ProductShipment'
tax_code:
type: string
description: Tax classification code
example: "txcd_software"
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type
example: "digital"
unit_dim:
type: string
description: Unit dimension label
example: "license"
updated_at:
type: string
format: date-time
nullable: true
description: Last update timestamp
example: null
PricePageRequest:
type: object
properties:
page_number:
type: integer
minimum: 0
maximum: 10
description: Page index to fetch. Omit it or send 0 to request page 1; otherwise use 1 through 10.
default: 1
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of prices per page (1-256)
default: 256
product_id:
type: string
description: Optional product ID to scope the page to a single product
example: "prod_abc123"
PricePageResponse:
type: object
properties:
page:
type: object
properties:
number:
type: integer
description: The page number returned
size:
type: integer
description: The number of prices in this page
prices:
type: array
items:
$ref: '#/components/schemas/PricePageItem'
error:
$ref: '#/components/schemas/Error'
PricePageItem:
$ref: '#/components/schemas/CatalogPrice'
PriceActionRequest:
type: object
required:
- price_id
properties:
price_id:
type: string
description: Price ID to perform the action on
example: "pr_xyz789"
PriceResponse:
type: object
properties:
price:
$ref: '#/components/schemas/CatalogPrice'
error:
$ref: '#/components/schemas/Error'
CatalogPriceParams:
type: object
oneOf:
- title: Fixed amount
required: [type, fixed_amount]
properties:
type:
enum: [fixed_amount]
not:
anyOf:
- required: [amount]
- required: [customer_selected_amount]
- title: Customer-selected amount
required: [type, customer_selected_amount, product_id]
properties:
type:
enum: [customer_selected_amount]
not:
anyOf:
- required: [amount]
- required: [fixed_amount]
properties:
product_id:
type: string
description: Product ID to associate this price with. Optional for fixed prices, required for customer_selected_amount prices, and immutable once set.
example: "prod_abc123"
label:
type: string
description: Short label for this price (max 100 characters)
example: "Standard pricing"
about:
type: string
description: Longer description of this price (max 500 characters)
example: "Standard pricing for individual customers"
type:
type: string
enum: [fixed_amount, customer_selected_amount]
description: Price definition discriminator.
fixed_amount:
description: Required when type is fixed_amount.
$ref: '#/components/schemas/AmountParams'
customer_selected_amount:
description: Required when type is customer_selected_amount. Available only to Commerce internal services and Upper private beta organizations and applications.
$ref: '#/components/schemas/CustomerSelectedAmountParams'
CatalogPrice:
type: object
required:
- id
- active
- type
- created_at
oneOf:
- title: Fixed amount
required: [nominal, fixed_amount]
properties:
type:
enum: [fixed_amount]
not:
required: [customer_selected_amount]
- title: Customer-selected amount
required: [customer_selected_amount]
anyOf:
- required: [product_id]
- required: [product]
properties:
type:
enum: [customer_selected_amount]
not:
anyOf:
- required: [nominal]
- required: [fixed_amount]
properties:
id:
type: string
description: Unique price identifier with pr_ prefix
example: "pr_xyz789"
label:
type: string
nullable: true
description: Short label for this price
example: "Standard pricing"
about:
type: string
nullable: true
description: Longer description of this price
example: "Standard pricing for individual customers"
active:
type: boolean
description: Whether this price is active and usable in new flows
example: true
type:
type: string
enum: [fixed_amount, customer_selected_amount]
description: Price definition discriminator
nominal:
deprecated: true
description: Legacy fixed price amount. Present only for fixed_amount prices.
$ref: '#/components/schemas/Amount'
fixed_amount:
description: Fixed price amount. Present only for fixed_amount prices.
$ref: '#/components/schemas/Amount'
customer_selected_amount:
description: Customer-selected amount configuration. Present only for customer_selected_amount prices.
$ref: '#/components/schemas/CustomerSelectedAmount'
product_id:
type: string
description: Product ID when the operation returns the relationship by reference
example: "prod_abc123"
product:
$ref: '#/components/schemas/PriceEmbeddedProduct'
nullable: true
description: Embedded product details, if this price belongs to a product
created_at:
type: string
format: date-time
description: Price creation timestamp
example: "2024-01-15T10:30:00Z"
updated_at:
type: string
format: date-time
nullable: true
description: Last update timestamp
example: "2024-01-20T14:45:00Z"
archived_at:
type: string
format: date-time
nullable: true
description: Archive timestamp (if archived)
example: null
SuggestedAmountParams:
type: object
required: [id, value]
properties:
id:
type: string
maxLength: 100
description: Stable merchant-defined identifier for this suggestion
example: "supporter"
value:
type: integer
minimum: 1
description: Suggested amount in the currency's smallest unit
example: 50000
recommended:
type: boolean
default: false
description: Whether this is the single recommended suggestion
SuggestedAmount:
type: object
required: [id, value]
properties:
id:
type: string
description: Stable merchant-defined identifier for this suggestion
value:
type: integer
description: Suggested amount in the currency's smallest unit
recommended:
type: boolean
description: Whether this is the recommended suggestion
CustomerSelectedAmountParams:
type: object
required: [currency, minimum]
properties:
currency:
description: Currency accepted for customer-selected amounts
$ref: '#/components/schemas/Currency'
minimum:
type: integer
minimum: 1
description: Minimum selectable amount in the currency's smallest unit
example: 10000
maximum:
type: integer
minimum: 1
description: Optional maximum selectable amount; it must be at least minimum
example: 500000
suggested_amounts:
type: array
description: Convenient choices, not an allow-list. IDs and values must be unique and at most one can be recommended.
items:
$ref: '#/components/schemas/SuggestedAmountParams'
CustomerSelectedAmount:
type: object
required: [currency, minimum]
properties:
currency:
description: Currency accepted for customer-selected amounts
$ref: '#/components/schemas/Currency'
minimum:
type: integer
description: Minimum selectable amount in the currency's smallest unit
maximum:
type: integer
description: Optional maximum selectable amount
suggested_amounts:
type: array
description: Convenient choices, not an allow-list
items:
$ref: '#/components/schemas/SuggestedAmount'
PageFinancialAccountsRequest:
type: object
required:
- page_number
properties:
page_number:
type: integer
minimum: 1
maximum: 10
description: Page number to retrieve (1-indexed)
example: 1
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of accounts per page (defaults to 256)
example: 50
PageFinancialAccountsResponse:
type: object
properties:
page:
type: object
properties:
number:
type: integer
description: Current page number
example: 1
size:
type: integer
description: Number of accounts in this page
example: 50
accounts:
type: array
description: Array of financial account objects
items:
type: object
properties:
id:
type: string
description: Financial account identifier
example: "fa_abc123"
type:
type: string
enum: [wallet, bank_account, dosh_account]
description: Type of financial account
example: "wallet"
currency:
type: string
description: Three-letter ISO currency code
example: "GHS"
label:
type: string
description: Human-readable label
example: "Primary Payout Account"
description:
type: string
description: Optional description
reference:
type: string
description: External reference ID
created_at:
type: string
format: date-time
description: Account creation timestamp
archived_at:
type: string
format: date-time
description: Archive timestamp (if archived)
custom_data:
$ref: '#/components/schemas/CustomData'
error:
$ref: '#/components/schemas/Error'
OrderLineItem:
oneOf:
- $ref: '#/components/schemas/OrderProductLineItem'
- $ref: '#/components/schemas/OrderFeeLineItem'
- $ref: '#/components/schemas/OrderShippingLineItem'
- $ref: '#/components/schemas/OrderDiscountLineItem'
discriminator:
propertyName: type
mapping:
product: '#/components/schemas/OrderProductLineItem'
fee: '#/components/schemas/OrderFeeLineItem'
shipping: '#/components/schemas/OrderShippingLineItem'
discount: '#/components/schemas/OrderDiscountLineItem'
OrderProductLineItem:
type: object
required: [type, product]
properties:
type:
type: string
enum: [product]
product:
type: object
required: [id, name, price, quantity]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
example: "oli_7QYpB8c3V9kL2nM4"
product_id:
type: string
description: Source catalog product ID when this line snapshots a catalog product.
price_id:
type: string
description: Source catalog price ID when this line snapshots a saved price.
reference:
type: string
about:
type: string
custom_data:
$ref: '#/components/schemas/CustomData'
tax_code:
type: string
name:
type: string
category:
type: string
type:
type: string
price:
$ref: '#/components/schemas/Price'
quantity:
type: integer
OrderFeeLineItem:
type: object
required: [type, fee]
properties:
type:
type: string
enum: [fee]
fee:
type: object
required: [id, amount, label]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
description:
type: string
tax_code:
type: string
amount:
$ref: '#/components/schemas/Amount'
label:
type: string
OrderShippingLineItem:
type: object
required: [type, shipping]
properties:
type:
type: string
enum: [shipping]
shipping:
type: object
required: [id, fee]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
tax_code:
type: string
label:
type: string
fee:
$ref: '#/components/schemas/Amount'
OrderDiscountLineItem:
type: object
additionalProperties: false
required: [type, discount]
properties:
type:
type: string
enum: [discount]
discount:
$ref: '#/components/schemas/OrderDiscount'
OrderDiscount:
type: object
additionalProperties: false
LineItem:
oneOf:
- $ref: '#/components/schemas/ProductLineItem'
- $ref: '#/components/schemas/FeeLineItem'
- $ref: '#/components/schemas/ShippingLineItem'
discriminator:
propertyName: type
mapping:
product: '#/components/schemas/ProductLineItem'
fee: '#/components/schemas/FeeLineItem'
shipping: '#/components/schemas/ShippingLineItem'
ProductLineItem:
type: object
required:
- type
- product
properties:
type:
type: string
enum: [product]
description: Line item type discriminator
product:
$ref: '#/components/schemas/ProductDetails'
FeeLineItem:
type: object
required:
- type
- fee
properties:
type:
type: string
enum: [fee]
description: Line item type discriminator
fee:
$ref: '#/components/schemas/FeeDetails'
ShippingLineItem:
type: object
required:
- type
- shipping
properties:
type:
type: string
enum: [shipping]
description: Line item type discriminator
shipping:
$ref: '#/components/schemas/ShippingDetails'
ProductDetails:
oneOf:
- $ref: '#/components/schemas/InlineProductDetails'
- $ref: '#/components/schemas/CatalogProductWithPriceData'
- $ref: '#/components/schemas/CatalogProductWithPriceReference'
- $ref: '#/components/schemas/CatalogProductWithCustomerSelectedPrice'
description: |
Provide either inline product data or a `product_id` reference to an existing catalog
product. Catalog-backed product line items can use an explicit `price` or an existing
`price_id`, or a validated `customer_selected_price`. Inttegro never falls back to a
product's default unit price during order creation.
InlineProductDetails:
type: object
required:
- name
- price
- quantity
- type
properties:
about:
type: string
description: Long-form description or marketing copy
custom_data:
$ref: '#/components/schemas/CustomData'
name:
type: string
description: Product name shown to the customer
example: "Premium Widget"
price:
$ref: '#/components/schemas/PriceParams'
quantity:
type: integer
minimum: 1
description: How many units the customer is purchasing
example: 1
reference:
type: string
description: Your SKU or internal product reference
tax_code:
type: string
description: Tax classification code
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type—affects shipping requirements
CatalogProductWithPriceData:
type: object
required:
- price
- product_id
- quantity
properties:
price:
$ref: '#/components/schemas/PriceParams'
product_id:
type: string
description: Existing catalog product ID to snapshot onto the order line item
example: "prod_abc123xyz"
quantity:
type: integer
minimum: 1
description: How many units of the catalog product the customer is purchasing
example: 1
CatalogProductWithPriceReference:
type: object
required:
- price_id
- product_id
- quantity
properties:
price_id:
type: string
description: Existing product price to snapshot onto the order line item. It must belong to the same application and product.
example: "pr_xyz789"
product_id:
type: string
description: Existing catalog product ID to snapshot onto the order line item
example: "prod_abc123xyz"
quantity:
type: integer
minimum: 1
description: How many units of the catalog product the customer is purchasing
example: 1
CustomerSelectedPriceInput:
type: object
description: Available only to Commerce internal services and Upper private beta organizations and applications.
required: [price_id, selected_amount]
properties:
price_id:
type: string
description: Existing customer_selected_amount price belonging to the catalog product
example: "pr_donation"
selected_amount:
$ref: '#/components/schemas/AmountParams'
description: Concrete unit amount selected for this order; it must satisfy the referenced price's currency and range
CatalogProductWithCustomerSelectedPrice:
type: object
required:
- customer_selected_price
- product_id
- quantity
properties:
customer_selected_price:
$ref: '#/components/schemas/CustomerSelectedPriceInput'
product_id:
type: string
description: Existing catalog product ID to snapshot onto the order line item
example: "prod_devcongress_donation"
quantity:
type: integer
minimum: 1
description: How many units of the catalog product the customer is purchasing
example: 1
FeeDetails:
type: object
required:
- amount
properties:
id:
type: string
description: Fee identifier
label:
type: string
description: Customer-facing label for this fee
tax_code:
type: string
description: The tax classification code for the shipping fee
description:
type: string
description: Customer-facing description for this fee
custom_data:
$ref: '#/components/schemas/CustomData'
amount:
$ref: '#/components/schemas/AmountParams'
ShippingDetails:
type: object
required:
- fee
properties:
id:
type: string
description: Unique ID for this shipping charge
tax_code:
type: string
description: The tax classification code for the shipping fee
custom_data:
$ref: '#/components/schemas/CustomData'
fee:
$ref: '#/components/schemas/AmountParams'
Currency:
type: string
description: A currency code recognized by the Inttegro API. Individual operations can support a subset of these currencies.
enum: [ghs, usd, gbp, eur, cny]
example: ghs
AmountParams:
type: object
required:
- currency
- value
properties:
currency:
$ref: '#/components/schemas/Currency'
value:
type: integer
description: Amount in smallest currency unit (e.g., pesewas for GHS)
example: 20000
minimum: 0
Amount:
type: object
required:
- currency
- value
properties:
currency:
$ref: '#/components/schemas/Currency'
value:
type: integer
description: Amount in the currency's smallest unit.
example: 20000
PriceParams:
description: An inline price supplied in a request.
allOf:
- $ref: '#/components/schemas/AmountParams'
- type: object
properties:
value:
type: integer
minimum: 1
description: Price in the currency's smallest unit.
example: 20000
Price:
description: An inline price returned by the API.
allOf:
- $ref: '#/components/schemas/Amount'
BillingDetails:
type: object
required:
- name
- email_address
- phone_number
properties:
name:
type: string
description: Billing contact name
email_address:
type: string
format: email
description: Billing email address
phone_number:
type: string
description: Billing phone number
address:
$ref: '#/components/schemas/Address'
Shipping:
type: object
required:
- address
properties:
address:
$ref: '#/components/schemas/Address'
Address:
type: object
required:
- name
- phone_number
- line1
- town
- country
properties:
name:
type: string
description: Recipient name
example: "Customer Name"
phone_number:
type: string
description: Contact phone number
example: "+233242058841"
line1:
type: string
description: Street address line 1
example: "23 Adenta High Street"
line2:
type: string
description: Street address line 2 (optional)
example: "Behind Pantang"
town:
type: string
description: City or town
example: "Accra"
region:
type: string
description: State, province, or region
example: "Greater Accra"
district:
type: string
description: District or area
example: "Adenta"
country:
type: string
description: Country name
example: "Ghana"
post_code:
type: string
description: Postal/ZIP code
example: "GHA-123-9822"
CreateMessageTemplateRequest:
oneOf:
- $ref: '#/components/schemas/CreateSMSMessageTemplateRequest'
- $ref: '#/components/schemas/CreateEmailMessageTemplateRequest'
discriminator:
propertyName: channel
description: Create request for one reusable SMS or email message template.
CreateSMSMessageTemplateRequest:
type: object
required: [channel, name, purpose, sms]
additionalProperties: false
properties:
about:
type: string
channel:
type: string
enum: [sms]
locale:
type: string
default: en
name:
type: string
purpose:
type: string
sms:
$ref: '#/components/schemas/MessageTemplateSMSContent'
variables:
type: array
items:
$ref: '#/components/schemas/MessageTemplateVariableInput'
CreateEmailMessageTemplateRequest:
type: object
required: [channel, email, name, purpose]
additionalProperties: false
properties:
about:
type: string
attachments:
$ref: '#/components/schemas/MessageTemplateAttachmentIDs'
channel:
type: string
enum: [email]
email:
$ref: '#/components/schemas/MessageTemplateEmailContent'
locale:
type: string
default: en
name:
type: string
purpose:
type: string
variables:
type: array
items:
$ref: '#/components/schemas/MessageTemplateVariableInput'
MessageTemplateCreateFields:
type: object
required:
- name
- channel
- purpose
properties:
name:
type: string
description: Human-readable template name.
example: "Receipt email"
about:
type: string
description: Optional description of when this template should be used.
example: "Sent after a successful payment."
channel:
type: string
enum: [sms, email]
description: Delivery channel this template renders for.
purpose:
type: string
description: Caller-defined purpose for filtering and analytics.
example: "receipt"
locale:
type: string
description: Template locale. Defaults to `en` when omitted.
example: "en"
variables:
type: array
description: Variables accepted by this template.
items:
$ref: '#/components/schemas/MessageTemplateVariableInput'
UpdateMessageTemplateRequest:
type: object
required:
- id
additionalProperties: false
not:
required:
- sms
- email
properties:
id:
type: string
description: API-generated message template id.
example: "mtpl_receipt"
name:
type: string
description: Human-readable template name.
example: "Receipt email"
about:
type: string
description: Optional description of when this template should be used.
example: "Sent after a successful payment."
channel:
type: string
enum: [sms, email]
description: Existing template channel. Channels cannot be changed.
purpose:
type: string
description: Caller-defined purpose for filtering and analytics.
example: "receipt"
locale:
type: string
example: "en"
variables:
type: array
items:
$ref: '#/components/schemas/MessageTemplateVariableInput'
sms:
$ref: '#/components/schemas/MessageTemplateSMSContent'
email:
$ref: '#/components/schemas/MessageTemplateEmailContent'
attachments:
$ref: '#/components/schemas/MessageTemplateAttachmentIDs'
MessageTemplateIDRequest:
type: object
required:
- id
properties:
id:
type: string
description: API-generated message template id.
example: "mtpl_receipt"
PageMessageTemplatesRequest:
type: object
properties:
page:
type: integer
minimum: 1
default: 1
size:
type: integer
minimum: 1
default: 25
status:
type: string
enum: [draft, published, archived]
channel:
type: string
enum: [sms, email]
purpose:
type: string
example: "receipt"
locale:
type: string
example: "en"
RenderMessageTemplatePreviewRequest:
type: object
required:
- message_template
properties:
message_template:
$ref: '#/components/schemas/MessageTemplateReference'
MessageTemplateReference:
type: object
required:
- template_id
properties:
template_id:
type: string
description: API-generated message template id.
example: "mtpl_receipt"
variables:
$ref: '#/components/schemas/MessageTemplateVariables'
MessageTemplateVariables:
allOf:
- $ref: '#/components/schemas/JSONData'
description: Variable values used when rendering a template.
example:
customer_name: "Akua"
receipt_url: "https://pay.inttegro.com/receipts/123"
MessageTemplateAttachmentIDs:
type: array
description: Stored file IDs returned by previews. Chime send, schedule, and broadcast currently reject stored-template attachments.
maxItems: 25
items:
type: string
pattern: "^file_[A-Za-z0-9]+$"
example:
- "file_invoicePdf"
MessageTemplateVariableInput:
type: object
required:
- name
- type
additionalProperties: false
properties:
name:
type: string
pattern: "^[a-z][a-z0-9_]{0,63}$"
example: "customer_name"
type:
type: string
enum: [string, number, integer, boolean, url, email, phone, date, datetime, array]
required:
type: boolean
'default':
description: Default value used when this variable is omitted.
about:
type: string
description: Optional description of the variable.
items:
type: array
description: Field schema for array item objects. Nested arrays are not supported.
items:
$ref: '#/components/schemas/MessageTemplateVariableItemInput'
MessageTemplateVariableItemInput:
type: object
required: [name, type]
additionalProperties: false
properties:
about:
type: string
default: {}
name:
type: string
pattern: "^[a-z][a-z0-9_]{0,63}$"
required:
type: boolean
type:
type: string
enum: [string, number, integer, boolean, url, email, phone, date, datetime]
MessageTemplateVariable:
type: object
required: [name, required, type]
properties:
about:
type: string
default: {}
items:
type: array
items:
$ref: '#/components/schemas/MessageTemplateVariableItem'
name:
type: string
required:
type: boolean
type:
type: string
enum: [string, number, integer, boolean, url, email, phone, date, datetime, array]
MessageTemplateVariableItem:
type: object
required: [name, required, type]
properties:
about:
type: string
default: {}
name:
type: string
required:
type: boolean
type:
type: string
enum: [string, number, integer, boolean, url, email, phone, date, datetime]
MessageTemplateSMSContent:
type: object
required:
- message_template
properties:
message_template:
type: string
description: SMS body template.
example: "Your code is {{code}}."
MessageTemplateEmailContent:
type: object
required:
- subject
- html
properties:
subject:
type: string
description: Email subject template.
example: "Your receipt"
html:
type: string
description: HTML email body template.
example: "Thanks {{customer_name}}.
"
from:
$ref: '#/components/schemas/MessageTemplateMailbox'
reply_to:
$ref: '#/components/schemas/MessageTemplateMailbox'
headers:
$ref: '#/components/schemas/MessageHeaders'
MessageTemplateMailbox:
type: object
required:
- address
properties:
address:
type: string
description: Literal or templated mailbox address, such as `{{recipient_email}}`.
example: "{{recipient_email}}"
name:
type: string
example: "Acme"
MessageTemplateSafetyResult:
type: object
description: Result of the email safety scan.
required: [content_hash, normalized_text, scanner, status]
properties:
content_hash:
type: string
links:
type: array
items:
$ref: '#/components/schemas/MessageTemplateScannedLink'
normalized_text:
type: string
quarantine_notes:
type: string
reason_codes:
type: array
items:
type: string
sanitized_html:
type: string
scanner:
type: string
status:
type: string
enum: [allowed, rejected, quarantined]
MessageTemplateScannedLink:
type: object
required: [raw, scheme, status]
properties:
host:
type: string
raw:
type: string
reason:
type: string
scheme:
type: string
status:
type: string
MessageTemplate:
type: object
required:
- id
- name
- channel
- purpose
- locale
- status
- version
- draft_version
- has_unpublished_changes
- created_at
- updated_at
properties:
id:
type: string
description: API-generated unique template id.
example: "mtpl_receipt"
name:
type: string
example: "Receipt email"
about:
type: string
example: "Sent after successful payment."
channel:
type: string
enum: [sms, email]
purpose:
type: string
example: "receipt"
locale:
type: string
example: "en"
status:
type: string
enum: [draft, published, archived]
version:
type: integer
example: 2
published_version:
type: integer
example: 1
draft_version:
type: integer
example: 2
has_unpublished_changes:
type: boolean
variables:
type: array
items:
$ref: '#/components/schemas/MessageTemplateVariable'
sms:
$ref: '#/components/schemas/MessageTemplateSMSContent'
email:
$ref: '#/components/schemas/MessageTemplateEmailContent'
attachments:
$ref: '#/components/schemas/MessageTemplateAttachmentIDs'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
published_at:
type: string
format: date-time
archived_at:
type: string
format: date-time
MessageTemplateEnvelope:
type: object
required: [message_template]
properties:
message_template:
$ref: '#/components/schemas/MessageTemplate'
MessageTemplatesPageEnvelope:
type: object
required: [page]
properties:
page:
$ref: '#/components/schemas/MessageTemplatesPage'
MessageTemplatesPage:
type: object
required:
- number
- size
- message_templates
properties:
number:
type: integer
example: 1
size:
type: integer
description: Number of templates returned in this page after filters are applied.
example: 25
message_templates:
type: array
items:
$ref: '#/components/schemas/MessageTemplate'
RenderMessageTemplatePreviewResponse:
type: object
required: [message_template, rendered]
properties:
message_template:
$ref: '#/components/schemas/MessageTemplate'
rendered:
$ref: '#/components/schemas/RenderedMessageTemplate'
RenderedMessageTemplate:
type: object
required:
- channel
properties:
channel:
type: string
enum: [sms, email]
attachments:
$ref: '#/components/schemas/MessageTemplateAttachmentIDs'
sms:
$ref: '#/components/schemas/RenderedSMSMessageTemplate'
email:
$ref: '#/components/schemas/RenderedEmailMessageTemplate'
RenderedSMSMessageTemplate:
type: object
required:
- full_message
properties:
full_message:
type: string
maxLength: 120
example: "Your code is 123456."
RenderedEmailMessageTemplate:
type: object
required:
- subject
- text
properties:
subject:
type: string
example: "Your receipt"
text:
type: string
example: "Thanks Akua."
html:
type: string
example: "Thanks Akua.
"
from:
$ref: '#/components/schemas/MessageTemplateMailbox'
reply_to:
$ref: '#/components/schemas/MessageTemplateMailbox'
headers:
$ref: '#/components/schemas/MessageHeaders'
safety:
$ref: '#/components/schemas/MessageTemplateSafetyResult'
OrderDocumentDeliveryRequest:
type: object
additionalProperties: false
required:
- order_id
properties:
order_id:
type: string
description: Order whose hosted invoice or receipt link should be delivered.
example: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
OrderDocumentDeliveryResponse:
type: object
description: Response returned by deliberate order document delivery endpoints.
properties:
delivery:
$ref: '#/components/schemas/OrderDocumentDelivery'
error:
$ref: '#/components/schemas/Error'
order:
$ref: '#/components/schemas/Order'
OrderDocumentDelivery:
type: object
description: Delivery result for one hosted order document link.
properties:
deliveries:
type: array
description: Chime messages that were accepted for delivery.
items:
$ref: '#/components/schemas/OrderDocumentDeliveryAttempt'
document_kind:
type: string
enum: [invoice, receipt]
description: Hosted document that was delivered.
example: "invoice"
document_url:
type: string
format: uri
description: Hosted invoice or receipt URL sent to the customer. Receipt URLs use the hosted receipt path, not the invoice PDF path.
example: "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
failed_channels:
type: array
description: Channels that failed to send.
items:
type: string
enum: [email, sms]
example: ["email"]
failures:
type: array
description: Per-channel delivery failures.
items:
$ref: '#/components/schemas/OrderDocumentDeliveryFailure'
sent_channels:
type: array
description: Channels accepted by Chime.
items:
type: string
enum: [email, sms]
example: ["sms"]
OrderDocumentDeliveryAttempt:
type: object
description: Chime delivery accepted for one channel.
properties:
accepted_at:
type: string
format: date-time
description: Authoritative time at which Chime accepted this channel delivery.
channel:
type: string
enum: [email, sms]
description: Delivery channel.
example: "sms"
chime_id:
type: string
description: Chime ID created for this delivery.
example: "chm_7QYpB8c3V9kL2nM4"
OrderDocumentDeliveryFailure:
type: object
description: Chime delivery failure for one channel.
properties:
channel:
type: string
enum: [email, sms]
description: Delivery channel.
example: "email"
error:
type: string
description: Provider or Chime error for this channel.
example: "chime api returned status=503"
OrderDocumentDeliverySummary:
type: object
description: Bounded aggregate of Chime-accepted sends for one generated order document.
required: [channels, latest_sent_at, total_count]
properties:
channels:
type: object
description: Accepted send totals grouped by delivery channel. Channels with no accepted sends are omitted.
properties:
email:
$ref: '#/components/schemas/OrderDocumentDeliveryChannelSummary'
sms:
$ref: '#/components/schemas/OrderDocumentDeliveryChannelSummary'
latest_sent_at:
type: string
format: date-time
description: Latest authoritative Chime acceptance time across all channels.
total_count:
type: integer
format: int64
minimum: 1
description: Total channel deliveries accepted for this document.
OrderDocumentDeliveryChannelSummary:
type: object
description: Bounded aggregate of Chime-accepted sends through one channel.
required: [count, latest_sent_at]
properties:
count:
type: integer
format: int64
minimum: 1
description: Number of deliveries accepted through this channel.
latest_sent_at:
type: string
format: date-time
description: Latest authoritative Chime acceptance time for this channel.
PaymentMethodPageRequest:
type: object
properties:
customer_id:
type: string
description: Optional customer ID to scope the page to a single customer
example: "cu_a1b2c3d4e5"
page_number:
type: integer
minimum: 0
maximum: 10
description: Page index to fetch. `0` is accepted and normalized to page 1; returned pages are numbered 1-10.
default: 1
page_size:
type: integer
minimum: 1
maximum: 256
description: Number of payment methods per page (1-256)
default: 256
PaymentMethodPageResponse:
type: object
required:
- page
properties:
page:
type: object
required:
- number
- payment_methods
- size
properties:
number:
type: integer
description: The page number returned
payment_methods:
type: array
items:
$ref: '#/components/schemas/PaymentMethodObject'
size:
type: integer
description: The number of payment methods in this page
MobileMoney:
type: object
required:
- network
- account_number
properties:
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
description: Mobile money service provider
example: "mtn"
account_number:
type: string
description: Mobile money account number
example: "0544998605"
OrderCreateResponse:
type: object
description: Response returned when an order is successfully created
required:
- order
properties:
order:
type: object
required:
- id
- number
- status
- customer
- line_item_group
- initiated_at
- sealed_at
properties:
id:
type: string
description: Unique identifier for the created order
example: "cHPzmk9aL1iQPjfYICpKh73mMzlasKezSCCl27J0"
number:
type: string
description: Human-readable order number
example: "ORDER-NUMBER"
receipt_number:
type: string
description: Merchant-provided receipt number, when set
example: "RCPT-NUMBER"
invoice_settings:
$ref: '#/components/schemas/InvoiceSettings'
status:
type: string
enum: [preparing, requires_payment, completed, canceled, expired]
description: Current status of the order
example: "requires_payment"
customer:
type: object
description: Customer who owns the order
required:
- id
- name
- email_address
- phone_number
- created_at
properties:
id:
type: string
description: Unique identifier for the customer
example: "Rc3pbHKtmoYpWR3R19o9eYio9YUXEAEY3fwaiuZb"
name:
type: string
description: Customer name
example: "Gloria Kesewaa"
email_address:
type: string
format: email
description: Customer email
example: "gloria@kesewaa.co"
phone_number:
type: string
description: Customer's phone number in full international format
example: "+233544998605"
billing_address:
type: object
description: Customer billing address
properties:
name:
type: string
description: Recipient name
example: "Anita Segnom"
phone_number:
type: string
description: Recipient phone number
example: "+233559714200"
line1:
type: string
description: Primary street address line
example: "15 Main Street"
line2:
type: string
description: Secondary street address line
example: "Apartment 3B"
city:
type: string
description: City or town
example: "Accra"
region:
type: string
description: Region or state
example: "Greater Accra"
post_code:
type: string
description: Postal code
example: "GA-123-4567"
country:
type: string
description: ISO 3166-1 alpha-2 country code
example: "GH"
shipping_address:
type: object
description: Customer shipping address
properties:
name:
type: string
description: Recipient name
example: "Anita Segnom"
phone_number:
type: string
description: Recipient phone number
example: "+233559714200"
line1:
type: string
description: Primary street address line
example: "15 Main Street"
line2:
type: string
description: Secondary street address line
example: "Apartment 3B"
city:
type: string
description: City or town
example: "Accra"
region:
type: string
description: Region or state
example: "Greater Accra"
post_code:
type: string
description: Postal code
example: "GA-123-4567"
country:
type: string
description: ISO 3166-1 alpha-2 country code
example: "GH"
created_at:
type: string
format: date-time
description: When the customer was created
example: "2025-10-24T21:08:11.494242829Z"
line_item_group:
type: object
description: Group of line items in the order
required:
- line_items
- total
properties:
line_items:
type: array
description: Items included in the order. Product line items may use inline product data, `product_id` with explicit `price`, or `product_id` with `price_id`.
items:
type: object
required:
- type
properties:
type:
type: string
enum: [product, fee, shipping]
description: Type of line item
product:
type: object
description: Product details (when type is 'product')
required:
- id
- name
- type
- quantity
properties:
id:
type: string
description: Unique identifier for the product order line item
example: "oli_VyxdsD4iP6K3H2z76eBdP9NSqmJLeDbxqnsl1Zhr"
name:
type: string
description: Product name
example: "Bespoke Ceramic Cheese"
about:
type: string
description: Product description
type:
type: string
enum: [physical, digital, service, voucher, custom, cause]
description: Product type
example: "digital"
price:
$ref: '#/components/schemas/Price'
quantity:
type: integer
minimum: 1
description: Quantity ordered
example: 1
tax_code:
type: string
description: Tax classification code
example: "green"
custom_data:
$ref: '#/components/schemas/CustomData'
fee:
type: object
description: Fee details (when type is 'fee')
required:
- id
- amount
properties:
id:
type: string
description: Unique identifier for the fee order line item
example: "oli_l709U3Hb8Sjzt81iuR4WrFJQnmZEFyzSAXLCLS05"
label:
type: string
description: Fee label/name
example: "Service/Technology Fee"
description:
type: string
description: Fee description
example: "A small charge to support technology development and use"
amount:
$ref: '#/components/schemas/Amount'
shipping:
type: object
description: Shipping details (when type is 'shipping')
required:
- id
- fee
properties:
id:
type: string
description: Unique identifier for the shipping order line item
example: "oli_Nq4fIE5bW3yrpCMr2duOvzKKWCdpoXx5l0xH3qFy"
fee:
$ref: '#/components/schemas/Amount'
total:
$ref: '#/components/schemas/Amount'
payment:
type: object
description: Payment information if payment was initiated
nullable: true
required:
- id
- status
- amount
- payment_method
- initiated_at
properties:
id:
type: string
description: Unique identifier for the payment
example: "3deNYydEjIGCqK1tGlAPwJYSCsZnQ4XGFki9PZWC"
status:
type: string
enum: [requires_action, processing, succeeded, failed, cancelled]
description: Payment status
example: "requires_action"
statement_descriptor:
type: string
description: Optional statement descriptor shown on the customer's bank statement
example: "STATEMENT"
amount:
$ref: '#/components/schemas/Amount'
payment_method:
$ref: '#/components/schemas/PaymentMethodObject'
next_action:
$ref: '#/components/schemas/PaymentNextAction'
initiated_at:
type: string
format: date-time
description: When the payment was initiated
example: "2025-10-24T21:08:11.594061484Z"
balance_transaction:
type: object
description: |
Balance transaction details, if available. `type` is the semantic source, not
direction. Exactly one matching `payment_id` or `refund_id` is present.
nullable: true
required: [amount, created_at, id, order_id, type]
properties:
id:
type: string
description: Unique identifier for the balance transaction
example: "bt_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN"
payout_id:
type: string
description: Associated payout ID
example: "po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN"
nullable: true
payment_id:
type: string
description: Present when `type` is `payment`; omitted when `type` is `refund`.
example: "py_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn"
refund_id:
type: string
description: Present when `type` is `refund`; omitted when `type` is `payment`.
example: "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd"
order_id:
type: string
description: Order associated with the payment.
example: "or_0123456789abcdefghijklmnopqrstuvwxyzABCD"
created_at:
type: string
format: date-time
description: When the balance transaction was created
example: "2025-10-24T21:08:12.123456789Z"
paid_at:
type: string
format: date-time
description: When the balance transaction was paid out
example: "2025-10-25T21:08:12.123456789Z"
amount:
$ref: '#/components/schemas/Amount'
payout_configuration:
type: object
description: Payout configuration for this balance transaction
nullable: true
properties:
enable_fx:
type: boolean
enum: [false]
description: Compatibility flag. Cross-currency payout execution is not currently available.
example: false
destination:
type: object
description: Where the funds will be paid out
properties:
financial_account_id:
type: string
description: ID of the financial account receiving the payout
example: "fa_1234567890abcdef"
type:
type: string
enum: [payment, refund]
description: Semantic source or cause of this entry, not its direction.
shipping:
type: object
description: Shipping information for the order
nullable: true
initiated_at:
type: string
format: date-time
description: Timestamp when the order was initiated
example: "2025-10-24T21:08:11.494216067Z"
sealed_at:
type: string
format: date-time
description: Timestamp when the order was finalized (sealed)
example: "2025-10-24T21:08:11.660713878Z"
CheckoutOrderReferenceRequest:
type: object
additionalProperties: false
required:
- order_id
properties:
order_id:
type: string
minLength: 1
description: The finalized Order to inspect or pay.
example: "or_a1b2c3d4e5f6"
CheckoutLookupRequest:
oneOf:
- $ref: '#/components/schemas/CheckoutOrderReferenceRequest'
- type: object
additionalProperties: false
required:
- purchase_intent_id
properties:
purchase_intent_id:
type: string
minLength: 1
description: Purchase Intent whose customer-selected amount policy should be loaded.
example: "sale_a1b2c3d4e5f6"
CheckoutSelectAmountRequest:
oneOf:
- type: object
additionalProperties: false
required:
- purchase_intent_id
- selected_amount
properties:
purchase_intent_id:
type: string
minLength: 1
description: Purchase Intent used to create a new Checkout Order.
example: "sale_a1b2c3d4e5f6"
selected_amount:
$ref: '#/components/schemas/CheckoutSelectedAmount'
- type: object
additionalProperties: false
required:
- order_id
- selected_amount
properties:
order_id:
type: string
minLength: 1
description: Existing finalized Order whose amount should be changed before payment begins.
example: "or_a1b2c3d4e5f6"
selected_amount:
$ref: '#/components/schemas/CheckoutSelectedAmount'
CheckoutSelectedAmount:
type: object
additionalProperties: false
required:
- currency
- value
properties:
currency:
$ref: '#/components/schemas/Currency'
value:
type: integer
minimum: 1
description: Payer-selected amount in the currency's smallest unit.
example: 5000
CheckoutPaymentAddress:
type: object
additionalProperties: false
required:
- country
properties:
name:
type: string
phone_number:
type: string
line1:
type: string
line2:
type: string
city:
type: string
region:
type: string
post_code:
type: string
country:
type: string
description: ISO 3166-1 alpha-2 country code.
example: GH
CheckoutBillingDetails:
type: object
additionalProperties: false
required:
- name
- address
properties:
name:
type: string
description: Name of the payer associated with the new payment method.
phone_number:
type: string
description: Phone number associated with the new payment method.
address:
$ref: '#/components/schemas/CheckoutPaymentAddress'
CheckoutMobileMoneyData:
type: object
additionalProperties: false
required:
- network
- account_number
properties:
reference:
type: string
network:
type: string
enum: [mtn, vodafone, airtel, telecel]
account_number:
type: string
CheckoutPaymentMethodData:
type: object
additionalProperties: false
required:
- type
- mobile_money
properties:
type:
type: string
enum: [mobile_money]
mobile_money:
$ref: '#/components/schemas/CheckoutMobileMoneyData'
billing_details:
allOf:
- $ref: '#/components/schemas/CheckoutBillingDetails'
description: |
Billing details for this new payment method. They do not replace the
Order customer's identity or the Order's shipping address.
CheckoutPayRequest:
type: object
additionalProperties: false
required:
- order_id
not:
required: [payment_method_id, payment_method_data]
properties:
payment_method_id:
type: string
payment_method_data:
type: object
properties:
order_id:
type: string
minLength: 1
description: The finalized Order to pay.
example: "or_a1b2c3d4e5f6"
payment_method_id:
type: string
minLength: 1
description: |
A saved payment method owned by the Order's immutable customer. Mutually
exclusive with `payment_method_data`.
payment_method_data:
allOf:
- $ref: '#/components/schemas/CheckoutPaymentMethodData'
description: |
New payment method details supplied by the payer. Mutually exclusive with
`payment_method_id`. Shipping details are not accepted here because checkout
cannot change the Order's shipping address.
save_payment_method:
type: boolean
default: false
description: |
Save a newly supplied payment method to the Order's customer. When true,
`payment_method_data.billing_details` is required.
CheckoutConfirmPaymentRequest:
type: object
additionalProperties: false
required:
- order_id
- token
properties:
order_id:
type: string
minLength: 1
example: "or_a1b2c3d4e5f6"
payment_id:
type: string
description: Optional payment identifier when already known by the client.
confirmation_id:
type: string
description: Optional confirmation attempt identifier.
token:
type: string
minLength: 1
description: Payer confirmation token.
example: "123456"
CheckoutOrderResponse:
type: object
description: Checkout response. Error responses can include the latest Order snapshot when available.
properties:
order:
$ref: '#/components/schemas/CheckoutOrder'
error:
$ref: '#/components/schemas/Error'
CheckoutLookupResponse:
type: object
description: |
A Purchase Intent lookup returns `amount_selection`. An Order lookup returns
`order` and also returns `amount_selection` while that Order's amount can still be
changed.
properties:
order:
$ref: '#/components/schemas/CheckoutOrder'
amount_selection:
$ref: '#/components/schemas/CheckoutAmountSelection'
error:
$ref: '#/components/schemas/Error'
CheckoutAmountSelection:
type: object
additionalProperties: false
required:
- price_id
- product_id
- merchant_name
- product_name
- customer_selected_amount
oneOf:
- required: [purchase_intent_id]
- required: [order_id]
properties:
purchase_intent_id:
type: string
description: Purchase Intent reference present when selection creates an Order.
example: "sale_a1b2c3d4e5f6"
order_id:
type: string
description: Order reference present when selection changes an existing Order.
example: "or_a1b2c3d4e5f6"
price_id:
type: string
example: "price_123"
product_id:
type: string
example: "prod_123"
merchant_name:
type: string
example: "Kora Market"
product_name:
type: string
example: "Open contribution"
product_about:
type: string
expires_at:
type: string
format: date-time
customer_selected_amount:
$ref: '#/components/schemas/CustomerSelectedAmount'
CheckoutOrder:
type: object
description: |
Current checkout projection. Its existing fields are published unchanged for the
initial mobile SDK contract and may be narrowed in a future contract revision.
required:
- id
- initiated_at
- customer
- status
properties:
id:
type: string
example: "or_a1b2c3d4e5f6"
number:
type: string
receipt_number:
type: string
reference:
type: string
status:
type: string
enum: [preparing, requires_payment, completed, paid, canceled, expired, unknown]
initiated_at:
type: string
format: date-time
sealed_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
paid_at:
type: string
format: date-time
canceled_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
payment_due_at:
type: string
format: date-time
checkout_settings:
type: object
properties:
redirect_url:
type: string
format: uri
cancel_url:
type: string
format: uri
line_item_group:
type: object
properties:
line_items:
type: array
items:
$ref: '#/components/schemas/LineItem'
total:
$ref: '#/components/schemas/Amount'
customer:
type: object
properties:
id:
type: string
guest:
type: boolean
name:
type: string
email_address:
type: string
phone_number:
type: string
billing_address:
type: object
shipping_address:
type: object
created_from:
type: object
properties:
source:
type: string
resource_type:
type: string
resource_id:
type: string
payment:
type: object
properties:
id:
type: string
statement_descriptor:
type: string
payment_method_types:
type: array
items:
type: string
payment_method:
type: object
billing_details:
type: object
receipt:
$ref: '#/components/schemas/CheckoutInvoiceView'
latest_attempt:
type: object
amount:
$ref: '#/components/schemas/Amount'
next_action:
type: object
latest_error:
type: object
status:
type: string
initiated_at:
type: string
format: date-time
executed_at:
type: string
format: date-time
due_at:
type: string
format: date-time
canceled_at:
type: string
format: date-time
expired_at:
type: string
format: date-time
paid_at:
type: string
format: date-time
paid_offline:
type: boolean
failed_at:
type: string
format: date-time
invoice:
$ref: '#/components/schemas/CheckoutInvoiceView'
CheckoutInvoiceView:
type: object
required:
- id
- created_at
- format
properties:
delivery_summary:
$ref: '#/components/schemas/OrderDocumentDeliverySummary'
id:
type: string
application_id:
type: string
number:
type: string
status:
type: string
enum: [draft, requires_payment, overdue, paid, expired, canceled]
created_at:
type: string
format: date-time
due_at:
type: string
format: date-time
format:
type: object
properties:
web:
type: object
properties:
url:
type: string
format: uri
pdf:
type: object
properties:
url:
type: string
format: uri
beneficiary:
type: object
properties:
id:
type: string
legal_entity_type:
type: string
logo_url:
type: string
format: uri
alias:
type: string
name:
type: string
support_email:
type: string
support_phone:
type: string
website_url:
type: string
format: uri
accent_color:
type: string
invoice_support_line:
type: string
invoice_footer:
type: string
OrderAddress:
type: object
required:
- country
properties:
name:
type: string
phone_number:
type: string
line1:
type: string
line2:
type: string
city:
type: string
region:
type: string
post_code:
type: string
country:
type: string
OrderPaymentMethod:
type: object
required: [id, created_at, customer_id, type, verified]
properties:
id:
type: string
bank_account:
type: object
required: [type]
properties:
type:
type: string
ghana_bank_account:
type: object
required: [account_number]
properties:
account_number:
type: string
branch:
type: string
name:
type: string
sort_code:
type: string
swift_code:
type: string
card:
$ref: '#/components/schemas/PaymentMethodCard'
created_at:
type: string
format: date-time
customer_id:
type: string
mobile_money:
type: object
required: [network, account_number, last4]
properties:
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
account_number:
type: string
description: Masked number in the form `****1234`.
last4:
type: string
owner:
type: object
required: [name]
properties:
name:
type: string
address:
$ref: '#/components/schemas/OrderAddress'
type:
type: string
enum: [mobile_money, bank_account, card, motito]
verified:
type: boolean
verified_at:
type: string
format: date-time
OrderResponse:
type: object
required:
- order
properties:
order:
$ref: '#/components/schemas/Order'
Order:
type: object
description: Complete order record with line items, customer details, payment state, and fulfillment information
required:
- customer
- id
- initiated_at
- status
properties:
canceled_at:
type: string
format: date-time
description: When the order was canceled. Omitted otherwise.
checkout_settings:
type: object
description: Checkout and payment flow configuration for this order
properties:
redirect_url:
type: string
format: uri
description: URL to redirect the customer after payment completion
cancel_url:
type: string
format: uri
description: URL to redirect the customer after canceling checkout
completed_at:
type: string
format: date-time
description: When the order was completed. Omitted otherwise.
created_from:
type: object
description: Attribution for the public resource that created this order, when available.
properties:
source:
type: string
resource_type:
type: string
enum: [purchase_intent]
resource_id:
type: string
custom_data:
$ref: '#/components/schemas/CustomData'
customer:
type: object
required:
- guest
- id
- name
properties:
id:
type: string
guest:
type: boolean
name:
type: string
email_address:
type: string
format: email
phone_number:
type: string
billing_address:
$ref: '#/components/schemas/OrderAddress'
shipping_address:
$ref: '#/components/schemas/OrderAddress'
expires_at:
type: string
format: date-time
description: When the order expires. Omitted when no expiry is set.
id:
type: string
description: Unique identifier for this order
example: "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
initiated_at:
type: string
format: date-time
description: When order processing began
invoice:
type: object
required: [format]
properties:
delivery_summary:
$ref: '#/components/schemas/OrderDocumentDeliverySummary'
number:
type: string
format:
type: object
required: [web, pdf]
properties:
web:
$ref: '#/components/schemas/OrderDocumentFormat'
pdf:
$ref: '#/components/schemas/OrderDocumentFormat'
number:
type: string
description: Human-readable order number
example: "ORDER-12345"
receipt_number:
type: string
description: Merchant-provided receipt number, when set
example: "RCPT-12345"
refunds:
type: array
description: All refunds issued for this order, newest first. Omitted when no refunds exist.
items:
$ref: '#/components/schemas/Refund'
invoice_settings:
$ref: '#/components/schemas/InvoiceSettings'
status:
type: string
enum: [preparing, requires_payment, paid, completed, canceled, expired, unknown]
description: Current lifecycle state of the order
example: "completed"
sealed_at:
type: string
format: date-time
description: When the order was finalized and became immutable—ready for payment or fulfillment
example: "2025-09-14T16:24:41.312701813Z"
line_item_group:
type: object
description: Cart contents and totals
required:
- line_items
- total
properties:
line_items:
type: array
description: Array of products, fees, and shipping charges
items:
$ref: '#/components/schemas/OrderLineItem'
total:
$ref: '#/components/schemas/Amount'
payment:
type: object
description: Payment intent tied to this order
required:
- amount
- id
- initiated_at
- statement_descriptor
- status
properties:
id:
type: string
description: Payment intent ID
example: "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl"
status:
type: string
enum: [initiated, requires_action, overdue, executed, paid, canceled, expired, failed, unknown]
description: Payment state
example: "paid"
statement_descriptor:
type: string
description: Optional statement descriptor shown on the customer's bank statement
example: "STATEMENT"
amount:
$ref: '#/components/schemas/Amount'
balance_transaction:
$ref: '#/components/schemas/BalanceTransaction'
payment_method:
$ref: '#/components/schemas/OrderPaymentMethod'
billing_details:
type: object
additionalProperties: false
properties:
owner:
type: object
additionalProperties: false
required: [name]
properties:
name:
type: string
address:
$ref: '#/components/schemas/OrderAddress'
receipt:
$ref: '#/components/schemas/OrderReceipt'
customer:
type: object
additionalProperties: false
required: [id, guest, name]
properties:
id:
type: string
guest:
type: boolean
name:
type: string
email_address:
type: string
format: email
phone_number:
type: string
billing_address:
$ref: '#/components/schemas/OrderAddress'
shipping_address:
$ref: '#/components/schemas/OrderAddress'
latest_attempt:
type: object
description: Most recent payment attempt details
required: [status, initiated_at]
properties:
payment_method_type:
type: string
example: "mobile_money"
payment_method_id:
type: string
example: "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6"
error:
type: object
additionalProperties: false
required: [message]
properties:
message:
type: string
reference:
type: string
description: External payment reference
example: "68c6ecbc3bf0a6548973b598"
status:
type: string
enum: [initiated, executed, succeeded, canceled, expired, failed, unknown]
example: "succeeded"
initiated_at:
type: string
format: date-time
succeeded_at:
type: string
format: date-time
next_action:
$ref: '#/components/schemas/PaymentNextAction'
latest_error:
type: object
additionalProperties: false
required: [message, docs_url, source, type, code]
properties:
message:
type: string
docs_url:
type: string
format: uri
source:
type: string
type:
type: string
code:
type: string
initiated_at:
type: string
format: date-time
description: When we kicked off the payment intent
executed_at:
type: string
format: date-time
description: When payment execution started
paid_at:
type: string
format: date-time
description: When payment completed successfully
canceled_at:
type: string
format: date-time
description: When payment was canceled
due_at:
type: string
format: date-time
description: When payment becomes overdue
expired_at:
type: string
format: date-time
description: When payment expired
failed_at:
type: string
format: date-time
description: When payment failed
paid_offline:
type: boolean
description: Whether payment was recorded as received outside Inttegro
payment_method_types:
type: array
items:
type: string
payout_configuration:
type: object
description: Payout configuration for this payment
nullable: true
required: [enable_fx, destination]
properties:
enable_fx:
type: boolean
enum: [false]
description: Compatibility flag. Cross-currency payout execution is not currently available.
example: false
destination:
type: object
description: Where the funds will be paid out
required: [financial_account_id]
properties:
financial_account_id:
type: string
description: ID of the financial account receiving the payout
example: "fa_1234567890abcdef"
paid_at:
type: string
format: date-time
description: When the order became paid
payment_due_at:
type: string
format: date-time
description: When the order payment becomes overdue
reference:
type: string
description: External order reference when present
OrderDocumentFormat:
type: object
required:
- url
properties:
url:
type: string
format: uri
OrderReceipt:
type: object
description: Receipt issued for a paid order payment.
required: [format]
properties:
number:
type: string
delivery_summary:
$ref: '#/components/schemas/OrderDocumentDeliverySummary'
format:
type: object
required: [web, pdf]
properties:
web:
$ref: '#/components/schemas/OrderDocumentFormat'
pdf:
$ref: '#/components/schemas/OrderDocumentFormat'
PaymentResponse:
type: object
description: Response after initiating payment
properties:
payment_id:
type: string
description: Unique identifier for the payment
order_id:
type: string
description: Associated order ID
status:
type: string
enum: [pending, requires_confirmation, processing, succeeded, failed]
description: Payment status
requires_confirmation:
type: boolean
description: Whether payment requires token confirmation
confirmation_sent:
type: boolean
description: Whether confirmation token was sent to customer
Error:
type: object
description: |
Standard error response structure returned by all API endpoints.
Provides machine-readable codes, human-readable messages, and actionable guidance for resolution.
required:
- type
- code
- url
properties:
message:
type: string
description: Concise, caller-safe explanation of why the request was rejected or could not finish.
example: "payment method could not be used for this order"
fix_code:
type: string
description: Machine-readable suggestion for how to resolve the error (e.g., "retry_with_exponential_backoff", "change_request_parameters").
example: "change_request_parameters"
detail:
type: string
description: Explanation of the relevant rule and next safe action. It never contains raw dependency, storage, or implementation errors.
example: "the specified payment method could not be used for this order. verify that it belongs to the order customer and is active."
cause:
type: string
description: Stable category describing the reason for failure, such as invalid input, an unmet precondition, or a state conflict.
example: "invalid_request_parameter"
type:
type: string
description: Broad error category to help clients determine retry strategies (e.g., "invalid_request_parameter", "transient_error").
example: "invalid_request_parameter"
code:
type: string
description: Unique machine-readable identifier for this specific error condition. Unlike type and cause which group errors, code pinpoints the exact problem.
example: "payment_method_invalid"
url:
type: string
format: uri
description: Link to error reference documentation with detailed explanation, common causes, and resolution guidance.
example: "https://studio.inttegro.com/e/c-invalid_request_parameter"
ErrorEnvelope:
type: object
required: [error]
properties:
error:
$ref: '#/components/schemas/Error'
RefundReason:
type: string
enum:
- requested_by_customer
- duplicate
- fraudulent
- order_canceled
- item_returned
- item_damaged
- item_not_received
- item_not_as_described
- custom
RefundFailureReason:
type: string
description: Stable, caller-safe reason that terminal refund processing failed. `unknown` is the fail-closed fallback for an unclassified internal failure.
enum:
- insufficient_balance
- original_payment_method_unavailable
- original_payment_not_refundable
- refund_not_supported
- amount_not_supported
- refund_declined
- refund_not_permitted
- temporarily_unavailable
- unknown
RefundFailure:
type: object
additionalProperties: false
required: [detail, reason, retryable]
properties:
detail:
type: string
description: Safe explanation intended for the merchant. Raw provider and internal diagnostic messages are never returned.
reason:
$ref: '#/components/schemas/RefundFailureReason'
retryable:
type: boolean
description: Whether the underlying condition may be resolved before creating a new, intentional refund request. It never instructs clients to repeat an uncertain money movement.
RefundSettlement:
description: Immutable destination snapshot for the refund. `payment_method` returns money to the original payment method; `offline` records settlement for an order paid outside Inttegro.
oneOf:
- $ref: '#/components/schemas/RefundOfflineSettlement'
- $ref: '#/components/schemas/RefundPaymentMethodSettlement'
discriminator:
propertyName: type
mapping:
offline: '#/components/schemas/RefundOfflineSettlement'
payment_method: '#/components/schemas/RefundPaymentMethodSettlement'
RefundOfflineSettlement:
type: object
additionalProperties: false
required: [type]
properties:
type:
type: string
enum: [offline]
description: The order was paid offline, so no Inttegro payment method is attached.
RefundPaymentMethodSettlement:
type: object
additionalProperties: false
required: [payment_method, type]
properties:
payment_method:
$ref: '#/components/schemas/RefundSettlementPaymentMethod'
type:
type: string
enum: [payment_method]
description: The refund returns to the original payment method used for the order.
RefundSettlementPaymentMethod:
description: Caller-safe immutable snapshot of the original payment method. Account values are masked and management-only payment-method data is never included.
oneOf:
- $ref: '#/components/schemas/RefundSettlementMobileMoneyPaymentMethod'
- $ref: '#/components/schemas/RefundSettlementBankAccountPaymentMethod'
discriminator:
propertyName: type
mapping:
bank_account: '#/components/schemas/RefundSettlementBankAccountPaymentMethod'
mobile_money: '#/components/schemas/RefundSettlementMobileMoneyPaymentMethod'
RefundSettlementMobileMoneyPaymentMethod:
type: object
additionalProperties: false
required: [id, mobile_money, type]
properties:
id:
type: string
description: Public identifier of the original payment method.
example: pm_xyz789
mobile_money:
type: object
additionalProperties: false
required: [account_number, last4, network]
properties:
account_number:
type: string
pattern: '^\*{4}[0-9]{4}$'
description: Masked mobile-money account number. The full number is never returned.
example: '****7831'
last4:
type: string
pattern: '^[0-9]{4}$'
description: Last four numeric digits of the original account number.
example: '7831'
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
example: mtn
type:
type: string
enum: [mobile_money]
RefundSettlementBankAccountPaymentMethod:
type: object
additionalProperties: false
required: [bank_account, id, type]
properties:
bank_account:
type: object
additionalProperties: false
required: [ghana_bank_account, type]
properties:
ghana_bank_account:
type: object
additionalProperties: false
required: [account_number, last4]
properties:
account_number:
type: string
pattern: '^\*{4}[0-9]{4}$'
description: Masked bank-account number. The full number is never returned.
example: '****7890'
last4:
type: string
pattern: '^[0-9]{4}$'
description: Last four numeric digits of the original bank-account number.
example: '7890'
type:
type: string
enum: [ghana_bank_account]
id:
type: string
description: Public identifier of the original payment method.
example: pm_xyz789
type:
type: string
enum: [bank_account]
CreateRefundLineItem:
type: object
additionalProperties: false
required: [order_line_item_id, refund_amount]
properties:
order_line_item_id:
type: string
description: Strong identifier for the paid order line item being refunded.
example: oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
reason:
$ref: '#/components/schemas/RefundReason'
reason_details:
type: string
maxLength: 2048
description: Line-specific explanation. Requires a line-level reason; required when that reason is `custom`.
refund_amount:
$ref: '#/components/schemas/AmountParams'
RefundRequestMeta:
type: object
additionalProperties: false
properties:
idempotency_key:
type: string
minLength: 1
maxLength: 255
description: Body-level compatibility key. Prefer the `Idempotency-Key` header for new integrations.
CreateRefundRequest:
type: object
additionalProperties: false
required: [line_items, order_id, reason]
properties:
custom_data:
$ref: '#/components/schemas/CustomData'
line_items:
type: array
minItems: 1
maxItems: 64
items:
$ref: '#/components/schemas/CreateRefundLineItem'
order_id:
type: string
description: Paid order to refund.
example: or_0123456789abcdefghijklmnopqrstuvwxyzABCD
reason:
$ref: '#/components/schemas/RefundReason'
reason_details:
type: string
maxLength: 2048
description: Overall explanation. Required when `reason` is `custom`.
reference:
type: string
maxLength: 256
description: Your reconciliation reference.
request_meta:
$ref: '#/components/schemas/RefundRequestMeta'
CancelRefundRequest:
type: object
additionalProperties: false
required: [refund_id]
properties:
refund_id:
type: string
description: Refund to cancel before processing begins.
example: rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
reason:
type: string
minLength: 1
maxLength: 2048
description: Optional explanation for canceling the refund. Leading and trailing whitespace is removed.
request_meta:
$ref: '#/components/schemas/RefundRequestMeta'
LookupRefundRequest:
type: object
additionalProperties: false
required: [refund_id]
properties:
refund_id:
type: string
description: Refund identifier to retrieve.
example: rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
PageRefundsRequest:
type: object
additionalProperties: false
required: [page_number]
properties:
page_number:
type: integer
minimum: 1
maximum: 10
description: One-based page number.
page_size:
type: integer
minimum: 1
maximum: 256
default: 256
description: Maximum number of refunds to return.
RefundLineItem:
type: object
required: [id, order_line_item_id, original_amount_paid, refund_amount]
properties:
id:
type: string
description: Server-generated refund line-item identifier.
order_line_item_id:
type: string
deprecated: true
description: Deprecated compatibility identifier. Use `order_line_item.id` when `order_line_item` is present.
order_line_item:
$ref: '#/components/schemas/RefundOrderLineItem'
original_amount_paid:
$ref: '#/components/schemas/Amount'
reason:
$ref: '#/components/schemas/RefundReason'
reason_details:
type: string
maxLength: 2048
refund_amount:
$ref: '#/components/schemas/Amount'
RefundOrderLineItem:
description: Immutable display snapshot of the refunded order line. Omitted when the originating order cannot be resolved.
oneOf:
- $ref: '#/components/schemas/RefundOrderProductLineItem'
- $ref: '#/components/schemas/RefundOrderFeeLineItem'
- $ref: '#/components/schemas/RefundOrderShippingLineItem'
discriminator:
propertyName: type
mapping:
product: '#/components/schemas/RefundOrderProductLineItem'
fee: '#/components/schemas/RefundOrderFeeLineItem'
shipping: '#/components/schemas/RefundOrderShippingLineItem'
RefundOrderProductLineItem:
type: object
additionalProperties: false
required: [id, product, quantity, type]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
example: oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
type:
type: string
enum: [product]
quantity:
type: integer
minimum: 1
product:
type: object
additionalProperties: false
required: [name]
properties:
id:
type: string
description: Source catalog product identifier. Omitted for inline products.
example: prod_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
name:
type: string
description: Product name captured on the order.
RefundOrderFeeLineItem:
type: object
additionalProperties: false
required: [fee, id, type]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
example: oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
type:
type: string
enum: [fee]
fee:
type: object
additionalProperties: false
properties:
label:
type: string
description:
type: string
RefundOrderShippingLineItem:
type: object
additionalProperties: false
required: [id, shipping, type]
properties:
id:
type: string
description: Immutable order-line identifier with the `oli_` prefix.
example: oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN
type:
type: string
enum: [shipping]
shipping:
type: object
additionalProperties: false
properties:
label:
type: string
description:
type: string
Refund:
type: object
required: [created_at, id, line_items, order_id, reason, settlement, status, total]
properties:
cancel_reason:
type: string
maxLength: 2048
description: Omitted unless a reason was supplied when the refund was canceled.
canceled_at:
type: string
format: date-time
description: Omitted unless the refund was canceled before processing began.
created_at:
type: string
format: date-time
custom_data:
$ref: '#/components/schemas/CustomData'
failed_at:
type: string
format: date-time
description: Omitted unless processing failed.
failure:
$ref: '#/components/schemas/RefundFailure'
description: Sanitized terminal failure information. Present only when `status` is `failed`. An uncertain provider outcome remains `processing` and does not produce this object.
id:
type: string
line_items:
type: array
description: One or more immutable line-level refund allocations.
items:
$ref: '#/components/schemas/RefundLineItem'
order_id:
type: string
order_amount:
$ref: '#/components/schemas/Amount'
description: Total amount of the originating order captured when the refund was created.
processing_at:
type: string
format: date-time
description: Omitted until processing starts.
reason:
$ref: '#/components/schemas/RefundReason'
reason_details:
type: string
maxLength: 2048
reference:
type: string
settlement:
$ref: '#/components/schemas/RefundSettlement'
status:
type: string
enum: [canceled, failed, pending, processing, succeeded]
succeeded_at:
type: string
format: date-time
description: Omitted unless processing succeeded.
total:
$ref: '#/components/schemas/Amount'
RefundResponse:
type: object
required: [refund]
properties:
refund:
$ref: '#/components/schemas/Refund'
RefundPage:
type: object
required: [number, refunds, size]
properties:
number:
type: integer
minimum: 1
refunds:
type: array
items:
$ref: '#/components/schemas/Refund'
size:
type: integer
minimum: 0
description: Number of refunds returned in this page.
RefundPageResponse:
type: object
required: [page]
properties:
page:
$ref: '#/components/schemas/RefundPage'
BalanceSnapshotResponse:
type: object
additionalProperties: false
required: [balances]
properties:
balances:
$ref: '#/components/schemas/BalanceSnapshot'
CurrencyBalanceSnapshot:
type: object
required: [available, held, includes_transactions_before, pending, refund, reserved]
properties:
available:
$ref: '#/components/schemas/BalanceValue'
held:
$ref: '#/components/schemas/BalanceHolds'
includes_transactions_before:
type: string
format: date-time
description: The snapshot includes transactions created before this timestamp
pending:
$ref: '#/components/schemas/BalanceValue'
refund:
allOf:
- $ref: '#/components/schemas/BalanceValue'
description: Funds intentionally earmarked for future refund obligations at the snapshot cutoff
reserved:
allOf:
- $ref: '#/components/schemas/BalanceValue'
description: Funds intentionally reserved for policy, risk, or remediation purposes at the snapshot cutoff
BalanceHolds:
type: object
additionalProperties: false
description: Live operational commitments read from the canonical balance position.
required: [as_of, payout, refund]
properties:
as_of:
type: string
format: date-time
description: When these strongly consistent hold amounts were read.
payout:
allOf:
- $ref: '#/components/schemas/BalanceValue'
description: Funds committed to in-flight or unresolved payouts.
refund:
allOf:
- $ref: '#/components/schemas/BalanceValue'
description: Funds committed to in-flight or unresolved refunds.
BalanceValue:
type: object
required: [amount]
properties:
amount:
type: integer
minimum: 0
description: Amount in the currency's smallest unit
example: 145000
BalanceTransactionAmount:
type: object
additionalProperties: false
required: [currency, value]
properties:
currency:
type: string
description: Currency code as stored on the transaction
example: GHS
value:
type: integer
minimum: 0
description: Unsigned amount in the currency's smallest unit
example: 20000
BalanceTransactionAllocationStatus:
type: string
description: Public effect of an allocation on the source payment balance transaction. Internal reservation and reconciliation states are not exposed.
enum: [pending, completed]
BalanceTransactionAllocation:
description: A caller-safe allocation of part of a payment balance transaction to a refund or payout.
oneOf:
- $ref: '#/components/schemas/BalanceTransactionRefundAllocation'
- $ref: '#/components/schemas/BalanceTransactionPayoutAllocation'
discriminator:
propertyName: type
mapping:
payout: '#/components/schemas/BalanceTransactionPayoutAllocation'
refund: '#/components/schemas/BalanceTransactionRefundAllocation'
BalanceTransactionAllocationBase:
type: object
required: [created_at, id, status, type, updated_at]
properties:
completed_at:
type: string
format: date-time
description: When the allocated amount became permanently consumed. Present only when `status` is `completed`.
created_at:
type: string
format: date-time
description: When the amount first became unavailable for another refund or payout.
id:
type: string
description: Stable public allocation identifier for reconciliation and support.
example: bta_0123456789abcdefghijklmnopqrstuvwxyzABCD
status:
$ref: '#/components/schemas/BalanceTransactionAllocationStatus'
type:
type: string
enum: [payout, refund]
updated_at:
type: string
format: date-time
description: When the public allocation status last changed.
BalanceTransactionRefundAllocation:
allOf:
- $ref: '#/components/schemas/BalanceTransactionAllocationBase'
- type: object
required: [refund]
properties:
type:
type: string
enum: [refund]
refund:
type: object
additionalProperties: false
required: [amount, id]
properties:
amount:
$ref: '#/components/schemas/BalanceTransactionAmount'
id:
type: string
example: rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
BalanceTransactionPayoutAllocation:
allOf:
- $ref: '#/components/schemas/BalanceTransactionAllocationBase'
- type: object
required: [payout]
properties:
type:
type: string
enum: [payout]
payout:
type: object
additionalProperties: false
required: [amount, id]
properties:
amount:
$ref: '#/components/schemas/BalanceTransactionAmount'
id:
type: string
example: po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN
BalanceTransaction:
description: |
Merchant balance entry caused by a payment, refund, or payout. `type` is the
discriminator and describes the semantic source rather than the direction.
oneOf:
- $ref: '#/components/schemas/PaymentBalanceTransaction'
- $ref: '#/components/schemas/RefundBalanceTransaction'
- $ref: '#/components/schemas/PayoutDebitBalanceTransaction'
discriminator:
propertyName: type
mapping:
payment: '#/components/schemas/PaymentBalanceTransaction'
refund: '#/components/schemas/RefundBalanceTransaction'
payout: '#/components/schemas/PayoutDebitBalanceTransaction'
BalanceTransactionBase:
type: object
required: [amount, created_at, id, type]
properties:
amount:
$ref: '#/components/schemas/BalanceTransactionAmount'
created_at:
type: string
format: date-time
id:
type: string
example: bt_0123456789abcdefghijklmnopqrstuvwxyzABCD
type:
type: string
enum: [payment, refund, payout]
description: Semantic source or cause of the transaction, not its direction.
PaymentBalanceTransaction:
allOf:
- $ref: '#/components/schemas/BalanceTransactionBase'
- type: object
required: [order_id, payment_id]
properties:
allocations:
type: array
description: All current pending and completed allocations. Released allocations are omitted.
items:
$ref: '#/components/schemas/BalanceTransactionAllocation'
available_amount:
allOf:
- $ref: '#/components/schemas/BalanceTransactionAmount'
description: Amount still available for a refund or payout.
available_at:
type: string
format: date-time
claimed_at:
type: string
format: date-time
deprecated: true
description: Legacy whole-transaction payout claim timestamp. New integrations should inspect `allocations`.
order_id:
type: string
example: or_0123456789abcdefghijklmnopqrstuvwxyzABCD
paid_at:
type: string
format: date-time
deprecated: true
description: Legacy whole-transaction payout completion timestamp. New integrations should inspect `allocations`.
payment_id:
type: string
example: py_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn
payout_id:
type: string
deprecated: true
description: Legacy payout owning the whole transaction remainder. New integrations should inspect `allocations`.
example: po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN
payout_configuration:
type: object
additionalProperties: false
required: [enable_fx, destination]
properties:
enable_fx:
type: boolean
enum: [false]
destination:
type: object
additionalProperties: false
required: [financial_account_id]
properties:
financial_account_id:
type: string
pending_amount:
allOf:
- $ref: '#/components/schemas/BalanceTransactionAmount'
description: Amount temporarily unavailable because a refund or payout is unresolved.
spent_amount:
allOf:
- $ref: '#/components/schemas/BalanceTransactionAmount'
description: Amount permanently consumed by completed refund and payout allocations.
type:
type: string
enum: [payment]
RefundBalanceTransaction:
allOf:
- $ref: '#/components/schemas/BalanceTransactionBase'
- type: object
required: [order_id, refund_id]
properties:
order_id:
type: string
example: or_0123456789abcdefghijklmnopqrstuvwxyzABCD
refund_id:
type: string
example: rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
type:
type: string
enum: [refund]
PayoutDebitBalanceTransaction:
allOf:
- $ref: '#/components/schemas/BalanceTransactionBase'
- type: object
description: Immutable debit created once a payout succeeds.
required: [payout_id]
properties:
payout_id:
type: string
description: Payout that created this finalized debit.
example: po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN
type:
type: string
enum: [payout]
BalanceTransactionResponse:
type: object
required: [transaction]
properties:
transaction:
$ref: '#/components/schemas/BalanceTransaction'
BalanceTransactionPageResponse:
type: object
required: [page]
properties:
page:
type: object
required: [number, size]
properties:
number:
type: integer
size:
type: integer
minimum: 0
transactions:
type: array
description: Newest transactions first. Omitted when the page is empty.
items:
$ref: '#/components/schemas/BalanceTransaction'
FinancialAccountCreateRequest:
oneOf:
- $ref: '#/components/schemas/FinancialAccountWalletRequest'
- $ref: '#/components/schemas/FinancialAccountBankRequest'
- $ref: '#/components/schemas/FinancialAccountDoshRequest'
discriminator:
propertyName: type
FinancialAccountRequestBase:
type: object
required: [currency, label, reference, type]
properties:
currency:
type: string
description: Supported lowercase currency code
example: ghs
custom_data:
$ref: '#/components/schemas/CustomDataInput'
description:
type: string
maxLength: 200
label:
type: string
minLength: 5
maxLength: 40
owner:
$ref: '#/components/schemas/FinancialAccountOwnerInput'
pull_configuration:
type: object
properties:
enabled:
type: boolean
push_configuration:
type: object
properties:
enabled:
type: boolean
reference:
type: string
minLength: 5
maxLength: 40
type:
type: string
enum: [wallet, bank_account, dosh_account]
FinancialAccountWalletRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountRequestBase'
- type: object
required: [owner, wallet]
properties:
type:
type: string
enum: [wallet]
wallet:
type: object
required: [mobile_money, type]
properties:
type:
type: string
enum: [mobile_money]
mobile_money:
type: object
required: [account_number, network]
properties:
account_number:
type: string
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
FinancialAccountBankRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountRequestBase'
- type: object
description: Owner name and country must be supplied through top-level owner, the bank-account holder, or both. Missing values are filled between the two representations.
required: [bank_account]
properties:
type:
type: string
enum: [bank_account]
bank_account:
type: object
required: [ghana_bank_account, type]
properties:
type:
type: string
enum: [ghana_bank_account]
ghana_bank_account:
type: object
required: [number]
anyOf:
- required: [sort_code]
- required: [swift_code]
properties:
holder:
$ref: '#/components/schemas/FinancialAccountOwnerInput'
number:
type: string
minLength: 1
sort_code:
type: string
minLength: 1
swift_code:
type: string
minLength: 1
FinancialAccountDoshRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountRequestBase'
- type: object
required: [dosh_account, owner]
properties:
type:
type: string
enum: [dosh_account]
dosh_account:
$ref: '#/components/schemas/DoshAccount'
DoshAccount:
type: object
description: Dosh account marker. Dosh credentials and internal identifiers are not supplied by callers or returned publicly.
additionalProperties: false
FinancialAccountOwnerInput:
type: object
required: [address, name]
properties:
name:
type: string
minLength: 1
address:
type: object
required: [country]
properties:
city:
type: string
country:
type: string
minLength: 1
line_1:
type: string
line_2:
type: string
name:
type: string
phone:
type: string
post_code:
type: string
region:
type: string
FinancialAccountIDRequest:
type: object
required: [account_id]
properties:
account_id:
type: string
example: fa_1234567890abcdef
FinancialAccountDisableRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountIDRequest'
- type: object
properties:
unset_as_payout_destination:
type: boolean
default: false
description: Remove this account from payout destinations before the state change. If false, a mapped account is rejected.
FinancialAccountEnablePullRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountIDRequest'
- type: object
properties:
ip_address:
type: string
description: Client IP captured for the mandate. This is not inferred from the request.
user_agent:
type: string
description: Client user agent captured for the mandate. This is not inferred from the request.
FinancialAccountPageRequest:
type: object
required: [page_number]
properties:
page_number:
type: integer
minimum: 1
maximum: 10
page_size:
type: integer
minimum: 1
maximum: 256
default: 256
FinancialAccountUpdateRequest:
allOf:
- $ref: '#/components/schemas/FinancialAccountIDRequest'
- type: object
properties:
custom_data:
$ref: '#/components/schemas/CustomDataPatch'
description:
type: string
label:
type: string
owner:
$ref: '#/components/schemas/FinancialAccountOwnerUpdateInput'
reference:
type: string
FinancialAccountOwnerUpdateInput:
type: object
properties:
name:
type: string
address:
type: object
properties:
city:
type: string
country:
type: string
line_1:
type: string
line_2:
type: string
name:
type: string
phone:
type: string
post_code:
type: string
region:
type: string
FinancialAccountCommonResponse:
type: object
required: [created_at, currency, fingerprint, id, type]
properties:
archived_at:
type: string
format: date-time
created_at:
type: string
format: date-time
currency:
type: string
custom_data:
$ref: '#/components/schemas/CustomData'
description:
type: string
fingerprint:
type: string
description: A stable identifier for the underlying financial account within your application. Use it to recognize when the same account has been connected more than once.
id:
type: string
example: fa_1234567890abcdef
institution:
$ref: '#/components/schemas/FinancialInstitution'
label:
type: string
pull_configuration:
$ref: '#/components/schemas/FinancialAccountPullConfiguration'
push_configuration:
$ref: '#/components/schemas/FinancialAccountPushConfiguration'
reference:
type: string
supplied:
$ref: '#/components/schemas/ResourceSupply'
type:
type: string
enum: [wallet, bank_account, dosh_account]
verification:
$ref: '#/components/schemas/FinancialAccountVerification'
FinancialAccountVerification:
type: object
required: [initiated_at, request]
additionalProperties: false
properties:
initiated_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
request:
$ref: '#/components/schemas/FinancialAccountVerificationRequest'
FinancialAccountVerificationRequest:
type: object
additionalProperties: false
properties:
id:
type: string
mechanism:
type: string
type:
type: string
FinancialAccount:
allOf:
- $ref: '#/components/schemas/FinancialAccountCommonResponse'
- type: object
properties:
bank_account:
$ref: '#/components/schemas/FinancialAccountBankResponse'
disconnected_at:
type: string
format: date-time
dosh_account:
$ref: '#/components/schemas/DoshAccount'
owner:
$ref: '#/components/schemas/FinancialAccountOwnerResponse'
wallet:
$ref: '#/components/schemas/FinancialAccountWalletResponse'
FinancialAccountConnectedResponse:
allOf:
- $ref: '#/components/schemas/FinancialAccountCommonResponse'
- type: object
properties:
bank_account:
$ref: '#/components/schemas/FinancialAccountBankResponse'
dosh_account:
$ref: '#/components/schemas/DoshAccount'
owner:
$ref: '#/components/schemas/FinancialAccountOwnerResponse'
wallet:
$ref: '#/components/schemas/FinancialAccountWalletResponse'
FinancialAccountCreateResponse:
allOf:
- $ref: '#/components/schemas/FinancialAccountCommonResponse'
- type: object
properties:
bank_account:
$ref: '#/components/schemas/FinancialAccountBankCreateResponse'
owner:
$ref: '#/components/schemas/FinancialAccountOwnerCreateResponse'
wallet:
$ref: '#/components/schemas/FinancialAccountWalletResponse'
FinancialAccountUpdateResponse:
allOf:
- $ref: '#/components/schemas/FinancialAccountCommonResponse'
- type: object
properties:
bank_account:
$ref: '#/components/schemas/FinancialAccountBankUpdateResponse'
disconnected_at:
type: string
format: date-time
dosh_account:
$ref: '#/components/schemas/DoshAccount'
owner:
$ref: '#/components/schemas/FinancialAccountOwnerUpdateResponse'
wallet:
$ref: '#/components/schemas/FinancialAccountWalletRawResponse'
FinancialAccountCompactResponse:
type: object
required: [created_at, currency, fingerprint, id, type]
properties:
created_at:
type: string
format: date-time
currency:
type: string
description:
type: string
disconnected_at:
type: string
format: date-time
fingerprint:
type: string
description: A stable identifier for the underlying financial account within your application. Use it to recognize when the same account has been connected more than once.
id:
type: string
label:
type: string
type:
type: string
enum: [wallet, bank_account, dosh_account]
FinancialAccountPage:
type: object
required: [accounts, number, size]
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/FinancialAccount'
number:
type: integer
size:
type: integer
description: Number of accounts returned
FinancialAccountPushConfiguration:
type: object
required: [enabled_at]
properties:
enabled_at:
type: string
format: date-time
FinancialAccountPullConfiguration:
type: object
required: [enabled_at, mandate]
properties:
enabled_at:
type: string
format: date-time
mandate:
$ref: '#/components/schemas/FinancialAccountMandate'
FinancialAccountMandate:
type: object
required: [created_at, id, ip_address, user_agent]
additionalProperties: false
properties:
created_at:
type: string
format: date-time
id:
type: string
example: fm_abc123xyz789
ip_address:
type: string
user_agent:
type: string
FinancialAccountWalletResponse:
type: object
required: [id, type]
properties:
id:
type: string
example: wal_0987654321fedcba
type:
type: string
enum: [mobile_money]
mobile_money:
type: object
required: [account_number, network]
properties:
account_number:
type: string
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
FinancialAccountWalletRawResponse:
allOf:
- $ref: '#/components/schemas/FinancialAccountWalletResponse'
description: Update responses currently return the wallet ID without its type prefix.
FinancialAccountBankResponse:
type: object
required: [type]
properties:
type:
type: string
enum: [ghana_bank_account]
ghana_bank_account:
$ref: '#/components/schemas/GhanaBankAccountResponse'
FinancialAccountBankCreateResponse:
type: object
required: [id, type]
properties:
id:
type: string
description: Empty in the current create response.
type:
type: string
enum: [ghana_bank_account]
ghana_bank_account:
$ref: '#/components/schemas/GhanaBankAccountCreateResponse'
FinancialAccountBankUpdateResponse:
type: object
required: [id, type]
properties:
id:
type: string
type:
type: string
enum: [ghana_bank_account]
ghana_bank_account:
$ref: '#/components/schemas/GhanaBankAccountUpdateResponse'
GhanaBankAccountResponse:
type: object
required: [holder, number]
properties:
branch:
type: string
holder:
$ref: '#/components/schemas/FinancialAccountOwnerResponse'
name:
type: string
number:
type: string
sort_code:
type: string
swift_code:
type: string
GhanaBankAccountCreateResponse:
allOf:
- $ref: '#/components/schemas/GhanaBankAccountResponse'
- type: object
required: [name]
properties:
holder:
$ref: '#/components/schemas/FinancialAccountOwnerCreateResponse'
GhanaBankAccountUpdateResponse:
allOf:
- $ref: '#/components/schemas/GhanaBankAccountResponse'
- type: object
required: [name]
FinancialAccountOwnerResponse:
type: object
required: [address, name]
properties:
address:
$ref: '#/components/schemas/FinancialAccountAddressResponse'
name:
type: string
FinancialAccountOwnerCreateResponse:
type: object
required: [address, name]
properties:
address:
$ref: '#/components/schemas/FinancialAccountAddressCreateResponse'
name:
type: string
FinancialAccountOwnerUpdateResponse:
type: object
required: [address, name]
properties:
address:
$ref: '#/components/schemas/FinancialAccountAddressUpdateResponse'
name:
type: string
FinancialAccountAddressResponse:
type: object
required: [city, country, line_1, region]
properties:
city:
type: string
country:
type: string
line_1:
type: string
line_2:
type: string
name:
type: string
phone:
type: string
post_code:
type: string
region:
type: string
FinancialAccountAddressCreateResponse:
type: object
required: [application_id, city, country, id, line_1, name, region]
properties:
application_id:
type: string
city:
type: string
country:
type: string
id:
type: string
description: Empty in the current create response.
line_1:
type: string
line_2:
type: string
name:
type: string
phone:
type: string
post_code:
type: string
region:
type: string
FinancialAccountAddressUpdateResponse:
type: object
required: [city, country, line_1, region]
properties:
city:
type: string
country:
type: string
id:
type: string
line_1:
type: string
line_2:
type: string
name:
type: string
phone:
type: string
post_code:
type: string
region:
type: string
FinancialInstitution:
type: object
required: [country, id, name, type]
properties:
bank:
type: object
required: [bank_account_type, code_scheme]
properties:
bank_account_type:
type: string
branch:
type: object
required: [id, name, sort_code]
properties:
id:
type: string
name:
type: string
sort_code:
type: string
code_scheme:
type: string
sort_code_prefix:
type: string
swift_code:
type: string
country:
type: string
id:
type: string
mobile_money_provider:
type: object
required: [provider]
properties:
provider:
type: string
name:
type: string
type:
type: string
ResourceSupply:
type: object
required: [by, supplied_at]
properties:
attempt_id:
type: string
by:
type: string
channel:
type: string
resource_id:
type: string
resource_type:
type: string
supplied_at:
type: string
format: date-time
Payout:
type: object
description: A payout scheduled from your Inttegro balance to a destination financial account
additionalProperties: false
required:
- destination_id
- execute_after
- id
- initiated_at
- max_amount
- status
properties:
amount:
$ref: '#/components/schemas/Amount'
balance_transactions:
type: array
description: |
Balance transactions that contributed to this payout. Each item includes
the source transaction's original amount and the exact portion allocated
to this payout. The difference between those two amounts is not necessarily
still available because refunds or other payouts may also consume the source.
items:
$ref: '#/components/schemas/PayoutBalanceTransaction'
balance_transaction_id:
type: string
description: Immutable debit balance transaction created when this payout succeeds.
example: bt_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
canceled_at:
type: string
format: date-time
description: When the payout was canceled
cancellation:
$ref: '#/components/schemas/PayoutCancellation'
description: Caller-safe explanation and next step for a canceled payout. Present only when `status` is `canceled`.
custom_data:
$ref: '#/components/schemas/CustomData'
destination_id:
type: string
description: Financial account receiving the funds
example: "fa_1234567890abcdef"
error:
$ref: '#/components/schemas/PayoutError'
deprecated: true
description: Deprecated compatibility projection of `failure`. New integrations should use `failure`.
execute_after:
type: string
format: date-time
description: Earliest moment payout execution may begin
example: "2026-08-05T09:00:00Z"
executed_by:
type: string
description: Actor that executed the payout
expected_at:
type: string
format: date-time
description: Expected completion time
failed_at:
type: string
format: date-time
description: When the payout entered the `failed` state.
failure:
$ref: '#/components/schemas/PayoutFailure'
description: Caller-safe failure information. Present only when `status` is `failed`.
id:
type: string
description: Unique payout identifier
example: "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB"
initiated_at:
type: string
format: date-time
description: When the payout was created
initiated_by:
type: string
description: Actor that initiated the payout
max_amount:
$ref: '#/components/schemas/Amount'
reference:
type: string
description: Merchant reference carried on the payout
example: "PAYOUT-APR-15"
schedule_id:
type: string
description: Schedule associated with the payout
scheduled_at:
type: string
format: date-time
description: When the payout was scheduled
scheduled_by:
type: string
description: Actor that scheduled the payout
sent_at:
type: string
format: date-time
description: When the transfer was sent
source_id:
type: string
description: Source identifier associated with the payout
status:
type: string
enum: [initialized, scheduled, processing, executing, succeeded, failed, canceled]
description: Current payout lifecycle state
succeeded_at:
type: string
format: date-time
description: When the payout succeeded
PayoutBalanceTransaction:
type: object
description: A historical view of one balance transaction's contribution to a payout. Released contributions remain present so clients can inspect the payout's original composition.
additionalProperties: false
required: [allocated_amount, amount, id, status]
properties:
allocated_amount:
$ref: '#/components/schemas/Amount'
amount:
$ref: '#/components/schemas/Amount'
id:
type: string
description: Unique balance transaction identifier.
example: bt_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd
status:
type: string
enum: [reserved, completed, released]
description: Whether this contribution is still reserved for the payout, was consumed by a successful payout, or was released after the payout did not complete.
PayoutCancellation:
type: object
description: Stable, caller-safe information and guidance for a canceled payout.
additionalProperties: false
required: [detail, reason, remediation]
properties:
detail:
type: string
description: Human-readable explanation safe to show to an operator.
reason:
type: string
enum: [requested, no_eligible_funds, unknown]
description: Stable category describing why the payout was canceled.
remediation:
type: string
description: Recommended next step safe to show to an operator.
PayoutError:
type: object
deprecated: true
description: Deprecated compatibility projection of `PayoutFailure`.
additionalProperties: false
required:
- cause
- message
- occurred_at
- type
properties:
cause:
type: string
description: Public explanation of the underlying failure cause.
message:
type: string
description: Human-readable failure message.
occurred_at:
type: string
format: date-time
description: When the failure occurred.
type:
type: string
description: Stable machine-readable failure category.
PayoutFailure:
type: object
description: Stable, caller-safe information about a terminal payout failure.
additionalProperties: false
required: [detail, reason, retryable]
properties:
detail:
type: string
description: Human-readable explanation safe to show to an operator.
reason:
type: string
enum: [provider_declined, delivery_failed, temporarily_unavailable, unknown]
description: Stable category describing why the payout failed.
retryable:
type: boolean
description: Whether creating a new payout attempt may succeed without changing the destination or request.
PayoutSettingsLookupScheduleAgingSpec:
type: object
description: Rules that determine when balance transactions become eligible for payout.
additionalProperties: false
required:
- abide
- label
- t_plus
properties:
abide:
type: string
description: How strictly the aging period is applied.
label:
type: string
description: Human-readable aging rule label.
t_plus:
type: string
description: Required transaction age.
example: "168h"
PayoutSettingsLookupSchedule:
type: object
description: Active payout schedule returned when settings are retrieved.
additionalProperties: false
required:
- aging_spec
- description
- interval
- name
- schedule_on
- type
properties:
aging_spec:
$ref: '#/components/schemas/PayoutSettingsLookupScheduleAgingSpec'
description:
type: string
interval:
type: string
name:
type: string
schedule_on:
type: string
type:
type: string
PayoutSettingsLookup:
type: object
description: Complete payout settings read model
additionalProperties: false
required:
- destinations
- limits
properties:
destinations:
$ref: '#/components/schemas/PayoutDestinations'
fx_enabled:
type: boolean
description: Present only when foreign exchange is enabled in stored settings
limits:
$ref: '#/components/schemas/PayoutSettingsLimits'
schedule:
$ref: '#/components/schemas/PayoutSettingsLookupSchedule'
PayoutSettingsLimits:
type: object
description: Platform limits applied to payouts.
additionalProperties: false
required:
- amount
properties:
amount:
$ref: '#/components/schemas/PayoutAmountLimits'
PayoutAmountLimits:
type: object
description: Inclusive payout amount range. Values use the currency's smallest unit.
additionalProperties: false
required:
- min
- max
properties:
min:
$ref: '#/components/schemas/Amount'
max:
$ref: '#/components/schemas/Amount'
PayoutSettingsMutationScheduleSpec:
type: object
description: Public payout schedule specification returned after a settings mutation.
additionalProperties: false
required:
- abide
- id
- label
- t_plus
properties:
abide:
type: string
id:
type: string
label:
type: string
t_plus:
type: string
example: "168h"
PayoutSettingsMutationSchedule:
type: object
description: Updated payout schedule returned after a settings mutation.
additionalProperties: false
required:
- description
- id
- interval
- name
- schedule_on
- spec
- type
properties:
description:
type: string
id:
type: string
interval:
type: string
name:
type: string
schedule_on:
type: string
spec:
$ref: '#/components/schemas/PayoutSettingsMutationScheduleSpec'
type:
type: string
PayoutSettingsMutation:
type: object
description: Payout settings fields returned after a mutation
additionalProperties: false
required:
- limits
properties:
destinations:
$ref: '#/components/schemas/PayoutDestinations'
fx_enabled:
type: boolean
description: Updated foreign-exchange setting, returned by FX mutations.
id:
type: string
description: Payout settings identifier
limits:
$ref: '#/components/schemas/PayoutSettingsLimits'
schedule:
$ref: '#/components/schemas/PayoutSettingsMutationSchedule'
SchedulePayoutRequest:
type: object
description: Parameters for scheduling a payout.
additionalProperties: false
required:
- destination_id
- reference
properties:
destination_id:
type: string
description: Financial account that should receive the payout.
example: "fa_1234567890abcdef"
execute_after:
type: string
format: date-time
description: Optional future time after which execution may begin.
example: "2026-08-05T09:00:00Z"
max_amount:
type: integer
minimum: 25000
description: Maximum amount, in the smallest currency unit, that this payout may transfer.
example: 250000
reference:
type: string
description: Merchant reference carried on the payout.
example: "PAYOUT-APR-15"
LookupPayoutRequest:
type: object
description: Parameters for retrieving a payout.
additionalProperties: false
required:
- payout_id
properties:
payout_id:
type: string
description: Payout identifier returned when the payout was created.
example: "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB"
CancelPayoutRequest:
type: object
description: Parameters for canceling a scheduled payout.
additionalProperties: false
required:
- payout_id
properties:
payout_id:
type: string
description: Scheduled payout identifier.
example: "po_yQ2wXm5Dc7Pk9Ls1Vn0RgHaB"
SetPayoutDestinationsRequest:
type: object
description: Supported payout destination assignments to update.
additionalProperties: false
required:
- destinations
properties:
destinations:
$ref: '#/components/schemas/PayoutDestinations'
PagePayoutsRequest:
type: object
description: Pagination parameters for payouts.
additionalProperties: false
required:
- page_number
properties:
page_number:
type: integer
minimum: 1
maximum: 10
description: 1-based page index to fetch (1-10 inclusive).
page_size:
type: integer
minimum: 1
maximum: 256
default: 256
description: Maximum number of payouts to return (1-256).
PayoutPage:
type: object
description: A page of payouts ordered from newest to oldest.
additionalProperties: false
required:
- number
- size
properties:
number:
type: integer
description: Page number returned.
size:
type: integer
description: Number of payouts returned.
payouts:
type: array
items:
$ref: '#/components/schemas/Payout'
PayoutResponse:
type: object
description: Response envelope containing a payout.
additionalProperties: false
properties:
payout:
$ref: '#/components/schemas/Payout'
PayoutSettingsLookupResponse:
type: object
description: Response envelope containing complete payout settings.
additionalProperties: false
properties:
settings:
$ref: '#/components/schemas/PayoutSettingsLookup'
PayoutSettingsMutationResponse:
type: object
description: Response envelope containing updated payout settings.
additionalProperties: false
properties:
settings:
$ref: '#/components/schemas/PayoutSettingsMutation'
PayoutPageResponse:
type: object
description: Response envelope containing a page of payouts.
additionalProperties: false
properties:
page:
$ref: '#/components/schemas/PayoutPage'
PaymentMethodOwnerInput:
type: object
required:
- address
- name
properties:
address:
type: object
required:
- country
properties:
city:
type: string
country:
type: string
minLength: 1
description: Country associated with the owner address.
example: "GH"
line1:
type: string
line2:
type: string
name:
type: string
phone_number:
type: string
post_code:
type: string
region:
type: string
name:
type: string
minLength: 1
description: Payment method owner's name.
example: "Jane Mensah"
PaymentMethodTokenizeBase:
type: object
required:
- customer_id
- type
properties:
customer_id:
type: string
minLength: 1
description: Existing customer in the authenticated application who will own the payment method.
example: "cu_a1b2c3d4e5"
custom_data:
$ref: '#/components/schemas/CustomData'
type:
type: string
enum: [mobile_money]
TokenizeMobileMoneyPaymentMethodRequest:
allOf:
- $ref: '#/components/schemas/PaymentMethodTokenizeBase'
- type: object
required:
- mobile_money
- owner
properties:
type:
type: string
enum: [mobile_money]
mobile_money:
type: object
required:
- account_number
- network
properties:
account_number:
type: string
minLength: 1
description: Mobile-money number in a valid local or international phone-number format.
example: "+233242057831"
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
example: "mtn"
owner:
$ref: '#/components/schemas/PaymentMethodOwnerInput'
PaymentMethodObject:
type: object
description: A tokenized payment instrument tied to a customer
required:
- id
- active
- customer_id
- fingerprint
- type
- created_at
properties:
active:
type: boolean
description: Whether this payment method is active and reusable in new payment flows
example: true
archived_at:
type: string
format: date-time
description: Timestamp when the payment method was archived. Omitted while unarchived.
bank_account:
type: object
description: Bank account details (present when type is bank_account)
required:
- type
properties:
ghana_bank_account:
type: object
description: Ghana bank account details
required:
- account_number
properties:
branch:
type: string
description: Branch name
example: "Accra Main"
name:
type: string
description: Account holder name
example: "John Doe"
account_number:
type: string
description: Account number
example: "1234567890"
sort_code:
type: string
description: Bank sort code
example: "030100"
swift_code:
type: string
description: SWIFT/BIC code
example: "GHBAGHAACCRA"
type:
type: string
description: Bank account sub-type
enum: [ghana_bank_account]
example: "ghana_bank_account"
card:
$ref: '#/components/schemas/PaymentMethodCard'
created_at:
type: string
format: date-time
description: When this payment method was tokenized
example: "2025-11-23T13:00:00Z"
custom_data:
$ref: '#/components/schemas/CustomData'
customer_id:
type: string
description: Customer who owns this payment method
example: "cu_a1b2c3d4e5"
ephemeral:
type: boolean
description: Whether the method is limited to its originating flow and cannot be reused.
example: false
expires_on:
type: string
format: date-time
description: When this payment method expires. Omitted when no expiry is available.
fingerprint:
type: string
description: Customer-scoped fingerprint for this payment method within the merchant application. Matching nonempty values for the same customer indicate the same underlying method was added more than once. May be empty for records awaiting fingerprint backfill or methods lacking reliable fingerprint material. It does not identify the method across customers or applications.
id:
type: string
description: Unique identifier for this payment method
example: "pm_xyz789"
mobile_money:
type: object
description: Masked mobile-money wallet details (present when type is mobile_money)
required:
- account_number
- last4
- network
properties:
account_number:
type: string
description: Masked wallet number. The full account number is never returned.
example: "****7831"
last4:
type: string
description: Last four numeric digits of the normalized wallet number.
example: "7831"
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
description: Mobile network operator
example: "mtn"
owner:
type: object
description: Owner identity captured during tokenization when provided
required:
- name
properties:
address:
type: object
description: Postal address for the owner when available
required:
- country
properties:
city:
type: string
description: City or locality
example: "Accra"
country:
type: string
description: Two-letter ISO country code
example: "GH"
line_1:
type: string
description: First line of the street address
example: "1 High Street"
line_2:
type: string
description: Second line of the street address
example: "Osu"
name:
type: string
description: Recipient name at this address, if different from owner name
example: "Jane Mensah"
phone_number:
type: string
description: Phone number for this address
example: "+233201234567"
post_code:
type: string
description: Postal or ZIP code
example: "GA-123-4567"
region:
type: string
description: Region, state, or province
example: "Greater Accra"
name:
type: string
description: Owner full legal name
example: "Yaw Boakye"
type:
type: string
enum: [mobile_money, bank_account, card, motito]
description: Payment rail type
example: "mobile_money"
supplied:
type: object
description: Public provenance for how the payment method was supplied.
required:
- by
- supplied_at
properties:
attempt_id:
type: string
by:
type: string
channel:
type: string
resource_id:
type: string
resource_type:
type: string
supplied_at:
type: string
format: date-time
verification:
type: object
description: Most recent verification record when the payment method has entered a verification flow.
required:
- initiated_at
- request_id
- type
properties:
completed_at:
type: string
format: date-time
description: When verification was completed
example: "2025-11-23T13:07:00Z"
initiated_at:
type: string
format: date-time
description: When verification was initiated
example: "2025-11-23T13:00:00Z"
mechanism:
type: string
description: Verification mechanism used
example: "otp"
request_id:
type: string
description: ID of the verification request
example: "req_abc123"
type:
type: string
description: Verification type
example: "sms_otp"
verified_at:
type: string
format: date-time
description: When ownership verification was completed
example: "2025-11-23T13:07:00Z"
PaymentMethodCard:
type: object
additionalProperties: false
description: Card marker. Nested card credentials are not returned.
PaymentMethodData:
type: object
description: Payment instrument details for tokenization
required:
- type
properties:
type:
type: string
enum: [mobile_money]
description: Payment rail type (currently only mobile_money supported)
example: "mobile_money"
mobile_money:
type: object
description: Mobile money wallet details (required when type is mobile_money)
required:
- network
- account_number
properties:
network:
type: string
enum: [airtel, mtn, telecel, vodafone]
description: Mobile money network provider
example: "mtn"
account_number:
type: string
description: Mobile money account number (international or local format)
example: "+233242057831"
pattern: '^(\+?\d{10,15})$'
PaymentMethodSettings:
type: object
description: Payment method acceptance configuration for an application
properties:
mobile_money:
$ref: '#/components/schemas/PaymentMethodTypeSetting'
bank_account:
$ref: '#/components/schemas/PaymentMethodTypeSetting'
card:
$ref: '#/components/schemas/PaymentMethodTypeSetting'
motito:
$ref: '#/components/schemas/PaymentMethodTypeSetting'
PaymentMethodTypeSetting:
type: object
description: Settings for a specific payment method type
required:
- confirms_use
- enabled
properties:
type:
type: string
enum: [mobile_money, bank_account, card, motito]
description: Payment method type
example: "mobile_money"
name:
type: string
description: Human-readable name
example: "Mobile Money"
description:
type: string
description: Description of this payment method
example: "Pay with supported mobile money wallets"
enabled:
type: boolean
description: Whether this payment type can be used
example: true
confirms_use:
type: boolean
description: Whether customers must explicitly agree before using
example: true
CountrySpecification:
type: object
description: Complete specification for a country including supported features and requirements
required: [bt_aging_specs, country_code, country_name, currencies, financial_account_types, id_document_types, legal_entity_types, payment_methods, payout_schedules]
properties:
country_code:
type: string
description: ISO 3166-1 alpha-2 country code
example: "gh"
country_name:
type: string
description: Full country name
example: "Ghana"
currencies:
type: array
description: Supported currencies in this country
items:
type: string
example: ["ghs", "usd"]
payment_methods:
type: array
description: Supported payment methods in this country
items:
type: string
example: ["mobile_money", "bank_account", "payment_card", "motito"]
payout_schedules:
type: array
description: Available payout schedules for this country
items:
type: string
example: ["weekly", "manual"]
bt_aging_specs:
type: array
description: Balance transaction aging specifications available
items:
type: string
example: ["twenty_four_hourly", "forty_eight_hourly", "hundred_sixty_eight_hourly"]
legal_entity_types:
type: array
description: Legal entity types that can operate in this country
items:
type: string
financial_account_types:
type: array
description: Financial account types available in this country
items:
type: string
id_document_types:
type: array
description: Identification document types accepted in this country
items:
type: string
banks:
$ref: '#/components/schemas/CountryBankDirectory'
CountryBankDirectory:
type: object
description: Bank reference data available for country-specific bank accounts
required: [bank_account_type, code_scheme, items]
properties:
bank_account_type:
type: string
description: Country-specific bank account subtype used by financial account APIs
example: "ghana_bank_account"
code_scheme:
type: string
description: Identifier scheme used for bank branch codes
example: "sort_code"
items:
type: array
description: Banking institutions available in this country
items:
$ref: '#/components/schemas/CountryBank'
CountryBank:
type: object
description: A banking institution available in a country
required: [branches, id, name]
properties:
id:
type: string
description: Stable bank identifier
example: "absa_gh_ltd"
name:
type: string
description: Bank display name
example: "ABSA (GH) LTD"
swift_code:
type: string
description: SWIFT/BIC code for the bank, when available
example: "BARCGHAC"
sort_code_prefix:
type: string
description: Ghana sort code prefix for the bank
example: "03"
branches:
type: array
description: Branches available for this bank
items:
$ref: '#/components/schemas/CountryBankBranch'
CountryBankBranch:
type: object
description: A bank branch in a country bank directory
required: [id, name, sort_code]
properties:
id:
type: string
description: Stable branch identifier
example: "absa_gh_ltd_kasoa_branch"
name:
type: string
description: Branch display name
example: "ABSA (GH) LTD-KASOA BRANCH"
sort_code:
type: string
description: Ghana bank branch sort code
example: "030101"
LookupChimeRequest:
type: object
description: Request to look up a chime by ID
required:
- chime_id
properties:
chime_id:
type: string
description: Unique identifier of the chime to look up
example: "ch_1234567890abcdef1234567890abcdef12345678"
PageChimesRequest:
type: object
description: Request to retrieve a page of chimes
properties:
customer_id:
type: string
description: Restrict the page to chimes associated with this customer
example: "cu_abc123def456"
page_number:
type: integer
minimum: 1
maximum: 10
default: 1
description: 1-based page index to fetch
example: 1
page_size:
type: integer
minimum: 1
maximum: 256
default: 256
description: Number of chimes to return
example: 25
recipient:
type: string
description: Restrict the page to chimes whose recipient exactly matches this phone number or email address
example: "+233544998605"
SendChimeRequest:
type: object
description: |
Request to send a chime to a recipient.
SMS recipients accept either `full_message` or `message_template`.
Email recipients accept either `email` or `message_template`.
required:
- recipient
properties:
recipient:
$ref: '#/components/schemas/ChimeRecipient'
full_message:
type: string
description: Complete SMS message content. Use only with SMS recipients.
example: "Your verification code is 123456. It expires in 10 minutes."
email:
$ref: '#/components/schemas/ChimeEmailMessageInput'
message_template:
$ref: '#/components/schemas/MessageTemplateReference'
sender_id:
type: string
description: Sender identifier shown to recipient. Uses default sender if not provided.
example: "YourBrand"
purpose:
type: string
description: Purpose of this chime for categorization and analytics
example: "verification"
cooldown:
type: object
description: Optional application-scoped delivery cooldown. A repeat send with the same key is rejected until the duration elapses.
additionalProperties: false
required: [key, duration_seconds]
properties:
key:
type: string
minLength: 1
maxLength: 120
description: Stable identifier for the notification being sent.
duration_seconds:
type: integer
minimum: 1
maximum: 86400
description: Rolling cooldown from the first accepted send attempt.
custom_data:
$ref: '#/components/schemas/CustomData'
request_meta:
type: object
description: Optional metadata controlling request processing
properties:
idempotency_key:
type: string
description: Unique key to prevent duplicate sends
example: "chime_send_20231214_abc123"
ChimeRecipient:
oneOf:
- $ref: '#/components/schemas/ChimeInlineRecipient'
- $ref: '#/components/schemas/ChimeSavedCustomerRecipient'
ChimeInlineRecipient:
oneOf:
- type: object
additionalProperties: false
required: [phone, type]
properties:
name:
type: string
phone:
type: object
additionalProperties: false
required: [number]
properties:
number:
type: string
example: "+233544998605"
type:
type: string
enum: [phone]
- type: object
additionalProperties: false
required: [email, type]
properties:
email:
type: object
additionalProperties: false
required: [address]
properties:
address:
type: string
format: email
example: "user@example.com"
name:
type: string
type:
type: string
enum: [email]
ChimeSavedCustomerRecipient:
type: object
additionalProperties: false
required: [customer_id, transport]
properties:
customer_id:
type: string
example: cu_abc123def456
transport:
type: string
enum: [sms, email]
ChimeResponse:
type: object
description: Response containing chime details
properties:
chime:
$ref: '#/components/schemas/Chime'
PageChimesResponse:
type: object
description: Response containing a page of chimes
properties:
page:
type: object
required:
- number
- size
- chimes
properties:
number:
type: integer
description: Page number returned
example: 1
size:
type: integer
description: Page size returned
example: 25
chimes:
type: array
description: Chimes in this page
items:
$ref: '#/components/schemas/Chime'
Chime:
type: object
description: A notification sent to one recipient
required: [created_at, full_message, id, recipient, sender_id]
properties:
created_at:
type: string
format: date-time
custom_data:
$ref: '#/components/schemas/CustomData'
customer_id:
type: string
email:
$ref: '#/components/schemas/ChimeEmailMessage'
full_message:
type: string
description: Rendered SMS content. Empty for email Chimes.
id:
type: string
idempotency_key:
type: string
purpose:
type: string
recipient:
$ref: '#/components/schemas/ChimeRecipientResponse'
sender_id:
type: string
transmission:
$ref: '#/components/schemas/ChimeTransmission'
ChimeTransmission:
type: object
required: [address, created_at, gateway, id, initialized_at, mechanism, status]
properties:
address:
type: string
created_at:
type: string
format: date-time
delivered_at:
type: string
format: date-time
email_events:
type: array
items:
$ref: '#/components/schemas/ChimeEmailEvent'
email_failure_code:
type: string
email_failure_reason:
type: string
email_status:
type: string
error:
type: string
failed_at:
type: string
format: date-time
gateway:
type: string
gateway_message_id:
type: string
id:
type: string
initialized_at:
type: string
format: date-time
last_email_event_at:
type: string
format: date-time
mechanism:
type: string
enum: [sms, email]
sent_at:
type: string
format: date-time
sent_via:
type: string
enum: [sms, email]
status:
type: string
suppressed_at:
type: string
format: date-time
suppression_reason:
type: string
ChimeEmailEvent:
type: object
required: [id, occurred_at, provider, provider_message_id, type]
properties:
bounce_sub_type:
type: string
bounce_type:
type: string
complaint_sub_type:
type: string
id:
type: string
occurred_at:
type: string
format: date-time
provider:
type: string
provider_message_id:
type: string
reason:
type: string
reason_code:
type: string
recipient:
type: string
source:
type: string
suppress_recipient:
type: boolean
temporary:
type: boolean
type:
type: string
ChimeEmailMessageInput:
type: object
description: Email content accepted for email chimes, broadcasts, and schedules.
required:
- subject
- text
- from
properties:
subject:
type: string
description: Email subject.
example: "Your receipt"
text:
type: string
description: Plain-text email body.
example: "Your receipt is ready."
html:
type: string
description: Optional HTML email body. Unsafe HTML is rejected or sanitized before delivery.
from:
$ref: '#/components/schemas/ChimeEmailMailbox'
reply_to:
type: string
format: email
description: Optional reply-to email address.
example: "support@example.com"
headers:
$ref: '#/components/schemas/MessageHeaders'
ChimeEmailMessage:
type: object
description: Email content, safety scan result, and system-generated schema markup for email chimes.
properties:
subject:
type: string
description: Email subject
example: "Your receipt"
text:
type: string
description: Plain-text email body
example: "Your receipt is ready."
html:
type: string
description: Optional HTML email body before provider-specific rendering
nullable: true
from:
$ref: '#/components/schemas/ChimeEmailMailbox'
reply_to:
$ref: '#/components/schemas/ChimeEmailMailbox'
headers:
$ref: '#/components/schemas/MessageHeaders'
safety:
$ref: '#/components/schemas/ChimeEmailSafetyResult'
schema:
$ref: '#/components/schemas/ChimeEmailSchemaMarkup'
ChimeEmailMailbox:
type: object
properties:
name:
type: string
description: Optional display name
example: "Acme"
address:
type: string
format: email
description: Email address
example: "notifications@inttegro.com"
ChimeEmailSafetyResult:
type: object
description: Result of the email safety scan
properties:
status:
type: string
enum: [allowed, rejected, quarantined]
description: Safety decision for the email content
reason_codes:
type: array
items:
type: string
description: Machine-readable reasons for non-allowed results
sanitized_html:
type: string
description: Sanitized HTML body used for provider send when present
nullable: true
normalized_text:
type: string
description: Normalized plain-text body used by the scanner
links:
type: array
items:
$ref: '#/components/schemas/ChimeEmailScannedLink'
scanner:
type: string
description: Safety scanner identifier
example: "content-safety"
content_hash:
type: string
description: Hash of the scanned email content
quarantine_notes:
type: string
nullable: true
ChimeEmailScannedLink:
type: object
properties:
raw:
type: string
scheme:
type: string
host:
type: string
status:
type: string
enum: [allowed, rejected, quarantined]
reason:
type: string
ChimeEmailSchemaMarkup:
type: object
description: Schema.org JSON-LD markup generated at email send time.
properties:
kind:
type: string
enum: [gmail_view_action, schema_org_order, schema_org_invoice]
description: Classification for the generated markup
json_ld:
$ref: '#/components/schemas/JSONData'
ChimeRecipientResponse:
type: object
description: Recipient information in response
required: [type]
properties:
type:
type: string
enum: [phone, email]
description: Contact type
example: "phone"
name:
type: string
description: Recipient name
example: "John Doe"
phone:
type: object
properties:
number:
type: string
example: "+233544998605"
required: [number]
email:
type: object
properties:
address:
type: string
example: "user@example.com"
required: [address]
ScheduleChimeRequest:
type: object
required:
- recipients
- send_after
properties:
request_meta:
type: object
properties:
idempotency_key:
type: string
description: Stable retry key. It must match the Idempotency-Key header when both are provided.
recipients:
type: array
description: Recipient objects for this scheduled chime. Each item must include `transport` and either inline contact details or `customer_id`.
items:
$ref: '#/components/schemas/ChimeRecipient'
minItems: 1
example:
- customer_id: "cu_abc123def456"
transport: "sms"
- type: "phone"
phone:
number: "+233544998605"
send_after:
type: string
format: date-time
description: ISO 8601 timestamp for when to send the chime (must be in the future)
example: "2025-12-15T10:00:00Z"
full_message:
type: string
description: Complete SMS message content. Use only with SMS recipients.
example: "Reminder: Your appointment is tomorrow at 10 AM."
email:
$ref: '#/components/schemas/ChimeEmailMessageInput'
message_template:
$ref: '#/components/schemas/MessageTemplateReference'
sender_id:
type: string
description: Sender identifier displayed to recipients
example: "YourBrand"
purpose:
type: string
description: Optional purpose or category for this scheduled chime
example: "appointment_reminder"
ScheduleResponse:
type: object
properties:
scheduled_chime:
$ref: '#/components/schemas/ScheduleCreationDetail'
ScheduleCreationDetail:
type: object
required: [created_at, full_message, id, send_after, sender_id]
properties:
created_at:
type: string
format: date-time
customer_ids:
type: array
items:
type: string
email:
$ref: '#/components/schemas/ChimeEmailMessage'
executed_at:
type: string
format: date-time
full_message:
type: string
id:
type: string
idempotency_key:
type: string
purpose:
type: string
recipients:
type: array
items:
type: string
send_after:
type: string
format: date-time
sender_id:
type: string
LookupScheduleRequest:
type: object
required: [schedule_id]
properties:
schedule_id:
type: string
CancelScheduleRequest:
type: object
required: [schedule_id]
properties:
schedule_id:
type: string
ScheduleLookupResponse:
type: object
properties:
scheduled_chime:
$ref: '#/components/schemas/ScheduleDetail'
ScheduleCancelResponse:
type: object
properties:
scheduled_chime:
$ref: '#/components/schemas/ScheduleCancelDetail'
ScheduleDetail:
type: object
required: [content, created_at, id, recipients, send_after, sender_id]
properties:
chime_ids:
type: array
items:
type: string
content:
type: string
created_at:
type: string
format: date-time
customer_ids:
type: array
items:
type: string
email:
$ref: '#/components/schemas/ChimeEmailMessage'
errors:
type: array
items:
$ref: '#/components/schemas/ScheduleError'
executed_at:
type: string
format: date-time
id:
type: string
idempotency_key:
type: string
purpose:
type: string
recipients:
type: array
items:
type: string
send_after:
type: string
format: date-time
sender_id:
type: string
ScheduleCancelDetail:
allOf:
- $ref: '#/components/schemas/ScheduleDetail'
- type: object
properties:
canceled_at:
type: string
format: date-time
ScheduleError:
type: object
description: Error encountered when scheduling a chime for a specific recipient
properties:
recipient:
type: string
description: Recipient address that caused the error
example: "+233invalid"
fix_code:
type: string
description: Code indicating how to fix this error
example: "check_recipient"
type:
type: string
description: Error type classification
example: "invalid_recipient"
BroadcastRequest:
type: object
required:
- recipients
properties:
request_meta:
type: object
properties:
idempotency_key:
type: string
description: Stable retry key. It must match the Idempotency-Key header when both are provided.
message_template:
oneOf:
- type: string
description: Raw SMS message content for SMS broadcasts.
example: "Your order #12345 has shipped."
- $ref: '#/components/schemas/MessageTemplateReference'
description: Raw SMS content for SMS broadcasts, or a stored message template reference for SMS or email broadcasts.
email:
$ref: '#/components/schemas/ChimeEmailMessageInput'
purpose:
type: string
description: Category or intent for this broadcast.
example: "order_notification"
recipients:
type: array
description: Recipient objects for this broadcast. Each item must include `transport` and either inline contact details or `customer_id`.
items:
$ref: '#/components/schemas/ChimeRecipient'
minItems: 1
example:
- customer_id: "cu_abc123def456"
transport: "email"
- type: "email"
email:
address: "user@example.com"
sender:
type: string
description: Sender identifier displayed to recipients.
example: "YourBrand"
BroadcastResponse:
type: object
properties:
broadcast:
$ref: '#/components/schemas/BroadcastCreationDetail'
BroadcastCreationDetail:
type: object
required: [content, created_at, id, recipients, send_after, sender_id]
properties:
content:
type: string
created_at:
type: string
format: date-time
customer_ids:
type: array
items:
type: string
email:
$ref: '#/components/schemas/ChimeEmailMessage'
id:
type: string
idempotency_key:
type: string
purpose:
type: string
recipients:
type: array
items:
type: string
send_after:
type: string
format: date-time
sender_id:
type: string
LookupBroadcastRequest:
type: object
required: [broadcast_id]
properties:
broadcast_id:
type: string
LookupBroadcastResponse:
type: object
properties:
broadcast:
$ref: '#/components/schemas/BroadcastDetail'
CancelBroadcastRequest:
type: object
required: [broadcast_id]
properties:
broadcast_id:
type: string
BroadcastCancelResponse:
type: object
properties:
broadcast:
$ref: '#/components/schemas/BroadcastCancelDetail'
BroadcastDetail:
type: object
required: [content, created_at, id, recipients, send_after, sender_id]
properties:
chime_ids:
type: array
items:
type: string
content:
type: string
created_at:
type: string
format: date-time
customer_ids:
type: array
items:
type: string
email:
$ref: '#/components/schemas/ChimeEmailMessage'
errors:
type: array
items:
$ref: '#/components/schemas/BroadcastError'
executed_at:
type: string
format: date-time
id:
type: string
idempotency_key:
type: string
purpose:
type: string
recipients:
type: array
items:
type: string
send_after:
type: string
format: date-time
sender_id:
type: string
BroadcastCancelDetail:
allOf:
- $ref: '#/components/schemas/BroadcastDetail'
- type: object
properties:
canceled_at:
type: string
format: date-time
BroadcastError:
type: object
description: Error encountered when broadcasting to a specific recipient
properties:
recipient:
type: string
description: Recipient address that caused the error
example: "+233invalid"
fix_code:
type: string
description: Code indicating how to fix this error
example: "check_recipient"
type:
type: string
description: Error type classification
example: "invalid_recipient"
InitiateOTPRequest:
type: object
required: [purpose, recipient, service_name, token_size]
additionalProperties: false
properties:
async_delivery:
type: boolean
description: Return after accepting the transaction while delivery continues asynchronously.
default: false
message_template:
type: string
description: SMS body or email copy containing the required `{token}` placeholder and optional `{service}` placeholder. Email templates must contain `{token}` exactly once. A custom template replaces the purpose-specific default body, while `purpose` still controls the email subject and heading. Email sends this as the plain-text fallback and renders the copy around a prominent code in the HTML version. Defaults are transport-specific.
example: "Your {service} code is {token}."
preferred_gateway:
type: string
description: Optional SMS gateway; not valid for email OTP delivery. Email uses the configured default provider.
example: "arkesel"
purpose:
$ref: '#/components/schemas/OTPPurpose'
recipient:
type: string
description: Phone number in international format (E.164) or bare email address. Transport is inferred from the address unless specified.
example: "+233241234567"
sender:
type: string
description: Optional SMS sender identifier (3-12 characters). Email OTP always uses `{service_name} `; omit this field for email or supply exactly the bare `noreply@inttegro.com` address.
example: "Acme"
service_name:
type: string
description: Service name substituted for `{service}` (2-20 characters).
minLength: 2
maxLength: 20
example: "Acme Bank"
token_alphabet:
type: string
description: Custom alphabet for token generation (mutually exclusive with token_alphabet_type)
example: "0123456789ABCDEF"
token_alphabet_type:
type: string
description: Predefined alphabet type (mutually exclusive with token_alphabet)
enum: [numeric, alpha, alphanumeric]
example: "numeric"
token_size:
type: integer
description: Length of generated token (5-10 characters)
minimum: 5
maximum: 10
example: 6
transport:
type: string
description: Optional delivery transport. When omitted, an email address selects email and a phone number selects SMS.
enum: [sms, email]
validity_duration_in_minutes:
type: integer
description: How long the token remains valid (3-10080 minutes)
minimum: 3
maximum: 10080
example: 10
InitiateOTPResponse:
type: object
required: [transaction]
properties:
transaction:
$ref: '#/components/schemas/OTPTransaction'
VerifyOTPRequest:
type: object
required: [recipient, token, transaction_id]
additionalProperties: false
properties:
transaction_id:
type: string
description: ID of the OTP transaction to verify (with ot_ prefix)
example: "ot_3f8a9c7e2d1b4a6f"
recipient:
type: string
description: Phone number or bare email address that received the OTP; must match the stored transaction transport.
example: "+233241234567"
token:
type: string
description: OTP token submitted by the user
example: "847293"
VerifyOTPResponse:
type: object
required: [transaction, verification_attempt]
properties:
transaction:
$ref: '#/components/schemas/OTPTransaction'
verification_attempt:
$ref: '#/components/schemas/OTPVerificationAttempt'
LookupOTPRequest:
type: object
required: [transaction_id]
additionalProperties: false
properties:
transaction_id:
type: string
description: ID of the OTP transaction to lookup (with ot_ prefix)
example: "ot_3f8a9c7e2d1b4a6f"
LookupOTPResponse:
type: object
required: [transaction]
properties:
transaction:
$ref: '#/components/schemas/OTPTransaction'
OTPPurpose:
type: string
description: Customer action protected by the OTP. Controls safe, purpose-specific default email copy. Unknown values are rejected; use `unspecified` explicitly for a general verification request.
enum: [account_creation, account_recovery, email_verification, financial_account_verification, password_reset, payment_confirmation, payment_method_verification, payout_confirmation, phone_verification, sensitive_action, sign_in, transaction_confirmation, unspecified]
OTPTransaction:
type: object
description: OTP transaction object returned by initiate, verify, and lookup endpoints
required: [expires_at, full_message, id, initiated_at, status]
properties:
cancel_reason:
type: string
description: Omitted unless the transaction was canceled.
canceled_at:
type: string
format: date-time
description: Omitted unless the transaction was canceled.
expires_at:
type: string
format: date-time
full_message:
type: string
description: Message text with the `{token}` placeholder preserved; no generated token is returned.
example: "Your Acme Bank code is {token}."
id:
type: string
description: Unique identifier with ot_ prefix
example: "ot_3f8a9c7e2d1b4a6f"
initiated_at:
type: string
format: date-time
status:
type: string
enum: [canceled, expired, pending, pending_delivery, pending_verification, verified]
transmission:
$ref: '#/components/schemas/OTPTransmission'
OTPTransmission:
type: object
required: [recipient, sender_id]
properties:
recipient:
type: string
example: "+233241234567"
sender_id:
type: string
description: SMS sender identifier or approved email From address.
example: "Acme"
sent_at:
type: string
format: date-time
sent_via:
type: string
enum: [sms, email]
status:
type: string
enum: [accepted, delivered, failed, queued, sent, submitted]
OTPVerificationAttempt:
type: object
description: Details of a verification attempt
required: [attempted_at, id, presented_token, recipient, result]
properties:
attempted_at:
type: string
format: date-time
id:
type: string
example: "ov_9e8d7c6b5a4f3e2d"
presented_token:
type: string
description: Token submitted for this verification attempt.
recipient:
type: string
result:
type: object
required: [verdict]
properties:
detail:
type: string
description: Omitted when no detail is available.
verdict:
type: string
enum: [fail, pass]