From 8ad3ce8ea496bca83f6dd3f5ba347ff37b44376c Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Wed, 18 Feb 2026 17:02:25 -0800 Subject: [PATCH] feat: fixing transaction schema --- .stainless/stainless.yml | 24 +-- mintlify/openapi.yaml | 196 ++++++++++-------- openapi.yaml | 196 ++++++++++-------- .../transactions/IncomingTransaction.yaml | 5 + .../transactions/OutgoingTransaction.yaml | 6 +- .../transactions/TransactionOneOf.yaml | 10 + .../transactions/TransactionStatus.yaml | 16 +- openapi/paths/transactions/transactions.yaml | 2 +- .../transactions_{transactionId}.yaml | 2 +- openapi/paths/transfers/transfer_in.yaml | 2 +- openapi/paths/transfers/transfer_out.yaml | 2 +- 11 files changed, 281 insertions(+), 180 deletions(-) create mode 100644 openapi/components/schemas/transactions/TransactionOneOf.yaml diff --git a/.stainless/stainless.yml b/.stainless/stainless.yml index d6f56b6f..a1586e41 100644 --- a/.stainless/stainless.yml +++ b/.stainless/stainless.yml @@ -417,18 +417,18 @@ openapi: - "$.components.schemas.UmaAddressTransactionDestination.allOf[0]" keys: [ "$ref" ] - # # ── beneficiaryType: beneficiary schemas ── - # - command: remove - # reason: >- - # Remove inline beneficiaryType enums from beneficiary allOf variants - # to avoid conflicting types with BaseBeneficiary which defines - # beneficiaryType via a shared $ref enum - # args: - # target: - # - "$.components.schemas.IndividualBeneficiary.allOf[1].properties" - # - "$.components.schemas.BusinessBeneficiary.allOf[1].properties" - # keys: [ "beneficiaryType" ] - # ── customerType: remove from base schemas ── + # ── type: transaction base schema ── + - command: remove + reason: >- + Remove inline type enum from Transaction base schema to avoid + conflicting types when allOf merges with IncomingTransaction and + OutgoingTransaction which define type as single-value enums + args: + target: + - "$.components.schemas.Transaction.properties" + keys: [ "type" ] + + # ── beneficiaryType: beneficiary schemas ── - command: remove reason: >- Remove customerType $ref from base schemas so the inline single-value diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 60017431..73824427 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -1304,7 +1304,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '400': description: Bad request - Invalid parameters content: @@ -1398,7 +1398,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '400': description: Bad request - Invalid parameters content: @@ -2062,7 +2062,7 @@ paths: type: array description: List of transactions matching the criteria items: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' hasMore: type: boolean description: Indicates if more results are available beyond this page @@ -2112,7 +2112,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '401': description: Unauthorized content: @@ -5838,6 +5838,32 @@ components: Optional Plaid account ID if the customer selected a specific account. If not provided, the default account will be used. example: plaid_account_id_123 + IncomingTransaction: + allOf: + - $ref: '#/components/schemas/Transaction' + - type: object + required: + - type + - receivedAmount + properties: + type: + type: string + enum: + - INCOMING + source: + $ref: '#/components/schemas/TransactionSourceOneOf' + receivedAmount: + $ref: '#/components/schemas/CurrencyAmount' + description: Amount received in the recipient's currency + reconciliationInstructions: + $ref: '#/components/schemas/ReconciliationInstructions' + description: Included for all transactions except those with "CREATED" status + rateDetails: + $ref: '#/components/schemas/IncomingRateDetails' + description: Details about the rate and fees for the transaction. + failureReason: + $ref: '#/components/schemas/IncomingTransactionFailureReason' + description: If the transaction failed, this field provides the reason for failure. Transaction: type: object required: @@ -5961,81 +5987,6 @@ components: mapping: ACCOUNT: '#/components/schemas/AccountTransactionSource' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource' - ReconciliationInstructions: - type: object - required: - - reference - properties: - reference: - type: string - description: Unique reference code that must be included with the payment to match it with the correct incoming transaction - example: UMA-Q12345-REF - IncomingRateDetails: - description: Details about the rate and fees for an incoming transaction. - type: object - required: - - gridApiMultiplier - - gridApiFixedFee - - gridApiVariableFeeRate - - gridApiVariableFeeAmount - properties: - gridApiMultiplier: - type: number - format: double - description: The underlying multiplier from the mSATS to the receiving currency, including variable fees. - exclusiveMinimum: 0 - example: 0.925 - gridApiFixedFee: - type: integer - format: int64 - description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). - minimum: 0 - example: 10 - gridApiVariableFeeRate: - type: number - format: double - description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. - exclusiveMinimum: 0 - example: 0.003 - gridApiVariableFeeAmount: - type: number - format: int64 - description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. - minimum: 0 - example: 30 - IncomingTransactionFailureReason: - type: string - enum: - - LNURLP_FAILED - - PAY_REQUEST_FAILED - - PAYMENT_APPROVAL_WEBHOOK_ERROR - - PAYMENT_APPROVAL_TIMED_OUT - - OFFRAMP_FAILED - - MISSING_MANDATORY_PAYEE_DATA - - QUOTE_EXPIRED - - QUOTE_EXECUTION_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. - IncomingTransaction: - allOf: - - $ref: '#/components/schemas/Transaction' - - type: object - required: - - receivedAmount - properties: - source: - $ref: '#/components/schemas/TransactionSourceOneOf' - receivedAmount: - $ref: '#/components/schemas/CurrencyAmount' - description: Amount received in the recipient's currency - reconciliationInstructions: - $ref: '#/components/schemas/ReconciliationInstructions' - description: Included for all transactions except those with "CREATED" status - rateDetails: - $ref: '#/components/schemas/IncomingRateDetails' - description: Details about the rate and fees for the transaction. - failureReason: - $ref: '#/components/schemas/IncomingTransactionFailureReason' - description: If the transaction failed, this field provides the reason for failure. Refund: type: object required: @@ -6118,10 +6069,14 @@ components: - $ref: '#/components/schemas/Transaction' - type: object required: + - type - sentAmount - - paymentInstructions - source properties: + type: + type: string + enum: + - OUTGOING source: $ref: '#/components/schemas/TransactionSourceOneOf' sentAmount: @@ -6174,12 +6129,26 @@ components: - CREATED - PENDING - PROCESSING + - SENT - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED - description: Status of a payment transaction + description: | + Status of a payment transaction. + + | Status | Description | + |--------|-------------| + | `CREATED` | Initial lookup has been created | + | `PENDING` | Quote has been created | + | `PROCESSING` | Funding has been received and payment initiated | + | `SENT` | Cross border settlement has been initiated | + | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | + | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | + | `FAILED` | An error occurred during payment | + | `REFUNDED` | Payment was unable to complete and refunded | + | `EXPIRED` | Quote has expired | AccountTransactionDestination: allOf: - $ref: '#/components/schemas/BaseTransactionDestination' @@ -6256,6 +6225,71 @@ components: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: DE + ReconciliationInstructions: + type: object + required: + - reference + properties: + reference: + type: string + description: Unique reference code that must be included with the payment to match it with the correct incoming transaction + example: UMA-Q12345-REF + IncomingRateDetails: + description: Details about the rate and fees for an incoming transaction. + type: object + required: + - gridApiMultiplier + - gridApiFixedFee + - gridApiVariableFeeRate + - gridApiVariableFeeAmount + properties: + gridApiMultiplier: + type: number + format: double + description: The underlying multiplier from the mSATS to the receiving currency, including variable fees. + exclusiveMinimum: 0 + example: 0.925 + gridApiFixedFee: + type: integer + format: int64 + description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). + minimum: 0 + example: 10 + gridApiVariableFeeRate: + type: number + format: double + description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. + exclusiveMinimum: 0 + example: 0.003 + gridApiVariableFeeAmount: + type: number + format: int64 + description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. + minimum: 0 + example: 30 + IncomingTransactionFailureReason: + type: string + enum: + - LNURLP_FAILED + - PAY_REQUEST_FAILED + - PAYMENT_APPROVAL_WEBHOOK_ERROR + - PAYMENT_APPROVAL_TIMED_OUT + - OFFRAMP_FAILED + - MISSING_MANDATORY_PAYEE_DATA + - QUOTE_EXPIRED + - QUOTE_EXECUTION_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. + TransactionOneOf: + oneOf: + - title: Incoming Transaction + $ref: '#/components/schemas/IncomingTransaction' + - title: Outgoing Transaction + $ref: '#/components/schemas/OutgoingTransaction' + discriminator: + propertyName: type + mapping: + INCOMING: '#/components/schemas/IncomingTransaction' + OUTGOING: '#/components/schemas/OutgoingTransaction' CurrencyPreference: type: object required: diff --git a/openapi.yaml b/openapi.yaml index 60017431..73824427 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1304,7 +1304,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '400': description: Bad request - Invalid parameters content: @@ -1398,7 +1398,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '400': description: Bad request - Invalid parameters content: @@ -2062,7 +2062,7 @@ paths: type: array description: List of transactions matching the criteria items: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' hasMore: type: boolean description: Indicates if more results are available beyond this page @@ -2112,7 +2112,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Transaction' + $ref: '#/components/schemas/TransactionOneOf' '401': description: Unauthorized content: @@ -5838,6 +5838,32 @@ components: Optional Plaid account ID if the customer selected a specific account. If not provided, the default account will be used. example: plaid_account_id_123 + IncomingTransaction: + allOf: + - $ref: '#/components/schemas/Transaction' + - type: object + required: + - type + - receivedAmount + properties: + type: + type: string + enum: + - INCOMING + source: + $ref: '#/components/schemas/TransactionSourceOneOf' + receivedAmount: + $ref: '#/components/schemas/CurrencyAmount' + description: Amount received in the recipient's currency + reconciliationInstructions: + $ref: '#/components/schemas/ReconciliationInstructions' + description: Included for all transactions except those with "CREATED" status + rateDetails: + $ref: '#/components/schemas/IncomingRateDetails' + description: Details about the rate and fees for the transaction. + failureReason: + $ref: '#/components/schemas/IncomingTransactionFailureReason' + description: If the transaction failed, this field provides the reason for failure. Transaction: type: object required: @@ -5961,81 +5987,6 @@ components: mapping: ACCOUNT: '#/components/schemas/AccountTransactionSource' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource' - ReconciliationInstructions: - type: object - required: - - reference - properties: - reference: - type: string - description: Unique reference code that must be included with the payment to match it with the correct incoming transaction - example: UMA-Q12345-REF - IncomingRateDetails: - description: Details about the rate and fees for an incoming transaction. - type: object - required: - - gridApiMultiplier - - gridApiFixedFee - - gridApiVariableFeeRate - - gridApiVariableFeeAmount - properties: - gridApiMultiplier: - type: number - format: double - description: The underlying multiplier from the mSATS to the receiving currency, including variable fees. - exclusiveMinimum: 0 - example: 0.925 - gridApiFixedFee: - type: integer - format: int64 - description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). - minimum: 0 - example: 10 - gridApiVariableFeeRate: - type: number - format: double - description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. - exclusiveMinimum: 0 - example: 0.003 - gridApiVariableFeeAmount: - type: number - format: int64 - description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. - minimum: 0 - example: 30 - IncomingTransactionFailureReason: - type: string - enum: - - LNURLP_FAILED - - PAY_REQUEST_FAILED - - PAYMENT_APPROVAL_WEBHOOK_ERROR - - PAYMENT_APPROVAL_TIMED_OUT - - OFFRAMP_FAILED - - MISSING_MANDATORY_PAYEE_DATA - - QUOTE_EXPIRED - - QUOTE_EXECUTION_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. - IncomingTransaction: - allOf: - - $ref: '#/components/schemas/Transaction' - - type: object - required: - - receivedAmount - properties: - source: - $ref: '#/components/schemas/TransactionSourceOneOf' - receivedAmount: - $ref: '#/components/schemas/CurrencyAmount' - description: Amount received in the recipient's currency - reconciliationInstructions: - $ref: '#/components/schemas/ReconciliationInstructions' - description: Included for all transactions except those with "CREATED" status - rateDetails: - $ref: '#/components/schemas/IncomingRateDetails' - description: Details about the rate and fees for the transaction. - failureReason: - $ref: '#/components/schemas/IncomingTransactionFailureReason' - description: If the transaction failed, this field provides the reason for failure. Refund: type: object required: @@ -6118,10 +6069,14 @@ components: - $ref: '#/components/schemas/Transaction' - type: object required: + - type - sentAmount - - paymentInstructions - source properties: + type: + type: string + enum: + - OUTGOING source: $ref: '#/components/schemas/TransactionSourceOneOf' sentAmount: @@ -6174,12 +6129,26 @@ components: - CREATED - PENDING - PROCESSING + - SENT - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED - description: Status of a payment transaction + description: | + Status of a payment transaction. + + | Status | Description | + |--------|-------------| + | `CREATED` | Initial lookup has been created | + | `PENDING` | Quote has been created | + | `PROCESSING` | Funding has been received and payment initiated | + | `SENT` | Cross border settlement has been initiated | + | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | + | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | + | `FAILED` | An error occurred during payment | + | `REFUNDED` | Payment was unable to complete and refunded | + | `EXPIRED` | Quote has expired | AccountTransactionDestination: allOf: - $ref: '#/components/schemas/BaseTransactionDestination' @@ -6256,6 +6225,71 @@ components: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: DE + ReconciliationInstructions: + type: object + required: + - reference + properties: + reference: + type: string + description: Unique reference code that must be included with the payment to match it with the correct incoming transaction + example: UMA-Q12345-REF + IncomingRateDetails: + description: Details about the rate and fees for an incoming transaction. + type: object + required: + - gridApiMultiplier + - gridApiFixedFee + - gridApiVariableFeeRate + - gridApiVariableFeeAmount + properties: + gridApiMultiplier: + type: number + format: double + description: The underlying multiplier from the mSATS to the receiving currency, including variable fees. + exclusiveMinimum: 0 + example: 0.925 + gridApiFixedFee: + type: integer + format: int64 + description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). + minimum: 0 + example: 10 + gridApiVariableFeeRate: + type: number + format: double + description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount. + exclusiveMinimum: 0 + example: 0.003 + gridApiVariableFeeAmount: + type: number + format: int64 + description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. + minimum: 0 + example: 30 + IncomingTransactionFailureReason: + type: string + enum: + - LNURLP_FAILED + - PAY_REQUEST_FAILED + - PAYMENT_APPROVAL_WEBHOOK_ERROR + - PAYMENT_APPROVAL_TIMED_OUT + - OFFRAMP_FAILED + - MISSING_MANDATORY_PAYEE_DATA + - QUOTE_EXPIRED + - QUOTE_EXECUTION_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. + TransactionOneOf: + oneOf: + - title: Incoming Transaction + $ref: '#/components/schemas/IncomingTransaction' + - title: Outgoing Transaction + $ref: '#/components/schemas/OutgoingTransaction' + discriminator: + propertyName: type + mapping: + INCOMING: '#/components/schemas/IncomingTransaction' + OUTGOING: '#/components/schemas/OutgoingTransaction' CurrencyPreference: type: object required: diff --git a/openapi/components/schemas/transactions/IncomingTransaction.yaml b/openapi/components/schemas/transactions/IncomingTransaction.yaml index 36e6db79..e5a89991 100644 --- a/openapi/components/schemas/transactions/IncomingTransaction.yaml +++ b/openapi/components/schemas/transactions/IncomingTransaction.yaml @@ -2,8 +2,13 @@ allOf: - $ref: ./Transaction.yaml - type: object required: + - type - receivedAmount properties: + type: + type: string + enum: + - INCOMING source: $ref: ./TransactionSourceOneOf.yaml receivedAmount: diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index 69539cab..385e3277 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -2,10 +2,14 @@ allOf: - $ref: ./Transaction.yaml - type: object required: + - type - sentAmount - - paymentInstructions - source properties: + type: + type: string + enum: + - OUTGOING source: $ref: ./TransactionSourceOneOf.yaml sentAmount: diff --git a/openapi/components/schemas/transactions/TransactionOneOf.yaml b/openapi/components/schemas/transactions/TransactionOneOf.yaml new file mode 100644 index 00000000..e137ccbf --- /dev/null +++ b/openapi/components/schemas/transactions/TransactionOneOf.yaml @@ -0,0 +1,10 @@ +oneOf: + - title: Incoming Transaction + $ref: ./IncomingTransaction.yaml + - title: Outgoing Transaction + $ref: ./OutgoingTransaction.yaml +discriminator: + propertyName: type + mapping: + INCOMING: ./IncomingTransaction.yaml + OUTGOING: ./OutgoingTransaction.yaml diff --git a/openapi/components/schemas/transactions/TransactionStatus.yaml b/openapi/components/schemas/transactions/TransactionStatus.yaml index 67619ca8..ac7d0069 100644 --- a/openapi/components/schemas/transactions/TransactionStatus.yaml +++ b/openapi/components/schemas/transactions/TransactionStatus.yaml @@ -3,9 +3,23 @@ enum: - CREATED - PENDING - PROCESSING + - SENT - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED -description: Status of a payment transaction +description: | + Status of a payment transaction. + + | Status | Description | + |--------|-------------| + | `CREATED` | Initial lookup has been created | + | `PENDING` | Quote has been created | + | `PROCESSING` | Funding has been received and payment initiated | + | `SENT` | Cross border settlement has been initiated | + | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | + | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | + | `FAILED` | An error occurred during payment | + | `REFUNDED` | Payment was unable to complete and refunded | + | `EXPIRED` | Quote has expired | diff --git a/openapi/paths/transactions/transactions.yaml b/openapi/paths/transactions/transactions.yaml index a2bf6fc3..af6dac8a 100644 --- a/openapi/paths/transactions/transactions.yaml +++ b/openapi/paths/transactions/transactions.yaml @@ -106,7 +106,7 @@ get: type: array description: List of transactions matching the criteria items: - $ref: ../../components/schemas/transactions/Transaction.yaml + $ref: ../../components/schemas/transactions/TransactionOneOf.yaml hasMore: type: boolean description: Indicates if more results are available beyond this page diff --git a/openapi/paths/transactions/transactions_{transactionId}.yaml b/openapi/paths/transactions/transactions_{transactionId}.yaml index aafdec0a..2ecfbf6e 100644 --- a/openapi/paths/transactions/transactions_{transactionId}.yaml +++ b/openapi/paths/transactions/transactions_{transactionId}.yaml @@ -19,7 +19,7 @@ get: content: application/json: schema: - $ref: ../../components/schemas/transactions/Transaction.yaml + $ref: ../../components/schemas/transactions/TransactionOneOf.yaml '401': description: Unauthorized content: diff --git a/openapi/paths/transfers/transfer_in.yaml b/openapi/paths/transfers/transfer_in.yaml index 682285e0..c55436e5 100644 --- a/openapi/paths/transfers/transfer_in.yaml +++ b/openapi/paths/transfers/transfer_in.yaml @@ -71,7 +71,7 @@ post: content: application/json: schema: - $ref: ../../components/schemas/transactions/Transaction.yaml + $ref: ../../components/schemas/transactions/TransactionOneOf.yaml '400': description: Bad request - Invalid parameters content: diff --git a/openapi/paths/transfers/transfer_out.yaml b/openapi/paths/transfers/transfer_out.yaml index d9785527..31ee21bc 100644 --- a/openapi/paths/transfers/transfer_out.yaml +++ b/openapi/paths/transfers/transfer_out.yaml @@ -69,7 +69,7 @@ post: content: application/json: schema: - $ref: ../../components/schemas/transactions/Transaction.yaml + $ref: ../../components/schemas/transactions/TransactionOneOf.yaml '400': description: Bad request - Invalid parameters content: