openapi: 3.1.0 info: title: IngoPay Webhook Events version: 1.0.0 description: > Ingo delivers webhook events to your registered HTTPS endpoint via HTTP POST. Your endpoint must return a 2xx response to acknowledge receipt. **Acceptance policy:** Accept webhooks independently of your ability to process them downstream. Accepted events can be re-processed locally without requiring Ingo to replay delivery. **Retry policy:** Non-2xx responses are retried every 60 minutes for up to 24 hours. Retry frequency, interval, and max attempts are configurable per endpoint. Use `metadata.id` as your idempotency key to prevent duplicate processing on retry. **Maintenance windows:** Contact your account coordinator to arrange webhook suspension during planned maintenance. ## Authentication Ingo requires your endpoint to authenticate inbound webhook requests. Supported mechanisms — configured by your Ingo integration manager: - **OAuth 2.0** — Ingo obtains an access token from your token endpoint before each delivery. - **Basic authentication** — username and password sent in the `Authorization` header on each request. - **Custom header** — a static value in a header of your choosing (e.g. `x-api-key`). - **Other mechanisms** (JWT, certificate-based, etc.) — discuss with your integration manager for evaluation. ## IP Whitelisting Configure your firewall to accept requests from the following IP addresses. **UAT:** 18.189.65.27, 23.253.209.42, 23.253.213.126, 23.253.22.48, 3.130.108.242, 3.134.254.69, 3.142.181.231, 104.130.74.57 **Production:** 64.88.183.84, 50.56.42.59, 50.56.46.146, 50.57.62.142 ## Event Categories - Recipient Verification (OFAC) - Recipient Payment webhooks: gateway.transaction.recipient.verification.ofac.status.suspended: post: operationId: ingopay_ofac_suspended summary: OFAC Screening — Suspended description: > An initial OFAC screening hit has suspended payment processing while the hit is verified. Subscribe to monitor compliance holds. tags: - Recipient Verification requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookOfacNoPayload' example: metadata: id: 7a6d0270-5912-4c31-8eac-3a344c419e98 topic: >- gateway.transaction.recipient.verification.ofac.status.suspended topic_description: OFAC Transaction Suspension - Initial Hit timestamp: 1629386098 version: '1' data: ancillary: participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a participant_unique_id2: 1b927134-5e70-40ff-a413-a322575a65c6 session_id: '' event: status: '1106' client_message: Success - OFAC suspended responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.verification.ofac.status.cleared: post: operationId: ingopay_ofac_cleared summary: OFAC Screening — Cleared description: > A previously suspended transaction has cleared OFAC review. Payment processing will resume. tags: - Recipient Verification requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookOfacNoPayload' example: metadata: id: 8c297f0f-d8af-477b-adcc-335e638053b2 topic: gateway.transaction.recipient.verification.ofac.status.cleared topic_description: OFAC Transaction Cleared timestamp: 1629386668 version: '1' data: ancillary: participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a participant_unique_id2: 1b927134-5e70-40ff-a413-a322575a65c6 session_id: '' event: status: '1107' client_message: Recipient Verification OFAC Cleared responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.verification.ofac.status.failure: post: operationId: ingopay_ofac_failure summary: OFAC Screening — Failure description: > The initial OFAC hit has been confirmed. The transaction will be terminated. This is a terminal event. tags: - Recipient Verification requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookOfacNoPayload' example: metadata: id: 5cba4f64-4a31-4b25-83e2-3a5cb8cb4ccf topic: gateway.transaction.recipient.verification.ofac.status.failure topic_description: OFAC Transaction Clearing Failure timestamp: 1629387787 version: '1' data: ancillary: participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a participant_unique_id2: 1b927134-5e70-40ff-a413-a322575a65c6 session_id: '' event: status: '1108' client_message: OFAC Transaction Clearing Failure responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.payment.status.check.issued: post: operationId: ingopay_check_issued summary: Check Issued description: > An Ingo-supported check transaction has been updated to check_issued status. The check_number in the event payload is required for subsequent check stop or check cancel operations. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCheckIssuedPaid' example: metadata: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 topic: gateway.transaction.recipient.payment.status.check.issued topic_description: Recipient Payment Status - Check Issued timestamp: 1629390000 version: '1' data: ancillary: notification_id: '123456789012345' participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a participant_unique_id2: 1b927134-5e70-40ff-a413-a322575a65c6 session_id: '' event: status: '100' client_message: Success check_number: '1000012345' check_amount: '250.00' responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.payment.status.check.paid: post: operationId: ingopay_check_paid summary: Check Paid description: An Ingo-supported check has been updated to check_paid status. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCheckIssuedPaid' example: metadata: id: b2c3d4e5-f6a7-8901-bcde-f01234567891 topic: gateway.transaction.recipient.payment.status.check.paid topic_description: Recipient Payment Status - Check Paid timestamp: 1629400000 version: '1' data: ancillary: notification_id: '123456789012345' participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a session_id: '' event: status: '100' client_message: Success check_number: '1000012345' check_amount: '250.00' responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.payment.status.check.canceled: post: operationId: ingopay_check_canceled summary: Check Cancellation Confirmed description: | A check cancellation has been confirmed via status report file. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCheckCanceledStopped' example: metadata: id: c3d4e5f6-a7b8-9012-cdef-012345678912 topic: gateway.transaction.recipient.payment.status.check.canceled topic_description: Recipient Payment Status - Check Cancellation Confirmed timestamp: 1629410000 version: '1' data: ancillary: notification_id: '123456789012345' participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a session_id: '' event: status: '73' client_message: 'Check Cancel: Check Not Printed' check_number: '1000012345' check_amount: '250.00' reason_code: '73' responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.payment.status.check.stopped: post: operationId: ingopay_check_stopped summary: Check Stop Confirmed description: A check stop has been confirmed via status report file. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCheckCanceledStopped' example: metadata: id: d4e5f6a7-b8c9-0123-def0-123456789013 topic: gateway.transaction.recipient.payment.status.check.stopped topic_description: Recipient Payment Status - Check Stop Confirmed timestamp: 1629420000 version: '1' data: ancillary: notification_id: '123456789012345' participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a session_id: '' event: status: '77' client_message: 'Check Stop: Client Request' check_number: '1000012345' check_amount: '250.00' reason_code: '77' responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.status.payment.check.returned: post: operationId: ingopay_check_returned summary: Check Returned (Positive Pay Exception) description: | A check transaction has been returned due to a positive pay exception. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCheckReturned' example: metadata: id: e5f6a7b8-c9d0-1234-ef01-234567890014 topic: gateway.transaction.recipient.status.payment.check.returned topic_description: Recipient Payment Status - Check Returned timestamp: 1629430000 version: '1' data: ancillary: notification_id: '123456789012345' participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a session_id: '' event: status: '1114' client_message: Payment Returned by Issuer check_number: '1000012345' check_amount: '250.00' reason_code: PP01 responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. gateway.transaction.recipient.payment.status.returned: post: operationId: ingopay_payment_returned summary: Payment Returned by Issuer description: > A previously completed payment has been returned by the account issuer. This is a terminal event. Subscribe to trigger refund or re-issuance workflows. tags: - Recipient Payment requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookPaymentReturned' example: metadata: id: d3ca0435-69b6-44ad-88ed-1413e74685bd topic: gateway.transaction.recipient.payment.status.returned topic_description: Payment Returned by Issuer timestamp: 1610654442 version: '1' data: ancillary: participant_unique_id1: 39eef189-dd96-49e4-80d3-6346240c427a participant_unique_id2: 1b927134-5e70-40ff-a413-a322575a65c6 session_id: '' event: status: '1114' client_message: Payment Returned by Issuer return_transaction_id: '567890123456789' reason_code: R03 reason_description: No Account/Unable to Locate Account responses: default: description: >- Return any 2xx status to acknowledge receipt. Ingo does not evaluate the response body. components: schemas: WebhookMetadata: type: object required: - id - topic - topic_description - timestamp - version properties: id: type: string maxLength: 50 description: > Ingo-assigned unique ID for this webhook delivery. Use as your idempotency key to prevent duplicate processing on retry. topic: type: string maxLength: 150 description: Topic name identifying the event type. topic_description: type: string maxLength: 250 description: Human-readable description of the topic. timestamp: type: integer description: Unix timestamp of the webhook delivery. version: type: string maxLength: 5 description: Payload version number. example: '1' WebhookAncillaryIngoPay: type: object required: - participant_unique_id1 properties: notification_id: type: string maxLength: 15 description: Ingo-assigned unique identifier for the original transaction. party_id: type: string maxLength: 36 nullable: true description: Ingo-assigned unique ID for a party to the transaction. tracer_token: type: string maxLength: 250 nullable: true session_id: type: string maxLength: 50 nullable: true participant_unique_id1: type: string maxLength: 100 description: >- Participant-provided unique identifier from the original transaction. participant_unique_id2: type: string maxLength: 100 nullable: true WebhookEventBase: type: object required: - status - client_message properties: status: type: string maxLength: 10 description: Numeric status code for the event. client_message: type: string maxLength: 250 attempt_count: type: integer description: >- Current attempt number. Present when event has attempt counter config. max_attempts: type: integer description: >- Maximum allowed attempts. Present when event has attempt counter config. WebhookOfacNoPayload: type: object required: - metadata - data properties: metadata: $ref: '#/components/schemas/WebhookMetadata' data: type: object required: - ancillary - event properties: ancillary: $ref: '#/components/schemas/WebhookAncillaryIngoPay' event: $ref: '#/components/schemas/WebhookEventBase' WebhookCheckIssuedPaid: type: object required: - metadata - data properties: metadata: $ref: '#/components/schemas/WebhookMetadata' data: type: object required: - ancillary - event properties: ancillary: $ref: '#/components/schemas/WebhookAncillaryIngoPay' event: allOf: - $ref: '#/components/schemas/WebhookEventBase' - type: object required: - check_number - check_amount properties: check_number: type: string maxLength: 10 check_amount: type: string maxLength: 10 WebhookCheckCanceledStopped: type: object required: - metadata - data properties: metadata: $ref: '#/components/schemas/WebhookMetadata' data: type: object required: - ancillary - event properties: ancillary: $ref: '#/components/schemas/WebhookAncillaryIngoPay' event: allOf: - $ref: '#/components/schemas/WebhookEventBase' - type: object required: - check_number - check_amount - reason_code properties: check_number: type: string maxLength: 10 check_amount: type: string maxLength: 10 reason_code: type: string maxLength: 10 WebhookCheckReturned: type: object required: - metadata - data properties: metadata: $ref: '#/components/schemas/WebhookMetadata' data: type: object required: - ancillary - event properties: ancillary: $ref: '#/components/schemas/WebhookAncillaryIngoPay' event: allOf: - $ref: '#/components/schemas/WebhookEventBase' - type: object required: - check_number - check_amount - reason_code properties: check_number: type: string maxLength: 10 check_amount: type: string maxLength: 10 reason_code: type: string maxLength: 10 WebhookPaymentReturned: type: object required: - metadata - data properties: metadata: $ref: '#/components/schemas/WebhookMetadata' data: type: object required: - ancillary - event properties: ancillary: $ref: '#/components/schemas/WebhookAncillaryIngoPay' event: allOf: - $ref: '#/components/schemas/WebhookEventBase' - type: object required: - return_transaction_id - reason_code - reason_description properties: return_transaction_id: type: string maxLength: 15 reason_code: type: string maxLength: 10 reason_description: type: string maxLength: 250