diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index c024979a..5698cbe6 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -10149,7 +10149,7 @@ webhooks: post: summary: Incoming payment webhook and approval mechanism description: | - Webhook that is called when an incoming payment is received by a customer's UMA address. + Webhook that is called when an incoming payment is received by a customer — over UMA to the customer's UMA address, or over a bank rail (e.g. a SWIFT wire to the customer's funding coordinates from `fundingPaymentInstructions`). This endpoint should be implemented by clients of the Grid API. ### Authentication @@ -10174,6 +10174,8 @@ webhooks: The Grid system will proceed or cancel the payment based on your response. For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational. + + Bank-rail incoming payments (e.g. SWIFT) are informational at every status, including PENDING: the funds have already moved interbank, so the approval mechanism and the 5-second response window do not apply. operationId: incomingPaymentWebhook tags: - Webhooks @@ -10324,7 +10326,7 @@ webhooks: '200': description: | Webhook received successfully. - For PENDING transactions, this indicates approval to proceed with the payment. + For PENDING transactions on approval-mechanism rails, this indicates approval to proceed with the payment. For bank-rail incoming payments (e.g. SWIFT) a 200 only acknowledges receipt: there is nothing to approve. If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverCustomerInfo` object. content: application/json: @@ -10335,6 +10337,7 @@ webhooks: Webhook received and will be processed asynchronously. The synchronous 200 response should be preferred where possible. This asycnhronous path should only be used in cases where the platform's architecture requires async (but still very quick) processing before approving or rejecting the payment. The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected. + Bank-rail incoming payments (e.g. SWIFT) need no approve/reject call: a 202 is treated the same as a 200 acknowledgment. '400': description: Bad request content: @@ -10350,7 +10353,9 @@ webhooks: '403': description: | Forbidden - Payment rejected by the client. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + a bank-rail incoming payment (e.g. SWIFT) cannot be rejected through + this response because the funds have already moved interbank. content: application/json: schema: @@ -10364,7 +10369,9 @@ webhooks: '422': description: | Unprocessable Entity - Additional counterparty information required. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + for bank-rail incoming payments (e.g. SWIFT) this response has no + effect on the already-received funds. content: application/json: schema: @@ -10949,6 +10956,7 @@ webhooks: ### Event types - `INTERNAL_ACCOUNT.BALANCE_UPDATED` — Fired when the balance of an internal account changes. The `data` payload contains the full internal account object. - `INTERNAL_ACCOUNT.STATUS_UPDATED` — Fired when the status of an internal account changes (e.g., `OPEN` → `FROZEN`). The `data` payload contains the full internal account object. + - `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` — Fired when the account's `fundingPaymentInstructions` change: new funding coordinates became available (e.g., a SWIFT collection account finished provisioning) or previously served coordinates were withdrawn. The `data` payload contains the full internal account object, including the current `fundingPaymentInstructions`. operationId: internalAccountStatusWebhook tags: - Webhooks @@ -11017,6 +11025,44 @@ webhooks: fundingPaymentInstructions: [] createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' + fundingInstructionsUpdated: + summary: A SWIFT collection account finished provisioning and the account gained wire coordinates + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED + timestamp: '2025-08-15T14:32:00Z' + data: + id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + type: INTERNAL_FIAT + status: ACTIVE + balance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + totalBalance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + fundingPaymentInstructions: + - accountOrWalletInfo: + accountType: SWIFT_ACCOUNT + country: SG + swiftCode: DBSSSGSG + bankName: DBS Bank + accountNumber: '8850123456' + accountHolderName: Acme Exports Pte Ltd + paymentRails: + - SWIFT + instructionsNotes: Payments are attributed automatically by the destination account; no reference code is required. + createdAt: '2025-08-01T10:00:00Z' + updatedAt: '2025-08-15T14:32:00Z' responses: '200': description: | @@ -14532,6 +14578,7 @@ components: - SGD_ACCOUNT - THB_ACCOUNT - VND_ACCOUNT + - SWIFT_ACCOUNT - SPARK_WALLET - LIGHTNING - SOLANA_WALLET @@ -16891,6 +16938,7 @@ components: example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' SwiftAccountInfoBase: type: object + description: 'At least one of accountNumber or iban is always present: IBAN-only corridors (e.g. BR, GB) use iban, other corridors use accountNumber, and both appear when the bank exposes both identifiers for the same account.' required: - accountType - swiftCode @@ -16960,11 +17008,23 @@ components: - $ref: '#/components/schemas/SwiftAccountInfo' - type: object required: - - reference + - accountHolderName properties: + accountHolderName: + type: string + description: The name of the account holder as it must appear on the wire. Remitting banks match this against the beneficiary name field, so payers should copy it exactly. + example: Acme Exports Pte Ltd + minLength: 1 + maxLength: 255 + bankAddress: + type: string + description: The address of the bank holding the account, when known. + example: 12 Marina Boulevard, Singapore 018982 + minLength: 1 + maxLength: 1024 reference: type: string - description: Unique reference code that must be included with the payment to properly credit it + description: Reference code to include with the payment when present. SWIFT payments are attributed by the destination account number/IBAN, so this account type typically requires no reference. example: UMA-Q12345-REF CnyAccountInfoBase: type: object @@ -21519,7 +21579,8 @@ components: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED - description: Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. COMPLIANCE_REJECTED means compliance blocked the incoming funds. If the transaction is not in a failed state, this field is omitted. + - COLLECTION_FAILED + description: Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. IncomingTransaction: title: Incoming Transaction allOf: @@ -25260,6 +25321,7 @@ components: - EXTERNAL_ACCOUNT.STATUS_UPDATED - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED - INVITATION.CLAIMED - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED @@ -25452,6 +25514,7 @@ components: enum: - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED ExternalAccountStatusWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' diff --git a/openapi.yaml b/openapi.yaml index c024979a..5698cbe6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -10149,7 +10149,7 @@ webhooks: post: summary: Incoming payment webhook and approval mechanism description: | - Webhook that is called when an incoming payment is received by a customer's UMA address. + Webhook that is called when an incoming payment is received by a customer — over UMA to the customer's UMA address, or over a bank rail (e.g. a SWIFT wire to the customer's funding coordinates from `fundingPaymentInstructions`). This endpoint should be implemented by clients of the Grid API. ### Authentication @@ -10174,6 +10174,8 @@ webhooks: The Grid system will proceed or cancel the payment based on your response. For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational. + + Bank-rail incoming payments (e.g. SWIFT) are informational at every status, including PENDING: the funds have already moved interbank, so the approval mechanism and the 5-second response window do not apply. operationId: incomingPaymentWebhook tags: - Webhooks @@ -10324,7 +10326,7 @@ webhooks: '200': description: | Webhook received successfully. - For PENDING transactions, this indicates approval to proceed with the payment. + For PENDING transactions on approval-mechanism rails, this indicates approval to proceed with the payment. For bank-rail incoming payments (e.g. SWIFT) a 200 only acknowledges receipt: there is nothing to approve. If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverCustomerInfo` object. content: application/json: @@ -10335,6 +10337,7 @@ webhooks: Webhook received and will be processed asynchronously. The synchronous 200 response should be preferred where possible. This asycnhronous path should only be used in cases where the platform's architecture requires async (but still very quick) processing before approving or rejecting the payment. The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected. + Bank-rail incoming payments (e.g. SWIFT) need no approve/reject call: a 202 is treated the same as a 200 acknowledgment. '400': description: Bad request content: @@ -10350,7 +10353,9 @@ webhooks: '403': description: | Forbidden - Payment rejected by the client. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + a bank-rail incoming payment (e.g. SWIFT) cannot be rejected through + this response because the funds have already moved interbank. content: application/json: schema: @@ -10364,7 +10369,9 @@ webhooks: '422': description: | Unprocessable Entity - Additional counterparty information required. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + for bank-rail incoming payments (e.g. SWIFT) this response has no + effect on the already-received funds. content: application/json: schema: @@ -10949,6 +10956,7 @@ webhooks: ### Event types - `INTERNAL_ACCOUNT.BALANCE_UPDATED` — Fired when the balance of an internal account changes. The `data` payload contains the full internal account object. - `INTERNAL_ACCOUNT.STATUS_UPDATED` — Fired when the status of an internal account changes (e.g., `OPEN` → `FROZEN`). The `data` payload contains the full internal account object. + - `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` — Fired when the account's `fundingPaymentInstructions` change: new funding coordinates became available (e.g., a SWIFT collection account finished provisioning) or previously served coordinates were withdrawn. The `data` payload contains the full internal account object, including the current `fundingPaymentInstructions`. operationId: internalAccountStatusWebhook tags: - Webhooks @@ -11017,6 +11025,44 @@ webhooks: fundingPaymentInstructions: [] createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' + fundingInstructionsUpdated: + summary: A SWIFT collection account finished provisioning and the account gained wire coordinates + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED + timestamp: '2025-08-15T14:32:00Z' + data: + id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + type: INTERNAL_FIAT + status: ACTIVE + balance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + totalBalance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + fundingPaymentInstructions: + - accountOrWalletInfo: + accountType: SWIFT_ACCOUNT + country: SG + swiftCode: DBSSSGSG + bankName: DBS Bank + accountNumber: '8850123456' + accountHolderName: Acme Exports Pte Ltd + paymentRails: + - SWIFT + instructionsNotes: Payments are attributed automatically by the destination account; no reference code is required. + createdAt: '2025-08-01T10:00:00Z' + updatedAt: '2025-08-15T14:32:00Z' responses: '200': description: | @@ -14532,6 +14578,7 @@ components: - SGD_ACCOUNT - THB_ACCOUNT - VND_ACCOUNT + - SWIFT_ACCOUNT - SPARK_WALLET - LIGHTNING - SOLANA_WALLET @@ -16891,6 +16938,7 @@ components: example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' SwiftAccountInfoBase: type: object + description: 'At least one of accountNumber or iban is always present: IBAN-only corridors (e.g. BR, GB) use iban, other corridors use accountNumber, and both appear when the bank exposes both identifiers for the same account.' required: - accountType - swiftCode @@ -16960,11 +17008,23 @@ components: - $ref: '#/components/schemas/SwiftAccountInfo' - type: object required: - - reference + - accountHolderName properties: + accountHolderName: + type: string + description: The name of the account holder as it must appear on the wire. Remitting banks match this against the beneficiary name field, so payers should copy it exactly. + example: Acme Exports Pte Ltd + minLength: 1 + maxLength: 255 + bankAddress: + type: string + description: The address of the bank holding the account, when known. + example: 12 Marina Boulevard, Singapore 018982 + minLength: 1 + maxLength: 1024 reference: type: string - description: Unique reference code that must be included with the payment to properly credit it + description: Reference code to include with the payment when present. SWIFT payments are attributed by the destination account number/IBAN, so this account type typically requires no reference. example: UMA-Q12345-REF CnyAccountInfoBase: type: object @@ -21519,7 +21579,8 @@ components: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED - description: Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. COMPLIANCE_REJECTED means compliance blocked the incoming funds. If the transaction is not in a failed state, this field is omitted. + - COLLECTION_FAILED + description: Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. IncomingTransaction: title: Incoming Transaction allOf: @@ -25260,6 +25321,7 @@ components: - EXTERNAL_ACCOUNT.STATUS_UPDATED - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED - INVITATION.CLAIMED - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED @@ -25452,6 +25514,7 @@ components: enum: - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED ExternalAccountStatusWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' diff --git a/openapi/components/schemas/common/PaymentAccountType.yaml b/openapi/components/schemas/common/PaymentAccountType.yaml index 343aae35..d7ac415c 100644 --- a/openapi/components/schemas/common/PaymentAccountType.yaml +++ b/openapi/components/schemas/common/PaymentAccountType.yaml @@ -18,6 +18,7 @@ enum: - SGD_ACCOUNT - THB_ACCOUNT - VND_ACCOUNT + - SWIFT_ACCOUNT - SPARK_WALLET - LIGHTNING - SOLANA_WALLET diff --git a/openapi/components/schemas/common/PaymentSwiftAccountInfo.yaml b/openapi/components/schemas/common/PaymentSwiftAccountInfo.yaml index c2c1dad8..126a48be 100644 --- a/openapi/components/schemas/common/PaymentSwiftAccountInfo.yaml +++ b/openapi/components/schemas/common/PaymentSwiftAccountInfo.yaml @@ -4,10 +4,27 @@ allOf: - $ref: ./SwiftAccountInfo.yaml - type: object required: - - reference + - accountHolderName properties: + accountHolderName: + type: string + description: >- + The name of the account holder as it must appear on the wire. + Remitting banks match this against the beneficiary name field, + so payers should copy it exactly. + example: Acme Exports Pte Ltd + minLength: 1 + maxLength: 255 + bankAddress: + type: string + description: The address of the bank holding the account, when known. + example: 12 Marina Boulevard, Singapore 018982 + minLength: 1 + maxLength: 1024 reference: type: string - description: Unique reference code that must be included with the payment to - properly credit it + description: >- + Reference code to include with the payment when present. SWIFT + payments are attributed by the destination account number/IBAN, + so this account type typically requires no reference. example: UMA-Q12345-REF diff --git a/openapi/components/schemas/common/SwiftAccountInfoBase.yaml b/openapi/components/schemas/common/SwiftAccountInfoBase.yaml index d8550a5e..925f43d0 100644 --- a/openapi/components/schemas/common/SwiftAccountInfoBase.yaml +++ b/openapi/components/schemas/common/SwiftAccountInfoBase.yaml @@ -1,4 +1,9 @@ type: object +description: >- + At least one of accountNumber or iban is always present: IBAN-only + corridors (e.g. BR, GB) use iban, other corridors use accountNumber, + and both appear when the bank exposes both identifiers for the same + account. required: - accountType - swiftCode diff --git a/openapi/components/schemas/transactions/IncomingTransactionFailureReason.yaml b/openapi/components/schemas/transactions/IncomingTransactionFailureReason.yaml index f5a57642..5158d7f4 100644 --- a/openapi/components/schemas/transactions/IncomingTransactionFailureReason.yaml +++ b/openapi/components/schemas/transactions/IncomingTransactionFailureReason.yaml @@ -9,8 +9,14 @@ enum: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED + - COLLECTION_FAILED description: >- Reason for failure of an incoming transaction. This is used to provide more - context on why a transaction failed. COMPLIANCE_REJECTED means compliance - blocked the incoming funds. If the transaction is not in a failed state, - this field is omitted. + context on why a transaction failed. If the transaction is not in a failed + state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked + the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection + deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most + commonly a compliance-screening rejection or an unresolved request for + information, on either the collection provider's side or Grid's. Failed + collections are returned to the sender per the collection provider's + process. diff --git a/openapi/components/schemas/webhooks/InternalAccountStatusWebhook.yaml b/openapi/components/schemas/webhooks/InternalAccountStatusWebhook.yaml index a6fdfd12..eed81041 100644 --- a/openapi/components/schemas/webhooks/InternalAccountStatusWebhook.yaml +++ b/openapi/components/schemas/webhooks/InternalAccountStatusWebhook.yaml @@ -11,3 +11,4 @@ allOf: enum: - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED diff --git a/openapi/components/schemas/webhooks/WebhookType.yaml b/openapi/components/schemas/webhooks/WebhookType.yaml index d27f1b6e..56c09025 100644 --- a/openapi/components/schemas/webhooks/WebhookType.yaml +++ b/openapi/components/schemas/webhooks/WebhookType.yaml @@ -29,6 +29,7 @@ enum: - EXTERNAL_ACCOUNT.STATUS_UPDATED - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED + - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED - INVITATION.CLAIMED - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED diff --git a/openapi/webhooks/incoming-payment.yaml b/openapi/webhooks/incoming-payment.yaml index 79f7f9c0..bd7d19d6 100644 --- a/openapi/webhooks/incoming-payment.yaml +++ b/openapi/webhooks/incoming-payment.yaml @@ -1,8 +1,10 @@ post: summary: Incoming payment webhook and approval mechanism description: > - Webhook that is called when an incoming payment is received by a customer's UMA - address. + Webhook that is called when an incoming payment is received by a customer — + over UMA to the customer's UMA address, or over a bank rail (e.g. a SWIFT + wire to the customer's funding coordinates from + `fundingPaymentInstructions`). This endpoint should be implemented by clients of the Grid API. @@ -55,6 +57,11 @@ post: For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational. + + + Bank-rail incoming payments (e.g. SWIFT) are informational at every + status, including PENDING: the funds have already moved interbank, so the + approval mechanism and the 5-second response window do not apply. operationId: incomingPaymentWebhook tags: - Webhooks @@ -206,8 +213,10 @@ post: description: > Webhook received successfully. - For PENDING transactions, this indicates approval to proceed with the - payment. + For PENDING transactions on approval-mechanism rails, this indicates + approval to proceed with the payment. For bank-rail incoming payments + (e.g. SWIFT) a 200 only acknowledges receipt: there is nothing to + approve. If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in @@ -229,6 +238,9 @@ post: The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected. + + Bank-rail incoming payments (e.g. SWIFT) need no approve/reject call: a + 202 is treated the same as a 200 acknowledgment. '400': description: Bad request content: @@ -244,7 +256,9 @@ post: '403': description: | Forbidden - Payment rejected by the client. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + a bank-rail incoming payment (e.g. SWIFT) cannot be rejected through + this response because the funds have already moved interbank. content: application/json: schema: @@ -258,7 +272,9 @@ post: '422': description: | Unprocessable Entity - Additional counterparty information required. - Only applicable for PENDING transactions. + Only applicable for PENDING transactions on approval-mechanism rails; + for bank-rail incoming payments (e.g. SWIFT) this response has no + effect on the already-received funds. content: application/json: schema: diff --git a/openapi/webhooks/internal-account-status.yaml b/openapi/webhooks/internal-account-status.yaml index 6078386f..90a26ee2 100644 --- a/openapi/webhooks/internal-account-status.yaml +++ b/openapi/webhooks/internal-account-status.yaml @@ -38,6 +38,13 @@ post: account changes (e.g., `OPEN` → `FROZEN`). The `data` payload contains the full internal account object. + - `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` — Fired when the + account's `fundingPaymentInstructions` change: new funding coordinates + became available (e.g., a SWIFT collection account finished provisioning) + or previously served coordinates were withdrawn. The `data` payload + contains the full internal account object, including the current + `fundingPaymentInstructions`. + operationId: internalAccountStatusWebhook tags: @@ -107,6 +114,44 @@ post: fundingPaymentInstructions: [] createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' + fundingInstructionsUpdated: + summary: A SWIFT collection account finished provisioning and the account gained wire coordinates + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED + timestamp: '2025-08-15T14:32:00Z' + data: + id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + type: INTERNAL_FIAT + status: ACTIVE + balance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + totalBalance: + amount: 10000 + currency: + code: USD + name: United States Dollar + symbol: $ + decimals: 2 + fundingPaymentInstructions: + - accountOrWalletInfo: + accountType: SWIFT_ACCOUNT + country: SG + swiftCode: DBSSSGSG + bankName: DBS Bank + accountNumber: '8850123456' + accountHolderName: Acme Exports Pte Ltd + paymentRails: + - SWIFT + instructionsNotes: Payments are attributed automatically by the destination account; no reference code is required. + createdAt: '2025-08-01T10:00:00Z' + updatedAt: '2025-08-15T14:32:00Z' responses: '200': description: >