openapi: 3.0.0 info: title: iFrame Session Create description: >- Establish a branded, PCI-compliant iFrame plugin session for recipient account capture. Requests must be signed using HMAC-SHA512 authentication. ## Authentication iFrame Session API requests are authenticated using HMAC-SHA512. **iFrame Session API credentials (provisioned by your Ingo integration manager):** | Credential | Where used | Notes | |---|---|---| | HMAC username | `Authorization` header `username` field | Ingo correlates this to your participant account on the backend | | HMAC secret | Used locally to compute the signature | Provisioned by your Ingo integration manager. Never transmit this value — store it in a secrets manager or environment variable, never in source code | No participant identifier is required in the iFrame Session request. Ingo resolves your participant account from the HMAC username on the backend automatically. **Algorithm requirement:** New integrations must use HMAC-SHA512. Legacy integrations using HMAC-SHA256 remain supported but are encouraged to upgrade. MD5 and SHA-1 are not accepted and will be rejected. See the Ingo API Authentication Guide for string-to-sign construction, body hashing requirements, and timestamp validation rules. version: 1.0.0 contact: name: Ingo Money Integrations url: https://ingomoney.com/contact tags: - name: Session Management description: Initialize and manage iFrame plugin sessions. servers: - url: https://iip-session-management-uat.ingo.money description: Sandbox - url: https://iip-session-management.ingo.money description: Production paths: /api/v1/sessions/point-in-time/plugin: post: tags: - Session Management operationId: createSession summary: Create Session description: >- Initialize a point-in-time session for mounting the IngoPay iFrame SDK. Establishes customer information for iFrame interactions, recipient verification, and tokenization processing. Supports idempotency to safely retry session initialization without creating duplicate sessions. parameters: - name: Idempotency-Key in: header required: false description: >- Unique client-generated key (V4 UUID recommended) for safely retrying a session request without creating a duplicate session. Keys remain active for 2 hours. A status 101 response is returned when the same key is reused within that window. schema: type: string maxLength: 250 example: 3f2a1b4c-9d8e-7f6a-5b4c-3d2e1f0a9b8c requestBody: required: true content: application/json: schema: type: object required: - participant_unique_id1 - recipient_information properties: participant_unique_id1: type: string maxLength: 100 description: >- Participant-assigned ID for the session request. Carry this value forward to subsequent process requests for tracking. example: 70646041-01ea-4cd6-b657-18ff88e465c7 participant_unique_id2: type: string maxLength: 100 description: >- Optional second participant-assigned ID. Can also be carried forward to process requests for tracking. example: DEF-5678 host_uri: type: string maxLength: 200 description: >- URI of the hosting application (include protocol and hostname, e.g. https://digitalpay.ingo.money). Must be explicitly whitelisted in client configuration. Defaults to the first configured parent application host domain if omitted. example: https://digitalpay.ingo.money language_locale_code: type: string maxLength: 5 description: >- IETF locale code specifying the language to use when launching the iFrame. example: en-US enum: - ar-SA - cs-CZ - da-DK - de-DE - en-GB - en-US - es-ES - es-US - fa-IR - fi-FI - fr-FR - hmn-Latn - it-IT - ja-JP - km-KH - ko-KR - nb-NO - nl-NL - pl-PL - pt-BR - ru-RU - sv-SE - tl-PH - tr-TR - vi-VN - zh-CN - zh-Hans - zh-TW recipient_information: type: object description: Client-provided recipient verification information. required: - first_name - last_name - address_line1 - city - state - zip_code properties: first_name: type: string maxLength: 150 description: Recipient first name. example: Jack last_name: type: string maxLength: 150 description: Recipient last name. example: Frost business_name: type: string maxLength: 150 description: >- Recipient business name. Required when a complete personal name (both first_name and last_name) is not provided. example: Acme Limited address_line1: type: string maxLength: 150 description: Recipient street address line 1. example: 123 Main St address_line2: type: string maxLength: 150 description: Recipient street address line 2. example: Suite 400 city: type: string maxLength: 150 description: Recipient city. example: Atlanta state: type: string maxLength: 2 description: >- Recipient state. Must be a valid two-letter US state code. example: GA zip_code: type: string maxLength: 10 description: Recipient ZIP code (formats xxxxx or xxxxx-xxxx). example: '37233' email_address: type: string maxLength: 150 description: >- Recipient email address. Required for PayPal-enabled participants. example: jack.frost@example.com phone_number: type: string maxLength: 10 description: Recipient phone number. Digits only. example: '4045551234' mobile_number: type: string maxLength: 10 description: Recipient mobile number. Digits only. example: '4045551234' open_banking: type: object description: Client-provided OpenBanking configuration. properties: mobus_customer_id: type: string maxLength: 50 description: OpenBanking Mobus Customer ID. example: '9999' example: participant_unique_id1: 70646041-01ea-4cd6-b657-18ff88e465c7 host_uri: https://digitalpay-test.ingo.money language_locale_code: en-US recipient_information: first_name: Alex last_name: Rivera business_name: Acme Limited address_line1: 100 Innovation Way city: Anytown state: GA zip_code: '37233' email_address: jack.frost@example.com phone_number: '1231231234' mobile_number: '1231231234' open_banking: mobus_customer_id: '9999' responses: '200': description: Session created successfully, or idempotent response returned. content: application/json: schema: type: object properties: status: type: integer description: >- Numeric status code. 100 = Success; 101 = Success (Idempotent — existing session returned, no new session created). example: 100 client_message: type: string description: Human-readable description of the status code. example: Success data: type: object description: Session identifiers and authorized launch URL. properties: session_identifier: type: string description: Unique identifier for the created session. example: 7830227a-ba47-4d28-9416-cad41a446db7 authorized_url: type: string description: >- Signed URL used to launch the iFrame. Must be consumed within 30 seconds of creation. example: >- https://iip-webplugin-ingo.money/session/7830227a-ba47-4d28-9416-cad41a446db7?t=637126733246949906&h=rpSb%2f%2fAeOAKjX7%2fhhOQvj9zpvwf4xeg97TuPCMtpUg0%3d authorized_url_expiration_utc: type: string description: UTC expiration timestamp for the authorized URL. example: '2019-12-10T20:14:19.763941Z' participant_unique_id1: type: string description: Transaction correlation ID echo. example: 1f271ff6-5b79-45b6-a71e-aa9d1b86c0d8 participant_unique_id2: type: string description: Customer correlation ID echo. example: '' time: type: number description: Server-side request processing time in seconds. example: 0.8 examples: success: summary: 100 Success value: status: 100 client_message: Success data: session_identifier: 7830227a-ba47-4d28-9416-cad41a446db7 authorized_url: >- https://iip-webplugin-ingo.money/session/7830227a-ba47-4d28-9416-cad41a446db7?t=637126733246949906&h=rpSb%2f%2fAeOAKjX7%2fhhOQvj9zpvwf4xeg97TuPCMtpUg0%3d authorized_url_expiration_utc: '2019-12-10T20:14:19.763941Z' participant_unique_id1: 1f271ff6-5b79-45b6-a71e-aa9d1b86c0d8 participant_unique_id2: '' time: 0.8 idempotent: summary: 101 Success - Idempotent value: status: 101 client_message: Success - Idempotent data: session_identifier: 5cf34a7d-25b6-4400-b19d-53a171d324e1 authorized_url: >- https://iip-webplugin-uat.ingo.money/session/5cf34a7d-25b6-4400-b19d-53a171d324e1?t=737135937108347861&h=%2fHdR2ZYGoNDaqmyhUO1HmoWpJRa2zNjNtFXcJsuJJww%3d authorized_url_expiration_utc: '2020-01-02T20:30:30.8347861Z' participant_unique_id1: 2639d2ce-2e74-48a4-be74-9bb90a62b40b participant_unique_id2: '' time: 0 '400': description: >- Field validation error, unauthorized host URI, or idempotency key mismatch. content: application/json: schema: type: object properties: status: type: integer description: Numeric error status code. example: 13400 client_message: type: string description: Human-readable error description. example: >- Field validation error - See data element for validation error details developer_message: type: string description: Machine-readable error identifier. example: invalid_request_fields data: type: object nullable: true description: >- For field validation errors, a map of field names to arrays of validation error messages. Null for other error types. example: participant_unique_id1: - The ParticipantUniqueId1 field is required. time: type: number description: Server-side request processing time in seconds. example: 0 examples: field-validation: summary: Field Validation Error (13400) value: status: 13400 client_message: >- Field validation error - See data element for validation error details developer_message: invalid_request_fields data: participant_unique_id1: - The ParticipantUniqueId1 field is required. time: 0 unauthorized-host: summary: Unauthorized Host URI (13412) value: status: 13412 client_message: host_uri is unauthorized developer_message: session_unauthorized_error data: null time: 0 invalid-mobus: summary: Invalid OpenBanking Customer ID (13421) value: status: 13421 client_message: Invalid MOBUS Customer Id <9999> for Participant <90018>. developer_message: invalid_mobus_customer_id data: null time: 0 idempotency-mismatch: summary: Idempotency Key Mismatch (13723) value: status: 13723 client_message: >- Idempotency Key for ParticipantId does not match the original request developer_message: invalid_idempotent_request data: null time: 0 components: securitySchemes: HmacAuth: type: http scheme: hmac-sha512 description: >- HMAC-SHA512 signed Authorization header. See the Authentication page for the complete signing guide. security: - HmacAuth: []