openapi: 3.1.1 info: title: Coinbase Commerce API description: API for processing payments on the PaymentEscrow smart contract protocol. version: v0.0.1 tags: - name: Payments description: >- Endpoints focused on handling payment transactions. This includes operations for authorizing funds without immediate capture, and capturing previously authorized funds directly via the PaymentEscrow smart contract protocol. The endpoints help ensure secure and controlled payment processing, including verifying signatures, and updating payment statuses. - name: Rewards description: >- Endpoints for managing reward operations. These endpoints allow you to independently allocate, distribute, send, and deallocate rewards on previously successful payment operations. - name: Campaigns description: >- Endpoints for managing reward campaigns. Create and manage campaigns that integrate with the Flywheel smart contract to provide reward functionality. Campaigns allow merchants to define reward structures with customizable parameters including reward percentages and maximum limits. - name: coinbase.engine.operator_api.v1.OperatorApiService paths: /api/v1/campaigns: post: summary: Create campaign description: Create a new campaign and deploy it onchain operationId: OperatorApiService_PostCampaign responses: '200': description: A successful response. content: application/json: schema: type: object properties: campaignAddress: type: string description: The deployed campaign contract address title: Campaign Address examples: - '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' required: - campaignAddress default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Campaigns security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: campaignType: description: >- Type of campaign. Defaults to CAMPAIGN_TYPE_CASHBACK_REWARDS if not provided. title: Campaign Type examples: - CAMPAIGN_TYPE_CASHBACK_REWARDS type: string enum: - CAMPAIGN_TYPE_CASHBACK_REWARDS chainId: type: integer format: int32 description: Blockchain network identifier title: Chain ID examples: - 8453 maxRewardAmounts: type: array items: type: object properties: tokenAddress: type: string description: >- The token contract address for which this reward amount limit applies title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' amount: type: string description: >- Maximum reward amount with two decimal places. Must be between 0.01 and 100,000,000. title: Amount examples: - '100.00' description: Maximum reward amount for a specific token. title: MaxRewardAmount required: - tokenAddress - amount examples: - tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' amount: '100.00' description: >- Optional list of maximum reward amounts for specific tokens. Only applicable for CAMPAIGN_TYPE_CASHBACK_REWARDS. title: Max Reward Amounts examples: - - tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' amount: '100.00' maxRewardBps: type: integer format: int32 description: >- Optional immutable maximum reward percentage applied to the smart contract (0-10000). Defaults to 10000 (no cap) if not provided. Only applicable for CAMPAIGN_TYPE_CASHBACK_REWARDS. title: Max Reward BPS examples: - 1000 ownerAddress: type: string description: Address that will own the campaign title: Owner Address examples: - '0x1234567890123456789012345678901234567890' rewardBps: type: integer format: int32 description: >- Reward percentage applied to the reward operations (1-10000, cannot be 0). Only applicable for CAMPAIGN_TYPE_CASHBACK_REWARDS. title: Reward BPS examples: - 500 required: - ownerAddress - chainId - rewardBps required: true /api/v1/operators: post: summary: Create Operator description: Create an operator for handling payments. operationId: OperatorApiService_PostOperator responses: '200': description: A successful response. content: application/json: schema: type: object properties: entity: type: string description: Entity type, usually 'operator'. title: Entity examples: - operator id: type: string description: Unique identifier of the operator. title: Id examples: - op-324235 coinbaseUserId: type: string description: Unique coinbase user identifier of the operator. title: Coinbase User Id examples: - cb-user-1234567890 name: type: string description: Name of the operator title: Name examples: - Test operator status: description: Current status of the operator. title: Status examples: - ACTIVATED type: string enum: - ACTIVATED - DEACTIVATED - PENDING smartAccountAddresses: type: object additionalProperties: type: object properties: addresses: type: array items: type: string description: List of account addresses title: Addresses examples: - addresses: - 0xwallet1 - 0xwallet2 description: >- Map of smart account addresses associated with the operator, grouped by network ID. title: Smart Account Addresses examples: - '8453': addresses: - 0xsmartaccount1 - 0xsmartaccount2 callbackSecret: type: string description: The secret to encrypt callback payload title: Callback Secret createdAt: type: string format: date-time description: Timestamp when the operator was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the operator was last updated. title: Updated At examples: - 2024-03-20T00:00:00.000Z description: Representation of an operator title: Operator required: - entity - id - coinbaseUserId - name - status - smartAccountAddresses - callbackSecret - createdAt - updatedAt examples: - entity: operator id: op-324235 coinbaseUserId: cb-user-1234567890 name: test.operator status: ACTIVATED smartAccountAddresses: - 0xwallet1 - 0xwallet2 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:00:00.000Z callbackSecret: secret default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} tags: - Operator security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: name: type: string description: Name of the operator title: Name examples: - test.operator description: Request payload for creating an operator. title: PostOperatorRequest required: - name examples: - name: test.operator status: ACTIVATED description: Request payload for creating an operator. required: true /api/v1/payment-operations/{id}: get: summary: Get Payment Operation description: Get Payment Operation operationId: OperatorApiService_GetPaymentOperation responses: '200': description: A successful response. content: application/json: schema: type: object properties: paymentOperation: description: Payment operation object. title: Payment Operation type: object properties: entity: type: string description: Entity type, e.g., 'payment-operation'. title: Entity examples: - payment-operation id: type: string description: Unique event ID. title: Id examples: - event123 transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - 0xhash params: type: object additionalProperties: type: string description: Payment Operation Parameters. title: Params examples: - amount: '10.00' status: description: Payment Operation status. title: Status examples: - PAYMENT_OPERATION_STATUS_SUCCEEDED type: string enum: - PAYMENT_OPERATION_STATUS_SUCCEEDED - PAYMENT_OPERATION_STATUS_FAILED - PAYMENT_OPERATION_STATUS_PENDING action: description: >- Type of action (e.g., PAYMENT_OPERATION_ACTION_AUTHORIZE). title: Action examples: - PAYMENT_OPERATION_ACTION_AUTHORIZE type: string enum: - PAYMENT_OPERATION_ACTION_AUTHORIZE - PAYMENT_OPERATION_ACTION_CAPTURE - PAYMENT_OPERATION_ACTION_CHARGE - PAYMENT_OPERATION_ACTION_RECLAIM - PAYMENT_OPERATION_ACTION_REFUND - PAYMENT_OPERATION_ACTION_VOID createdAt: type: string format: date-time description: Event creation timestamp. title: Created At examples: - 2021-05-03T00:00:00.000Z updatedAt: type: string format: date-time description: Event update timestamp. title: Updated At examples: - 2021-05-03T00:30:00.000Z payment: description: Detailed payment object. title: Payment examples: - id: payment123 type: object properties: entity: type: string description: Entity type, e.g., 'payment'. title: Entity examples: - payment id: type: string description: Unique payment ID. title: Id examples: - payment123 maxAmount: type: string description: Max payment amount approved by the buyer. title: Max Amount examples: - '100.00' token: type: string description: Token address used. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network Id examples: - '8453' payer: type: string description: Payer's EVM address. title: Payer examples: - 0xpayer signature: type: string description: >- Digital signature of the preapproved amount signed by the buyer. title: Signature examples: - 0xsig receiver: type: string description: Receiver's EVM address. title: Receiver examples: - 0xreceiver maxFeeBps: type: integer format: int32 description: Max fee in basis points. title: Max Fee Bps examples: - '50' minFeeBps: type: integer format: int32 description: Min fee in basis points. title: Min Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Recipient examples: - '0xfee789' salt: type: string description: >- Unique salt to prevent duplicate preapproval authorizations. title: Salt examples: - '2334324235415445346745646' paymentInfoHash: type: string description: Hash of the payment info. title: Payment Info Hash examples: - '0x2334324235415445346745646' nonce: type: string description: Nonce in the Preapproval Authorization. title: Nonce in the Preapproval Authorization examples: - '2334324235415445346745646' authorizationExpiry: type: string format: int64 description: Expiry time for the authorization. title: Authorization expiry examples: - '1843954582' preApprovalExpiry: type: string format: int64 description: Expiry time for preapproval title: Pre-approval expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: Expiry time for refund title: Refund expiry examples: - '1843954582' createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - 2021-05-03T00:00:00.000Z updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - 2021-05-03T01:00:00.000Z operator: type: string description: Operator handling the payment. title: Operator examples: - 0xoperator contractAddress: type: string description: >- Smart contract address of the Commerce PaymentEscrow protocol title: Contract Address examples: - 0xcontract authorizedAmount: type: string description: Authorized payment amount. title: Authorized Amount examples: - '50.00' capturedAmount: type: string description: Captured payment amount. title: Captured Amount examples: - '50.00' voidedAmount: type: string description: Voided payment amount. title: Voided Amount examples: - '0.00' refundedAmount: type: string description: Refunded payment amount. title: Refunded Amount examples: - '0.00' chargedAmount: type: string description: Charged payment amount. title: Charged Amount examples: - '50.00' merchantId: type: string description: Merchant ID. title: Merchant Id examples: - merchant123 sourceAddress: type: string description: >- CAIP-10 Source address for payment if different than payer address title: Source Address examples: - >- eip155:1:0x1234567890123456789012345678901234567890 sourceAsset: type: string description: >- CAIP-19 Source asset identifier for payment if different than token address title: Source Asset examples: - eip155:1 tokenCollector: type: string description: Token collector address. title: Token Collector examples: - 0xtokencollector required: - entity - id - maxAmount - token - networkId - payer - signature - receiver - maxFeeBps - minFeeBps - feeReceiver - salt - paymentInfoHash - nonce - authorizationExpiry - preApprovalExpiry - refundExpiry - createdAt - updatedAt - operator - contractAddress - authorizedAmount - capturedAmount - voidedAmount - refundedAmount - chargedAmount - merchantId output: type: string description: Output of the payment operation. title: Output examples: - 0xoutput error: type: string description: Error of the payment operation. title: Error examples: - an unknown error occurred errorCode: type: string description: Error code of the payment operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the payment operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the payment operation. title: Block Number examples: - '123' metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: Steps executed as part of this payment operation. title: Operation Steps examples: - - id: os_123 operation_step_type: OPERATION_STEP_TYPE_AUTH_ESCROW status: OPERATION_STEP_STATUS_SUCCEEDED required: - entity - id - transactionHash - params - status - action - createdAt - updatedAt - payment examples: - entity: payment-operation id: event123 transactionHash: 0xhash amount: '50.00' status: SUCCEEDED eventType: AUTHORIZED createdAt: 2021-05-03T00:00:00.000Z updatedAt: 2021-05-03T00:30:00.000Z payment: id: payment123 required: - paymentOperation default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: id in: path required: true tags: - Payments security: - Bearer: [] /api/v1/payments: post: summary: Create payment description: Create a new payment. operationId: OperatorApiService_PostPayment responses: '200': description: A successful response. content: application/json: schema: type: object properties: payment: description: The payment information. title: Payment type: object properties: entity: type: string description: Entity type, e.g., 'payment'. title: Entity examples: - payment id: type: string description: Unique payment ID. title: Id examples: - payment123 maxAmount: type: string description: Max payment amount approved by the buyer. title: Max Amount examples: - '100.00' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network Id examples: - '8453' receiver: type: string description: Receiver's EVM address. title: Receiver examples: - 0xreceiver maxFeeBps: type: integer format: int32 description: Max fee in basis points. title: Max Fee Bps examples: - '50' minFeeBps: type: integer format: int32 description: Min fee in basis points. title: Min Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Recipient examples: - '0xfee789' salt: type: string description: >- Unique salt to prevent duplicate preapproval authorizations. title: Salt examples: - '2334324235415445346745646' paymentInfoHash: type: string description: Hash of the payment info. title: Payment Info Hash examples: - '0x2334324235415445346745646' nonce: type: string description: Nonce in the Preapproval Authorization. title: Nonce in the Preapproval Authorization examples: - '2334324235415445346745646' authorizationExpiry: type: string format: int64 description: Expiry time for the authorization. title: Authorization expiry examples: - '1843954582' preApprovalExpiry: type: string format: int64 description: Expiry time for preapproval title: Pre-approval expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: Expiry time for refund title: Refund expiry examples: - '1843954582' createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - '2021-05-03T00:00:00Z' updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - '2021-05-03T01:00:00Z' operator: type: string description: Operator handling the payment. title: Operator examples: - 0xoperator merchantId: type: string description: Merchant ID. title: Merchant Id examples: - merchant123 sourceAddress: type: string description: >- CAIP-10 Source address for payment if different than payer address title: Source Address examples: - eip155:1:0x1234567890123456789012345678901234567890 sourceAsset: type: string description: >- CAIP-19 Source asset identifier for payment if different than token address title: Source Asset examples: - eip155:1 tokenCollector: type: string description: Token collector address. title: Token Collector examples: - 0xtokencollector merchant: description: Merchant information for this payment. title: Merchant type: object properties: name: type: string description: Name of the merchant. title: Name examples: - MerchantName logoUrl: type: string description: URL to the merchant's logo. title: Logo URL examples: - https://example.com/logo.png locale: type: string description: Locale of the merchant. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - name: MerchantName logoUrl: https://example.com/logo.png locale: en-US metadata: '{}' customer: description: Customer information for this payment. title: Customer type: object properties: locale: type: string description: Locale of the customer. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - locale: en-US metadata: '{}' fiat: description: Fiat currency information for this payment. title: Fiat type: object properties: amount: type: string description: Price of the fiat in the original fiat currency. title: Amount examples: - '10.00' currency: type: string description: Original fiat currency for this fiat. title: Currency examples: - USD metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value examples: - amount: '10.00' currency: USD metadata: '{}' metadata: type: object description: >- Session metadata including wallet provider, device type, OS, and browser. title: Metadata autoAuthorize: type: boolean description: >- Whether to automatically authorize the payment. Defaults to true. title: Auto Authorize examples: - true autoCapture: type: boolean description: >- Whether to automatically capture the payment after authorization. Defaults to true. title: Auto Capture examples: - true externalClientReferenceId: type: string description: External reference ID provided by the client. title: External Client Reference ID examples: - ext-ref-123 version: type: integer format: int32 description: Version number for optimistic locking. title: Version examples: - 1 link: description: Link information for this payment. title: Link type: object properties: id: type: string description: Unique identifier of the link. title: Id examples: - link_abc123 paymentId: type: string description: ID of the associated payment. title: Payment Id examples: - pm_xyz789 url: type: string description: Link URL. title: URL examples: - https://pay.example.com/link maxUsage: type: integer format: int32 description: Maximum allowed uses (-1 for unlimited). title: Max Usage examples: - -1 usageCount: type: integer format: int32 description: Current usage count. title: Usage Count examples: - 0 successRedirectUrl: type: string description: URL to redirect to on successful payment. title: Success Redirect URL examples: - https://example.com/success failRedirectUrl: type: string description: URL to redirect to on failed payment. title: Fail Redirect URL examples: - https://example.com/fail successCallbackUrl: type: string description: URL to call back on successful payment. title: Success Callback URL examples: - https://example.com/callback metadata: type: object description: Link-specific metadata. title: Metadata examples: - key: value createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - '2024-03-20T00:00:00Z' updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - '2024-03-20T00:00:00Z' required: - id - paymentId - url - status - maxUsage - usageCount - successRedirectUrl - failRedirectUrl - successCallbackUrl - hostUrl examples: - id: link_abc123 paymentId: pm_xyz789 url: https://pay.example.com/link maxUsage: -1 usageCount: 0 successRedirectUrl: https://example.com/success failRedirectUrl: https://example.com/fail required: - entity - id - maxAmount - token - networkId - payer - signature - receiver - maxFeeBps - minFeeBps - feeReceiver - salt - paymentInfoHash - nonce - authorizationExpiry - preApprovalExpiry - refundExpiry - createdAt - updatedAt - operator - contractAddress - merchantId - link examples: - entity: payment id: payment123 maxAmount: '100.00' networkId: 8453 receiver: 0xreceiver minFeeBps: 50 maxFeeBps: 50 feeReceiver: '0xcccccccccccccccccccccccccccccccccccccccc' salt: '2334324235415445346745646' paymentInfoHash: '2334324235415445346745646' nonce: '2334324235415445346745646' authorizationExpiry: 1843954582 preApprovalExpiry: 0 refundExpiry: 1843954582 createdAt: '2024-03-20T00:00:00Z' updatedAt: '2024-03-20T00:00:00Z' operator: 0xoperator description: Response containing the payment ID. title: PostPaymentResponse default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: maxAmount: type: string description: >- The max amount to be signed by the buyer, in USD with up to 2 decimal places. title: Max Amount examples: - '100.00' token: type: string description: >- The token address used for the payment. (Default: USDC address for the specified network_id, e.g. 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 for Base Mainnet) title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network ID examples: - '8453' receiver: type: string description: The receiver's wallet address (on Base). title: Receiver examples: - 0xreceiver autoAuthorize: type: boolean description: >- Whether to automatically authorize the transaction once the payer completes the checkout process. (Default: true, unless auto_capture is set). Cannot be true if auto_capture is also true. title: Auto Authorize examples: - 'true' autoCapture: type: boolean description: >- Whether to auto capture the payment. (Default: false). Cannot be true if auto_authorize is also true. title: Auto Capture examples: - 'false' minFeeBps: type: integer format: int32 description: 'Min Fee in basis points. (Default: 0)' title: Min Fee Bps examples: - '50' maxFeeBps: type: integer format: int32 description: 'Max Fee in basis points. (Default: 0)' title: Max Fee Bps examples: - '50' feeReceiver: type: string description: >- Address that receives the fee. (Default: 0x0000000000000000000000000000000000000000) title: Fee Receiver examples: - '0xfee789' preApprovalExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the pre-approval expires. After this expiration, the payment can no longer be authorized or captured. Must be at least 1 minute from now. (Default: now() + 1 day) title: Pre-Approval Expiry examples: - '1843954582' authorizationExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the authorization expires. After this expiration, the payment can no longer be captured. Must be at least 1 minute from now. (Default: now() + 7 days) title: Authorization Expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: >- Timestamp (in seconds) when the refund expires. Must be at least 1 minute from now. (Default: now() + 7 days) title: Refund Expiry examples: - '1843954582' successRedirectUrl: type: string description: URL to redirect on successful payment. title: Success Redirect URL examples: - https://example.com/success failRedirectUrl: type: string description: URL to redirect on failed payment. title: Fail Redirect URL examples: - https://example.com/fail operator: type: string description: >- The operator's smart account address for processing payments. title: Operator examples: - 0xoperator contractAddress: type: string description: >- Contract address of the Commerce protocol (PaymentEscrow.sol). (Default: PaymentEscrow address for the specified network_id, e.g. 0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff for Base Mainnet) title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchant: description: >- Additional merchant metadata. Does not impact the actual payment transaction. title: Merchant examples: - name: MerchantName logoUrl: https://example.com/logo.png locale: en-US metadata: '{}' type: object properties: name: type: string description: Name of the merchant. title: Name examples: - MerchantName logoUrl: type: string description: URL to the merchant's logo. title: Logo URL examples: - https://example.com/logo.png locale: type: string description: Locale of the merchant. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value customer: description: >- Additional customer metadata. Does not impact the actual payment transaction. title: Customer examples: - locale: en-US metadata: '{}' type: object properties: locale: type: string description: Locale of the customer. title: Locale examples: - en-US metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value fiat: description: >- Additional fiat currency metadata. Does not impact the actual payment transaction. title: fiat examples: - amount: '10.00' currency: USD metadata: '{}' type: object properties: amount: type: string description: Price of the fiat in the original fiat currency. title: Amount examples: - '10.00' currency: type: string description: Original fiat currency for this fiat. title: Currency examples: - USD metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value externalClientReferenceId: type: string description: External reference ID provided by the client. title: External Client Reference ID examples: - ext-ref-123 description: Request payload for creating a payment. title: PostPaymentRequest required: - maxAmount - networkId - receiver - operator required: true /api/v1/payments/{id}: get: summary: Get payment description: >- Get a payment by ID. If authenticated with a Bearer token and the operator owns this payment, payment operations will also be returned. operationId: OperatorApiService_GetPayment responses: '200': description: A successful response. content: application/json: schema: type: object properties: payment: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.Payment paymentOperations: type: array description: >- List of payment operations associated with the payment. Only returned when authenticated as the operator that owns this payment. title: Payment Operations items: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.PaymentOperation default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: id in: path required: true description: The ID of the payment. tags: - Payments security: - Bearer: [] /api/v1/payments/authorize: post: summary: Authorize payment description: Authorize funds without capturing them. operationId: OperatorApiService_PostPaymentAuthorize responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment authorization requests. title: PostPaymentAuthorizeResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentInfo: description: Payment info. title: Payment Info type: object properties: operator: type: string description: Operator address. title: Operator examples: - 0xoperator payer: type: string description: Payer address. title: Payer examples: - 0xpayer receiver: type: string description: Receiver address. title: Receiver examples: - 0xreceiver token: type: string description: Token address. title: Token address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: type: string description: Max amount pre approved. title: Max Amount pre approved (2 decimals) examples: - '10.00' preApprovalExpiry: type: string format: int64 description: Pre approval expiry. title: Pre Approval Expiry examples: - '1743712399' authorizationExpiry: type: string format: int64 description: Authorization expiry. title: Authorization Expiry examples: - '1743712399' refundExpiry: type: string format: int64 description: Refund expiry. title: Refund Expiry examples: - '1743712399' minFeeBps: type: string format: int64 description: Min fee bps. title: Min Fee Bps examples: - '50' maxFeeBps: type: string format: int64 description: Max fee bps. title: Max Fee Bps examples: - '100' feeReceiver: type: string description: Fee receiver. title: Fee Receiver examples: - 0xfeereceiver salt: type: string description: >- Source of entropy to ensure unique hashes across different payments. title: Salt required: - operator - payer - receiver - token - maxAmount - preApprovalExpiry - authorizationExpiry - refundExpiry - minFeeBps - maxFeeBps - feeReceiver - salt examples: - operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: '50' maxFeeBps: '100' feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' amount: type: string description: Amount to authorize in the escrow protocol. title: Amount examples: - '50.00' tokenCollector: type: string description: Address of the token collector. title: Token Collector address examples: - '0x3268108503f42B8a8018705586D18B41762248Fb' collectorData: type: string description: >- Data of the payment collector (i.e: ERC3009 Authorization signature) title: Collector Data (Signature) examples: - 0xcollector_data_signature networkId: type: integer format: int32 description: 'Blockchain network identifier. (Default: 8453)' title: Network Id examples: - '8453' contractAddress: type: string description: >- Smart contract address of the Commerce PaymentEscrow protocol. title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchantId: type: string description: Custom merchant ID, which will be returned in the webhook. title: Custom Merchant Id. examples: - merchant123 metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value allocateRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to allocate during payment authorization. title: Allocate Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: >- Request payload for authorizing a payment without capturing funds. title: PostPaymentAuthorizeRequest required: - paymentInfo - amount - tokenCollector - collectorData - networkId - contractAddress examples: - paymentInfo: operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: '50' maxFeeBps: '100' feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' amount: '50.00' tokenCollector: '0x0E3dF9510de65469C4518D7843919c0b8C7A7757' collectorData: 0xcollector_data_signature networkId: 8453 contractAddress: '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchantId: merchant123 description: Request payload for authorizing a payment without capturing funds. required: true /api/v1/payments/capture: post: summary: Capture payment description: Capture funds from the authorized payment. operationId: OperatorApiService_PostPaymentCapture responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment capture requests. title: PostPaymentCaptureResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentInfo: description: Payment info. title: Payment Info examples: - operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: '50' maxFeeBps: '100' feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' type: object properties: operator: type: string description: Operator address. title: Operator examples: - 0xoperator payer: type: string description: Payer address. title: Payer examples: - 0xpayer receiver: type: string description: Receiver address. title: Receiver examples: - 0xreceiver token: type: string description: Token address. title: Token address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: type: string description: Max amount pre approved. title: Max Amount pre approved (2 decimals) examples: - '10.00' preApprovalExpiry: type: string format: int64 description: Pre approval expiry. title: Pre Approval Expiry examples: - '1743712399' authorizationExpiry: type: string format: int64 description: Authorization expiry. title: Authorization Expiry examples: - '1743712399' refundExpiry: type: string format: int64 description: Refund expiry. title: Refund Expiry examples: - '1743712399' minFeeBps: type: string format: int64 description: Min fee bps. title: Min Fee Bps examples: - '50' maxFeeBps: type: string format: int64 description: Max fee bps. title: Max Fee Bps examples: - '100' feeReceiver: type: string description: Fee receiver. title: Fee Receiver examples: - 0xfeereceiver salt: type: string description: >- Source of entropy to ensure unique hashes across different payments. title: Salt required: - operator - payer - receiver - token - maxAmount - preApprovalExpiry - authorizationExpiry - refundExpiry - minFeeBps - maxFeeBps - feeReceiver - salt amount: type: string description: Amount to capture in the escrow protocol. title: Amount examples: - '50.00' feeBps: type: integer format: int32 description: Fee in basis points. title: Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Receiver examples: - 0xfeereceiver networkId: type: integer format: int32 description: 'Blockchain network identifier. (Default: 8453)' title: Network Id examples: - '8453' contractAddress: type: string description: >- Smart contract address of the Commerce PaymentEscrow protocol. title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value distributeRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to distribute during payment capture. title: Distribute Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: Request payload for capturing a payment. title: PostPaymentCaptureRequest required: - paymentInfo - amount - feeBps - feeReceiver - networkId - contractAddress examples: - paymentInfo: operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: '50' maxFeeBps: '100' feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' amount: '50.00' feeBps: '50' feeReceiver: 0xfeereceiver networkId: 8453 contractAddress: '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' description: Request payload for capturing a payment. required: true /api/v1/payments/charge: post: x-hidden: true summary: Charge payment description: Directly authorize and capture funds in a single operation. operationId: OperatorApiService_PostPaymentCharge responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment charge requests. title: PostPaymentChargeResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentInfo: description: Payment info. title: Payment Info examples: - operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: '50' maxFeeBps: '100' feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' type: object properties: operator: type: string description: Operator address. title: Operator examples: - 0xoperator payer: type: string description: Payer address. title: Payer examples: - 0xpayer receiver: type: string description: Receiver address. title: Receiver examples: - 0xreceiver token: type: string description: Token address. title: Token address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: type: string description: Max amount pre approved. title: Max Amount pre approved (2 decimals) examples: - '10.00' preApprovalExpiry: type: string format: int64 description: Pre approval expiry. title: Pre Approval Expiry examples: - '1743712399' authorizationExpiry: type: string format: int64 description: Authorization expiry. title: Authorization Expiry examples: - '1743712399' refundExpiry: type: string format: int64 description: Refund expiry. title: Refund Expiry examples: - '1743712399' minFeeBps: type: string format: int64 description: Min fee bps. title: Min Fee Bps examples: - '50' maxFeeBps: type: string format: int64 description: Max fee bps. title: Max Fee Bps examples: - '100' feeReceiver: type: string description: Fee receiver. title: Fee Receiver examples: - 0xfeereceiver salt: type: string description: >- Source of entropy to ensure unique hashes across different payments. title: Salt required: - operator - payer - receiver - token - maxAmount - preApprovalExpiry - authorizationExpiry - refundExpiry - minFeeBps - maxFeeBps - feeReceiver - salt amount: type: string description: Amount to charge in the escrow protocol. title: Amount examples: - '50.00' tokenCollector: type: string description: Address of the token collector. title: Token Collector address examples: - '0x3268108503f42B8a8018705586D18B41762248Fb' collectorData: type: string description: >- Data of the payment collector (i.e: ERC3009 Authorization signature) title: Collector Data (Signature) examples: - 0xcollector_data_signature feeBps: type: integer format: int32 description: Fee in basis points. title: Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Receiver examples: - 0xfeereceiver networkId: type: integer format: int32 description: 'Blockchain network identifier. (Default: 8453)' title: Network Id examples: - '8453' contractAddress: type: string description: >- Smart contract address of the Commerce PaymentEscrow protocol. title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchantId: type: string description: Custom merchant ID, which will be returned in the webhook. title: Custom Merchant Id. examples: - merchant123 metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value sendRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process during payment charge. title: Send Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: Request payload for directly charging a payment. title: PostPaymentChargeRequest required: - paymentInfo - amount - tokenCollector - collectorData - feeBps - feeReceiver - networkId - contractAddress examples: - paymentInfo: operator: 0xoperator payer: 0xpayer receiver: 0xreceiver token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: '10.00' preApprovalExpiry: '1743712399' authorizationExpiry: '1743712399' refundExpiry: '1743712399' minFeeBps: 50 maxFeeBps: 100 feeReceiver: 0xfeereceiver salt: '0x2334324235415445346745646' amount: '50.00' tokenCollector: '0x0E3dF9510de65469C4518D7843919c0b8C7A7757' collectorData: 0xcollector_data_signature feeBps: 50 feeReceiver: 0xfeereceiver networkId: 8453 contractAddress: '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' merchantId: merchant123 description: Request payload for directly charging a payment. required: true /api/v1/payments/void: post: summary: Void payment description: Void a payment. operationId: OperatorApiService_PostPaymentVoid responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment void requests. title: PostPaymentVoidResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentInfo: description: Payment info. title: Payment Info examples: - operator: '0x2B654aB28f82a2a4E4F6DB8e20791E5AcF4125c6' payer: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' receiver: '0x2B654aB28f82a2a4E4F6DB8e20791E5AcF4125c6' token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' maxAmount: '0.5' preApprovalExpiry: '2814749767655' authorizationExpiry: '2814749777655' refundExpiry: '2814749787655' minFeeBps: 100 maxFeeBps: 100 feeReceiver: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' salt: >- 9924593436278398790143993454453478389197477246831026986870572184585336872985 signature: >- 0x5cce60e215c351ba490a1dd611d699744503d7d358fd627797287455045aed92604888bbb97cd19f7ffcbc4b837520cb5f2bdaa696c1ccc443a01098e4346a7e1b type: object properties: operator: type: string description: Operator address. title: Operator examples: - 0xoperator payer: type: string description: Payer address. title: Payer examples: - 0xpayer receiver: type: string description: Receiver address. title: Receiver examples: - 0xreceiver token: type: string description: Token address. title: Token address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' maxAmount: type: string description: Max amount pre approved. title: Max Amount pre approved (2 decimals) examples: - '10.00' preApprovalExpiry: type: string format: int64 description: Pre approval expiry. title: Pre Approval Expiry examples: - '1743712399' authorizationExpiry: type: string format: int64 description: Authorization expiry. title: Authorization Expiry examples: - '1743712399' refundExpiry: type: string format: int64 description: Refund expiry. title: Refund Expiry examples: - '1743712399' minFeeBps: type: string format: int64 description: Min fee bps. title: Min Fee Bps examples: - '50' maxFeeBps: type: string format: int64 description: Max fee bps. title: Max Fee Bps examples: - '100' feeReceiver: type: string description: Fee receiver. title: Fee Receiver examples: - 0xfeereceiver salt: type: string description: >- Source of entropy to ensure unique hashes across different payments. title: Salt required: - operator - payer - receiver - token - maxAmount - preApprovalExpiry - authorizationExpiry - refundExpiry - minFeeBps - maxFeeBps - feeReceiver - salt networkId: type: integer format: int32 description: Blockchain network identifier. title: Network Id examples: - '8453' contractAddress: type: string description: >- Smart contract address of the Commerce PaymentEscrow protocol. title: Contract Address examples: - '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value deallocateRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to deallocate during payment void. title: Deallocate Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: Request payload for voiding a payment. title: PostPaymentVoidRequest required: - paymentInfo - networkId - contractAddress examples: - paymentInfo: paymentId: p-12345 salt: >- 9924593436278398790143993454453478389197477246831026986870572184585336872985 maxAmount: '0.5' refundExpiry: '2814749787655' preApprovalExpiry: '2814749767655' authorizationExpiry: '2814749777655' operator: '0x2B654aB28f82a2a4E4F6DB8e20791E5AcF4125c6' payer: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' receiver: '0x2B654aB28f82a2a4E4F6DB8e20791E5AcF4125c6' token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' feeReceiver: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' minFeeBps: 100 maxFeeBps: 100 signature: >- 0x5cce60e215c351ba490a1dd611d699744503d7d358fd627797287455045aed92604888bbb97cd19f7ffcbc4b837520cb5f2bdaa696c1ccc443a01098e4346a7e1b networkId: 84532 contractAddress: '0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff' description: Request payload for voiding a payment. required: true /api/v1/payments/{paymentId}/authorize: post: summary: Authorize payment description: >- Authorize funds for a payment using the payment ID. This simplified endpoint fetches payment details from the database. operationId: OperatorApiService_PostPaymentAuthorizeById responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment authorization requests. title: PostPaymentAuthorizeResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: paymentId description: The unique identifier of the payment to authorize. in: path required: true - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: allocateRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to allocate during payment authorization. title: Allocate Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 amount: type: string description: Amount to authorize in the escrow protocol. title: Amount examples: - '50.00' merchantId: type: string description: Custom merchant ID, which will be returned in the webhook. title: Custom Merchant Id. examples: - merchant123 metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value description: >- Request payload for authorizing a payment using the payment ID. This simplified endpoint fetches payment details from the database. title: PostPaymentAuthorizeByIdRequest required: - amount examples: - paymentId: pm_abc123 amount: '50.00' merchantId: merchant123 required: true /api/v1/payments/{paymentId}/capture: post: summary: Capture payment description: >- Capture funds from the authorized payment using the payment ID. This simplified endpoint fetches payment details from the database. operationId: OperatorApiService_PostPaymentCaptureById responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment capture requests. title: PostPaymentCaptureResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: paymentId description: The unique identifier of the payment to capture. in: path required: true - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: amount: type: string description: Amount to capture in the escrow protocol. title: Amount examples: - '50.00' distributeRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to distribute during payment capture. title: Distribute Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 feeBps: type: integer format: int32 description: Fee in basis points. title: Fee Bps examples: - '50' feeReceiver: type: string description: Address of the fee receiver. title: Fee Receiver examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value description: >- Request payload for capturing a payment using the payment ID. This simplified endpoint fetches payment details from the database. title: PostPaymentCaptureByIdRequest required: - amount - feeBps - feeReceiver examples: - paymentId: pm_abc123 amount: '50.00' feeBps: 50 feeReceiver: 0xfeereceiver required: true /api/v1/payments/{paymentId}/charge: post: x-hidden: true summary: Charge payment description: >- Directly authorize and capture funds using the payment ID. This simplified endpoint fetches payment details from the database. operationId: OperatorApiService_PostPaymentChargeById responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment charge requests. title: PostPaymentChargeResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: paymentId description: The unique identifier of the payment to charge. in: path required: true - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: amount: type: string description: Amount to charge in the escrow protocol. title: Amount examples: - '50.00' feeBps: type: integer format: int32 description: Fee in basis points. title: Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Receiver examples: - 0xfeereceiver merchantId: type: string description: Custom merchant ID, which will be returned in the webhook. title: Custom Merchant Id. examples: - merchant123 metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value sendRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process during payment charge. title: Send Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: >- Request payload for charging a payment using the payment ID. This simplified endpoint fetches payment details from the database. title: PostPaymentChargeByIdRequest required: - amount - feeBps - feeReceiver examples: - paymentId: pm_abc123 amount: '50.00' feeBps: 50 feeReceiver: 0xfeereceiver merchantId: merchant123 required: true /api/v1/payments/{paymentId}/void: post: summary: Void payment description: >- Void a payment using the payment ID. This simplified endpoint fetches payment details from the database. operationId: OperatorApiService_PostPaymentVoidById responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of reward operations with detailed information, if rewards were processed. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of rewards that were invalid/unable to be processed with detailed reasoning title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for payment void requests. title: PostPaymentVoidResponse required: - operationId examples: - operationId: op-2341434 rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: paymentId description: The unique identifier of the payment to void. in: path required: true - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value deallocateRewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to deallocate during payment void. title: Deallocate Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: >- Request payload for voiding a payment using the payment ID. This simplified endpoint fetches payment details from the database. title: PostPaymentVoidByIdRequest examples: - paymentId: pm_abc123 required: true /api/v1/payments/{paymentId}/refund: post: summary: Refund payment description: >- Refund funds using the payment ID. This simplified endpoint fetches payment details from the database. operationId: OperatorApiService_PostPaymentRefundById responses: '200': description: A successful response. content: application/json: schema: type: object properties: operationId: type: string description: Identifier for the payment operation. title: Operation Id examples: - op-2341434 description: Response payload for payment refund requests. title: PostPaymentRefundResponse required: - operationId examples: - operationId: op-2341434 default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: paymentId description: The unique identifier of the payment to refund. in: path required: true - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Payments security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: amount: type: string description: >- Amount to refund (must be less than or equal to the captured/charged amount). title: Amount examples: - '50.00' metadata: type: object description: >- Metadata for the payment operation that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for refunding a payment using the payment ID. title: PostPaymentRefundByIdRequest required: - amount examples: - paymentId: pm_abc123 amount: '50.00' required: true /api/v1/reward-operations/{id}: get: summary: 'Get reward operation ' description: Get reward operation operationId: OperatorApiService_GetRewardOperation responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperation: description: Reward operation object. title: Reward Operation type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value required: - rewardOperation default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: id in: path required: true tags: - Rewards security: - Bearer: [] /api/v1/rewards/allocate: post: summary: Allocate rewards description: Allocate rewards for a payment operation. operationId: OperatorApiService_PostAllocateRewards responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of successful reward operations with detailed information. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of reward inputs that were invalid/unable to be processed with detailed reasoning. title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for allocating rewards. title: PostAllocateRewardsResponse examples: - rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Rewards security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentOperationId: type: string description: The ID of the payment operation to associate rewards with. title: Payment Operation ID examples: - op-123456 rewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process. title: Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: type: object description: >- Metadata for the reward operations that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for allocating rewards. title: PostAllocateRewardsRequest required: - paymentOperationId - rewards examples: - paymentOperationId: op-123456 rewards: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: key: value description: Request payload for allocating rewards. required: true /api/v1/rewards/deallocate: post: summary: Deallocate rewards description: Deallocate rewards for a payment operation. operationId: OperatorApiService_PostDeallocateRewards responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of successful reward operations with detailed information. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: >- 0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ec04dC2DC5Ef8793 tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of reward inputs that were invalid/unable to be processed with detailed reasoning. title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for deallocating rewards. title: PostDeallocateRewardsResponse examples: - rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Rewards security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentOperationId: type: string description: The ID of the payment operation to associate rewards with. title: Payment Operation ID examples: - op-123456 rewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process. title: Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: type: object description: >- Metadata for the reward operations that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for deallocating rewards. title: PostDeallocateRewardsRequest required: - paymentOperationId - rewards examples: - paymentOperationId: op-123456 rewards: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: key: value description: Request payload for deallocating rewards. required: true /api/v1/rewards/distribute: post: summary: Distribute rewards description: Distribute rewards for a payment operation. operationId: OperatorApiService_PostDistributeRewards responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of successful reward operations with detailed information. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of reward inputs that were invalid/unable to be processed with detailed reasoning. title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for distributing rewards. title: PostDistributeRewardsResponse examples: - rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Rewards security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentOperationId: type: string description: The ID of the payment operation to associate rewards with. title: Payment Operation ID examples: - op-123456 rewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process. title: Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: type: object description: >- Metadata for the reward operations that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for distributing rewards. title: PostDistributeRewardsRequest required: - paymentOperationId - rewards examples: - paymentOperationId: op-123456 rewards: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: key: value description: Request payload for distributing rewards. required: true /api/v1/rewards/send: post: summary: Send rewards description: Send rewards for a payment operation. operationId: OperatorApiService_PostSendRewards responses: '200': description: A successful response. content: application/json: schema: type: object properties: rewardOperations: type: array items: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: description: >- Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: >- Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: >- Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: >- The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt action: description: >- Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED transactionHash: type: string description: >- Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value operationSteps: type: array items: type: object properties: entity: type: string description: Entity type, usually 'operation-step'. title: Entity examples: - operation-step id: type: string description: Unique identifier of the operation step. title: Id examples: - os_01234567890abcdef type: description: >- Type of the operation step (e.g., AUTH_ESCROW, CROSSCHAIN, FLYWHEEL). title: Operation Step Type examples: - OPERATION_STEP_TYPE_AUTH_ESCROW type: string enum: - OPERATION_STEP_TYPE_AUTH_ESCROW - OPERATION_STEP_TYPE_CROSSCHAIN - OPERATION_STEP_TYPE_FLYWHEEL operationId: type: string description: Identifier of the parent operation. title: Operation Id examples: - op-2341434 operationType: description: >- Type of the parent operation (e.g., PAYMENT, REWARD). title: Operation Type examples: - OPERATION_TYPE_PAYMENT type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD params: type: object description: >- Parameters for the operation step as a free-form object. title: Params examples: - key: value status: description: Current status of the operation step. title: Status examples: - OPERATION_STEP_STATUS_SUCCEEDED type: string enum: - OPERATION_STEP_STATUS_SUCCEEDED - OPERATION_STEP_STATUS_FAILED - OPERATION_STEP_STATUS_PENDING error: type: string description: Error message if the operation step failed. title: Error examples: - Failed to authorize escrow errorCode: type: string description: Error code if the operation step failed. title: Error Code examples: - AUTH_ESCROW_FAILED createdAt: type: string format: date-time description: Timestamp when the operation step was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the operation step was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z transactions: type: array items: type: object properties: entity: type: string description: Entity type, usually 'transaction'. title: Entity examples: - transaction transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: type: string format: int64 description: >- Block number where the transaction was included. title: Block Number examples: - '12345678' revertReason: type: string description: Revert reason if the transaction failed. title: Revert Reason examples: - Execution reverted createdAt: type: string format: date-time description: >- Timestamp when the transaction record was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: >- Timestamp when the transaction record was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z operationStepId: type: string description: >- Identifier of the operation step this transaction belongs to. title: Operation Step Id examples: - os_01234567890abcdef description: >- Represents a blockchain transaction with its hash, block number, and revert reason if applicable. title: Transaction required: - entity - transactionHash - blockNumber - createdAt - updatedAt examples: - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- Blockchain transactions associated with this operation step. title: Transactions examples: - - entity: transaction transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef blockNumber: 12345678 description: >- Represents a step within an operation, tracking its type, status, and associated parameters. title: OperationStep required: - entity - id - type - operationId - operationType - status - createdAt - updatedAt examples: - entity: operation-step id: os_01234567890abcdef operationStepType: OPERATION_STEP_TYPE_AUTH_ESCROW operationId: op-2341434 operationType: OPERATION_TYPE_PAYMENT params: key: value status: OPERATION_STEP_STATUS_SUCCEEDED createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z description: >- List of operation steps associated with this reward operation. title: Operation Steps examples: - - id: os-123456 type: OPERATION_STEP_TYPE_FLYWHEEL status: OPERATION_STEP_STATUS_SUCCEEDED description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 metadata: key: value description: >- List of successful reward operations with detailed information. title: Reward Operations examples: - - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: type: array items: type: object properties: rewardInput: description: The reward input that was invalid title: Reward Input type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: type: string description: Reason why this reward input is invalid title: Invalid Reason description: >- Details about a reward input that could not be processed. title: InvalidRewardInput description: >- List of reward inputs that were invalid/unable to be processed with detailed reasoning. title: Invalid Reward Inputs examples: - - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address description: Response payload for sending rewards. title: PostSendRewardsResponse examples: - rewardOperations: - id: ro-5678901 reward: id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z action: REWARD_OPERATION_ACTION_ALLOCATE amount: '100.00' status: REWARD_OPERATION_STATUS_PENDING transactionHash: >- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z metadata: key: value invalidRewardInputs: - rewardInput: campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 invalidReason: invalid campaign address default: description: An unexpected error response. content: application/json: schema: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object properties: '@type': type: string additionalProperties: {} parameters: - schema: type: string name: x-idempotency-key description: Unique identifier to ensure request idempotency in: header required: true tags: - Rewards security: - Bearer: [] requestBody: content: application/json: schema: type: object properties: paymentOperationId: type: string description: The ID of the payment operation to associate rewards with. title: Payment Operation ID examples: - op-123456 rewards: type: array items: type: object properties: campaignAddress: type: string description: The onchain address of the campaign title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' tokenAddress: type: string description: The token address for the rewards title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The chain ID where the campaign is deployed title: Chain ID examples: - 8453 description: Information required to execute a rewards operation. title: RewardInput required: - campaignAddress - tokenAddress - chainId examples: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 description: List of rewards to process. title: Rewards examples: - - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: type: object description: >- Metadata for the reward operations that will be returned in the webhook. title: Metadata examples: - key: value description: Request payload for sending rewards. title: PostSendRewardsRequest required: - paymentOperationId - rewards examples: - paymentOperationId: op-123456 rewards: - campaignAddress: '0x1234567890123456789012345678901234567890' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 metadata: key: value description: Request payload for sending rewards. required: true /api/v1/webhook-deliveries/event/{eventId}: get: summary: Get webhook deliveries by event ID description: Retrieve webhook deliveries by its event ID. operationId: WebhooksApiService_GetWebhookDeliveriesByEventId responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.GetWebhookDeliveriesByEventIdResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: eventId description: The unique identifier of the webhook event. in: path required: true - schema: type: integer format: int32 name: limit description: >- Limit Maximum number of webhook deliveries to return. Default is 10, Max is 25. in: query required: false - schema: type: string name: next description: |- Next Next item to use for pagination. in: query required: false tags: - WebhookDeliveries security: - Bearer: [] /api/v1/webhook-events: get: summary: List webhook events description: Retrieve all webhook events for an operator. operationId: WebhooksApiService_GetWebhookEventsPerOperator responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.GetWebhookEventsPerOperatorResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: integer format: int32 name: limit description: >- Limit Maximum number of webhook events to return. Default is 10, Max is 25. in: query required: false - schema: type: string name: next description: |- Next Next item to use for pagination. in: query required: false tags: - WebhookEvents security: - Bearer: [] /api/v1/webhook-events/payment-operation/{operationId}: get: summary: Get webhook events by payment operation ID description: Retrieve a list of webhook events by its payment operation ID. operationId: WebhooksApiService_GetWebhookEventsByPaymentOperationId responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.GetWebhookEventsByPaymentOperationIdResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: operationId description: The unique identifier of the payment operation. in: path required: true - schema: type: integer format: int32 name: limit description: >- Limit Maximum number of webhook events to return. Default is 10, Max is 25. in: query required: false - schema: type: string name: next description: |- Next Next item to use for pagination. in: query required: false tags: - WebhookEvents security: - Bearer: [] /api/v1/webhook-events/reward-operation/{operationId}: get: summary: Get webhook events by reward operation ID description: Retrieve a list of webhook events by its reward operation ID. operationId: WebhooksApiService_GetWebhookEventsByRewardOperationId responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.GetWebhookEventsByRewardOperationIdResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: operationId description: The unique identifier of the reward operation. in: path required: true - schema: type: integer format: int32 name: limit description: >- Limit Maximum number of webhook events to return. Default is 10, Max is 25. in: query required: false - schema: type: string name: next description: |- Next Next item to use for pagination. in: query required: false tags: - WebhookEvents security: - Bearer: [] /api/v1/webhook-events/{id}: get: summary: Get webhook event by ID description: Retrieve a webhook event by its webhook event ID. operationId: WebhooksApiService_GetWebhookEvent responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.WebhookEvent default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: id description: The unique identifier of the webhook event. in: path required: true tags: - WebhookEvents security: - Bearer: [] /api/v1/webhooks: get: summary: List webhooks description: Retrieve all activated webhooks for an operator. operationId: WebhooksApiService_GetWebhooksPerOperator responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.GetWebhooksPerOperatorResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: integer format: int32 name: limit description: |- Limit Maximum number of webhooks to return. Default is 25. Max is 50. in: query required: false - schema: type: string name: next description: |- Next Next item to use for pagination. in: query required: false tags: - Webhooks security: - Bearer: [] post: summary: Create webhook description: Create a new webhook. operationId: WebhooksApiService_PostWebhook responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.Webhook' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' tags: - Webhooks security: - Bearer: [] requestBody: content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PostWebhookRequest description: Request to create a new webhook. required: true /api/v1/webhooks/{id}: get: summary: Get webhook description: Retrieve a webhook by its ID. operationId: WebhooksApiService_GetWebhook responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.Webhook' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: id description: The unique identifier of the webhook. in: path required: true tags: - Webhooks security: - Bearer: [] delete: summary: Delete webhook description: Delete a webhook by its ID. operationId: WebhooksApiService_DeleteWebhook responses: '200': description: A successful response. content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.DeleteWebhookResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: id description: The unique identifier of the webhook to delete. in: path required: true tags: - Webhooks security: - Bearer: [] put: summary: Update webhook description: Update an existing webhook's properties. operationId: WebhooksApiService_PutWebhook responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.Webhook' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/google.rpc.Status' parameters: - schema: type: string name: id description: The unique identifier of the webhook to update. in: path required: true tags: - Webhooks security: - Bearer: [] requestBody: content: application/json: schema: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.WebhooksApiService.PutWebhookBody required: true servers: - url: https://payments.coinbase.com components: schemas: coinbase.engine.operator_api.v1.Payment: type: object properties: entity: type: string description: Entity type, e.g., 'payment'. title: Entity examples: - payment id: type: string description: Unique payment ID. title: Id examples: - payment123 maxAmount: type: string description: Max payment amount approved by the buyer. title: Max Amount examples: - '100.00' token: type: string description: Token address used. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' networkId: type: integer format: int32 description: Identifier for the blockchain network. title: Network Id examples: - '8453' payer: type: string description: Payer's EVM address. title: Payer examples: - 0xpayer signature: type: string description: Digital signature of the preapproved amount signed by the buyer. title: Signature examples: - 0xsig receiver: type: string description: Receiver's EVM address. title: Receiver examples: - 0xreceiver maxFeeBps: type: integer format: int32 description: Max fee in basis points. title: Max Fee Bps examples: - '50' minFeeBps: type: integer format: int32 description: Min fee in basis points. title: Min Fee Bps examples: - '50' feeReceiver: type: string description: Fee recipient address. title: Fee Recipient examples: - '0xfee789' salt: type: string description: Unique salt to prevent duplicate preapproval authorizations. title: Salt examples: - '2334324235415445346745646' paymentInfoHash: type: string description: Hash of the payment info. title: Payment Info Hash examples: - '0x2334324235415445346745646' nonce: type: string description: Nonce in the Preapproval Authorization. title: Nonce in the Preapproval Authorization examples: - '2334324235415445346745646' authorizationExpiry: type: string format: int64 description: Expiry time for the authorization. title: Authorization expiry examples: - '1843954582' preApprovalExpiry: type: string format: int64 description: Expiry time for preapproval title: Pre-approval expiry examples: - '1843954582' refundExpiry: type: string format: int64 description: Expiry time for refund title: Refund expiry examples: - '1843954582' createdAt: type: string format: date-time description: Creation timestamp. title: Created At examples: - 2021-05-03T00:00:00.000Z updatedAt: type: string format: date-time description: Last update timestamp. title: Updated At examples: - 2021-05-03T01:00:00.000Z operator: type: string description: Operator handling the payment. title: Operator examples: - 0xoperator contractAddress: type: string description: Smart contract address of the Commerce PaymentEscrow protocol title: Contract Address examples: - 0xcontract authorizedAmount: type: string description: Authorized payment amount. title: Authorized Amount examples: - '50.00' capturedAmount: type: string description: Captured payment amount. title: Captured Amount examples: - '50.00' voidedAmount: type: string description: Voided payment amount. title: Voided Amount examples: - '0.00' refundedAmount: type: string description: Refunded payment amount. title: Refunded Amount examples: - '0.00' chargedAmount: type: string description: Charged payment amount. title: Charged Amount examples: - '50.00' merchantId: type: string description: Merchant ID. title: Merchant Id examples: - merchant123 description: >- Payment details including identifiers, amounts, and blockchain transaction data. title: Payment required: - entity - id - maxAmount - token - networkId - payer - signature - receiver - maxFeeBps - minFeeBps - feeReceiver - salt - paymentInfoHash - nonce - authorizationExpiry - preApprovalExpiry - refundExpiry - createdAt - updatedAt - operator - contractAddress - authorizedAmount - capturedAmount - voidedAmount - refundedAmount - chargedAmount - merchantId examples: - entity: payment id: payment123 maxAmount: '100.00' token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' networkId: 8453 payer: 0xpayer signature: 0xsig receiver: 0xreceiver minFeeBps: 50 maxFeeBps: 50 feeReceiver: '0xcccccccccccccccccccccccccccccccccccccccc' salt: '2334324235415445346745646' paymentInfoHash: '2334324235415445346745646' nonce: '2334324235415445346745646' authorizationExpiry: 1843954582 preApprovalExpiry: 0 refundExpiry: 1843954582 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:00:00.000Z operator: 0xoperator contractAddress: 0xcontract authorizedAmount: '50.00' capturedAmount: '50.00' voidedAmount: '0.00' refundedAmount: '0.00' chargedAmount: '50.00' coinbase.engine.operator_api.v1.PaymentOperation: type: object properties: entity: type: string description: Entity type, e.g., 'payment-operation'. title: Entity examples: - payment-operation id: type: string description: Unique event ID. title: Id examples: - event123 transactionHash: type: string description: Blockchain transaction hash. title: Transaction Hash examples: - 0xhash params: type: object additionalProperties: type: string description: Payment Operation Parameters. title: Params examples: - amount: '10.00' status: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.PaymentOperationStatus description: Payment Operation status. title: Status examples: - PAYMENT_OPERATION_STATUS_SUCCEEDED action: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.PaymentOperationAction description: Type of action (e.g., PAYMENT_OPERATION_ACTION_AUTHORIZE). title: Action examples: - PAYMENT_OPERATION_ACTION_AUTHORIZE createdAt: type: string format: date-time description: Event creation timestamp. title: Created At examples: - 2021-05-03T00:00:00.000Z updatedAt: type: string format: date-time description: Event update timestamp. title: Updated At examples: - 2021-05-03T00:30:00.000Z payment: $ref: '#/components/schemas/coinbase.engine.operator_api.v1.Payment' description: Detailed payment object. title: Payment examples: - id: payment123 output: type: string description: Output of the payment operation. title: Output examples: - 0xoutput error: type: string description: Error of the payment operation. title: Error examples: - an unknown error occurred errorCode: type: string description: Error code of the payment operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the payment operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the payment operation. title: Block Number examples: - '123' metadata: type: object description: Additional metadata as a free-form object. title: Metadata examples: - key: value description: >- Event details related to a payment including transaction hash, status, and associated payment information. title: PaymentOperation required: - entity - id - transactionHash - params - status - action - createdAt - updatedAt - payment examples: - entity: payment-operation id: event123 transactionHash: 0xhash amount: '50.00' status: SUCCEEDED eventType: AUTHORIZED createdAt: 2021-05-03T00:00:00.000Z updatedAt: 2021-05-03T00:30:00.000Z payment: id: payment123 coinbase.engine.operator_api.v1.PaymentOperationAction: type: string enum: - PAYMENT_OPERATION_ACTION_AUTHORIZE - PAYMENT_OPERATION_ACTION_CAPTURE - PAYMENT_OPERATION_ACTION_CHARGE - PAYMENT_OPERATION_ACTION_RECLAIM - PAYMENT_OPERATION_ACTION_REFUND - PAYMENT_OPERATION_ACTION_VOID description: Action to be performed on the payment. title: PaymentOperationAction coinbase.engine.operator_api.v1.PaymentOperationStatus: type: string enum: - PAYMENT_OPERATION_STATUS_SUCCEEDED - PAYMENT_OPERATION_STATUS_FAILED - PAYMENT_OPERATION_STATUS_PENDING description: Status of the payment operation. title: PaymentOperationStatus coinbase.engine.operator_api.v1.Reward: type: object properties: id: type: string description: Unique identifier for the reward. title: Reward ID examples: - rw-123456 campaignAddress: type: string description: Onchain address of the campaign contract. title: Campaign Address examples: - '0x1234567890123456789012345678901234567890' paymentInfoHash: type: string description: Hash of the payment info that this reward is associated with. title: Payment Info Hash examples: - >- 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef recipientAddress: type: string description: Blockchain address that will receive the reward. title: Recipient Address examples: - '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: type: string description: Address of the token contract used for the reward. title: Token Address examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: type: integer format: int32 description: The blockchain network identifier where the reward is processed. title: Chain ID examples: - 8453 createdAt: type: string format: date-time description: Timestamp when the reward was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z description: >- Reward details including campaign association, payment tracking, and amount states throughout the reward lifecycle. title: Reward required: - id - campaignAddress - paymentInfoHash - recipientAddress - tokenAddress - chainId - createdAt - updatedAt examples: - id: rw-123456 campaignAddress: '0x1234567890123456789012345678901234567890' paymentInfoHash: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef' recipientAddress: '0x8078EB517712aAAdcCE9a0C5Ec04dC2DC5Ef8793' tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' chainId: 8453 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z coinbase.engine.operator_api.v1.RewardOperation: type: object properties: id: type: string description: Unique identifier for the reward operation. title: Reward Operation ID examples: - ro-789012 reward: $ref: '#/components/schemas/coinbase.engine.operator_api.v1.Reward' description: Detailed reward object associated with this operation. title: Reward examples: - id: rw-123456 action: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.RewardOperationAction description: Type of reward operation (e.g., REWARD_OPERATION_ACTION_DISTRIBUTE). title: Action examples: - REWARD_OPERATION_ACTION_DISTRIBUTE amount: type: string description: Amount involved in this reward operation. title: Amount examples: - '100.00' status: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.RewardOperationStatus description: Current status of the reward operation. title: Status examples: - REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: type: string description: Blockchain transaction hash for this reward operation. title: Transaction Hash examples: - '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' error: type: string description: Error message if the reward operation failed. title: Error examples: - insufficient funds in campaign errorCode: type: string description: Error code of the reward operation. title: Error Code examples: - Error revertReason: type: string description: Blockchain revert reason of the reward operation. title: Blockchain Revert Reason examples: - 0xrevert blockNumber: type: string format: int64 description: Block number of the reward operation. title: Block Number examples: - '123' createdAt: type: string format: date-time description: Timestamp when the reward operation was created. title: Created At examples: - 2024-03-20T00:00:00.000Z updatedAt: type: string format: date-time description: Timestamp when the reward operation was last updated. title: Updated At examples: - 2024-03-20T00:30:00.000Z description: >- Operation details related to a reward including transaction hash, status, and associated reward information. title: RewardOperation required: - id - action - status - createdAt - updatedAt examples: - id: ro-789012 rewardId: rw-123456 action: REWARD_OPERATION_ACTION_DISTRIBUTE amount: '100.00' status: REWARD_OPERATION_STATUS_SUCCEEDED transactionHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' error: null errorCode: null revertReason: null blockNumber: 123 createdAt: 2024-03-20T00:00:00.000Z updatedAt: 2024-03-20T00:30:00.000Z reward: id: rw-123456 coinbase.engine.operator_api.v1.RewardOperationAction: type: string enum: - REWARD_OPERATION_ACTION_ALLOCATE - REWARD_OPERATION_ACTION_DEALLOCATE - REWARD_OPERATION_ACTION_DISTRIBUTE - REWARD_OPERATION_ACTION_SEND description: Action to be performed on the reward operation. title: RewardOperationAction coinbase.engine.operator_api.v1.RewardOperationStatus: type: string enum: - REWARD_OPERATION_STATUS_PENDING - REWARD_OPERATION_STATUS_SUCCEEDED - REWARD_OPERATION_STATUS_FAILED description: Status of the reward operation. title: RewardOperationStatus coinbase.engine.webhooks_api.v1.DeleteWebhookResponse: type: object properties: success: type: boolean description: Indicates if the deletion was successful. title: Success examples: - true description: Response after successful webhook deletion. title: DeleteWebhookResponse examples: - success: true coinbase.engine.webhooks_api.v1.EventType: type: string enum: - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT - EVENT_TYPE_PAYMENT_RECONCILED description: List of supported events. title: EventType examples: - EVENT_TYPE_PAYMENT_AUTHORIZED coinbase.engine.webhooks_api.v1.GetWebhookDeliveriesByEventIdResponse: type: object properties: webhookDeliveries: type: array items: type: object $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.WebhookDelivery description: List of webhook deliveries. title: WebhookDeliveries pagination: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PaginationResponse description: Pagination information for the response. title: Pagination description: List of webhook deliveries. title: GetWebhookDeliveriesByEventIdResponse required: - webhookDeliveries - pagination coinbase.engine.webhooks_api.v1.GetWebhookEventsByPaymentOperationIdResponse: type: object properties: webhookEvents: type: array items: type: object $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookEvent' description: List of webhook events. title: WebhookEvents pagination: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PaginationResponse description: Pagination information for the response. title: Pagination description: Response to get a list of webhook events by its payment operation ID. title: GetWebhookEventsByPaymentOperationIdResponse required: - webhookEvents - pagination examples: - webhookEvents: - entity: webhook_event id: wh_123456789 operationId: op_123456789 status: WEBHOOK_EVENT_STATUS_DELIVERED coinbase.engine.webhooks_api.v1.GetWebhookEventsByRewardOperationIdResponse: type: object properties: webhookEvents: type: array items: type: object $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookEvent' description: List of webhook events. title: WebhookEvents pagination: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PaginationResponse description: Pagination information for the response. title: Pagination description: Response to get a list of webhook events by its reward operation ID. title: GetWebhookEventsByRewardOperationIdResponse required: - webhookEvents - pagination examples: - webhookEvents: - entity: webhook_event id: wh_123456789 operationId: op_123456789 status: WEBHOOK_EVENT_STATUS_DELIVERED coinbase.engine.webhooks_api.v1.GetWebhookEventsPerOperatorResponse: type: object properties: webhookEvents: type: array items: type: object $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookEvent' description: List of webhook events. title: WebhookEvents pagination: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PaginationResponse description: Pagination information for the response. title: Pagination description: List of webhook events . title: GetWebhookEventsPerOperatorResponse required: - webhookEvents - pagination examples: - webhookEvents: - entity: webhook-event id: wh_event_123456789 eventType: EVENT_TYPE_PAYMENT_AUTHORIZED paymentOperation: entity: payment-operation webhook: entity: webhook source: WEBHOOK_SOURCE_OPERATOR attempts: 0 maxRetries: 5 apiVersion: v1 createdAt: 2023-01-01T00:00:00.000Z deliveredAt: 2023-01-01T00:00:00.000Z coinbase.engine.webhooks_api.v1.GetWebhooksPerOperatorResponse: type: object properties: webhooks: type: array items: type: object $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.Webhook' description: List of webhook objects. title: Webhooks pagination: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.PaginationResponse description: Pagination information for the response. title: Pagination description: List of webhooks. title: Webhooks required: - webhooks - pagination examples: - webhooks: - entity: webhook id: wh_123456789 operatorId: op_987654321 url: https://example.com/webhooks events: - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT status: WEBHOOK_STATUS_ACTIVE coinbase.engine.webhooks_api.v1.OperationType: type: string enum: - OPERATION_TYPE_PAYMENT - OPERATION_TYPE_REWARD description: Type of operation that triggered the webhook. title: OperationType examples: - OPERATION_TYPE_PAYMENT coinbase.engine.webhooks_api.v1.PaginationResponse: type: object properties: limit: type: integer format: int32 description: Number of items per page in this response. title: Limit examples: - 10 next: type: string description: Next item to use for pagination. title: Next Item examples: - wh_event_123456789 description: Pagination details for list responses. title: PaginationResponse required: - limit - next examples: - limit: 10 next: wh_event_123456789 coinbase.engine.webhooks_api.v1.PostWebhookRequest: type: object properties: url: type: string description: The URL where webhook events will be sent. title: URL examples: - https://example.com/webhooks events: type: array items: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.EventType' description: Types of events this webhook should receive. title: Events examples: - - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT identifier: type: string description: External identifier for operators. title: Identifier examples: - client-webhook-1 description: type: string description: Human-readable description of the webhook's purpose. title: Description examples: - Payment notifications for order processing description: Request to create a new webhook. title: PostWebhookRequest required: - url - events examples: - url: https://example.com/webhooks events: - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT identifier: custom-id-1 description: Custom webhook description coinbase.engine.webhooks_api.v1.Webhook: type: object properties: entity: type: string description: Type of the entity, always "webhook". title: Entity examples: - webhook id: type: string description: Unique identifier for the webhook. title: ID examples: - wh_123456789 operatorCoinbaseUserId: type: string description: Coinbase user ID of the operator this webhook belongs to. title: Operator Coinbase User ID examples: - f521747f-6fc8-4a1d-a765-625dcc86c0db identifier: type: string description: External identifier for clients. title: Identifier examples: - client-webhook-1 description: type: string description: Human-readable description of the webhook's purpose. title: Description examples: - Payment notifications for order processing url: type: string description: The URL where webhook events will be sent. title: URL examples: - https://example.com/webhooks events: type: array items: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.EventType' description: Types of events this webhook should receive. title: Events examples: - - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT secret: type: string description: Secret used for webhook signature verification. title: Secret examples: - whsec_abcdef1234567890 status: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookStatus' description: Status of the webhook (active, inactive). title: Status examples: - WEBHOOK_STATUS_ACTIVE createdAt: type: string format: date-time description: When the webhook was created. title: Created At examples: - 2023-01-01T00:00:00.000Z updatedAt: type: string format: date-time description: When the webhook was last updated. title: Updated At examples: - 2023-01-02T00:00:00.000Z description: Webhook configuration details. title: Webhook examples: - entity: webhook id: wh_123456789 operatorCoinbaseUserId: op_987654321 identifier: client-webhook-1 description: Payment notifications for order processing url: https://example.com/webhooks secret: whsec_abcdef1234567890 events: - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT status: WEBHOOK_STATUS_ACTIVE createdAt: 2023-01-01T00:00:00.000Z updatedAt: 2023-01-02T00:00:00.000Z coinbase.engine.webhooks_api.v1.WebhookDelivery: type: object properties: entity: type: string description: The entity type of the webhook delivery. title: Entity examples: - webhook-delivery id: type: string description: The unique identifier of the webhook delivery. title: ID examples: - wh_delivery_123456789 webhookEventId: type: string description: The unique identifier of the webhook event. title: Webhook Event ID examples: - wh_event_123456789 webhookId: type: string description: The unique identifier of the webhook. title: Webhook ID examples: - wh_123456789 statusCode: type: integer format: int32 description: The status code of the webhook delivery. title: Status Code examples: - 200 status: $ref: >- #/components/schemas/coinbase.engine.webhooks_api.v1.WebhookDeliveryStatus description: The status of the webhook delivery. title: Status examples: - WEBHOOK_DELIVERY_STATUS_DELIVERED lastResponse: type: string description: The last response of the webhook delivery. title: Last Response deliveryDuration: type: number format: float description: The duration of the webhook delivery. title: Delivery Duration examples: - 1000 createdAt: type: string format: date-time description: The creation time of the webhook delivery. title: Created At examples: - 2023-01-01T00:00:00.000Z updatedAt: type: string format: date-time description: The last update time of the webhook delivery. title: Updated At examples: - 2023-01-01T00:00:00.000Z description: Webhook delivery details. title: WebhookDelivery required: - entity - id - webhookEventId - webhookId - statusCode - status - lastResponse - deliveryDuration - createdAt - updatedAt examples: - entity: webhook-delivery id: wh_delivery_123456789 eventId: wh_event_123456789 webhookId: wh_123456789 statusCode: 200 status: WEBHOOK_DELIVERY_STATUS_DELIVERED createdAt: 2023-01-01T00:00:00.000Z updatedAt: 2023-01-01T00:00:00.000Z coinbase.engine.webhooks_api.v1.WebhookDeliveryStatus: type: string enum: - WEBHOOK_DELIVERY_STATUS_DELIVERED - WEBHOOK_DELIVERY_STATUS_FAILED description: Enumeration of supported webhook delivery statuses. title: WebhookDeliveryStatus examples: - WEBHOOK_DELIVERY_STATUS_DELIVERED coinbase.engine.webhooks_api.v1.WebhookEvent: type: object properties: entity: type: string id: type: string eventType: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.EventType' operationType: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.OperationType' paymentOperation: $ref: >- #/components/schemas/coinbase.engine.operator_api.v1.PaymentOperation rewardOperation: $ref: '#/components/schemas/coinbase.engine.operator_api.v1.RewardOperation' webhook: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.Webhook' source: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookSource' attempts: type: integer format: int32 maxRetries: type: integer format: int32 apiVersion: type: string createdAt: type: string format: date-time deliveredAt: type: string format: date-time metadata: type: object description: Webhook event payload details. title: WebhookEvent examples: - entity: webhook-event id: wh_event_123456789 eventType: EVENT_TYPE_PAYMENT_AUTHORIZED operationType: OPERATION_TYPE_PAYMENT paymentOperation: entity: payment-operation webhook: entity: webhook source: WEBHOOK_SOURCE_OPERATOR attempts: 0 maxRetries: 5 apiVersion: v1 createdAt: 2023-01-01T00:00:00.000Z deliveredAt: 2023-01-01T00:00:00.000Z coinbase.engine.webhooks_api.v1.WebhookSource: type: string enum: - WEBHOOK_SOURCE_OPERATOR - WEBHOOK_SOURCE_INDEXER description: List of webhook sources. title: WebhookSource examples: - WEBHOOK_SOURCE_OPERATOR coinbase.engine.webhooks_api.v1.WebhookStatus: type: string enum: - WEBHOOK_STATUS_ACTIVATED - WEBHOOK_STATUS_DEACTIVATED description: Enumeration of supported webhook statuses. title: WebhookStatus examples: - WEBHOOK_STATUS_ACTIVATED coinbase.engine.webhooks_api.v1.WebhooksApiService.PutWebhookBody: type: object properties: url: type: string description: The updated URL where webhook events will be sent. title: URL examples: - https://updated-example.com/webhooks events: type: array items: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.EventType' description: Updated types of events this webhook should receive. title: Events examples: - - EVENT_TYPE_PAYMENT_AUTHORIZED - EVENT_TYPE_PAYMENT_CAPTURED - EVENT_TYPE_PAYMENT_VOIDED - EVENT_TYPE_PAYMENT_REFUNDED - EVENT_TYPE_PAYMENT_CHARGED - EVENT_TYPE_REWARD_ALLOCATED - EVENT_TYPE_REWARD_DISTRIBUTED - EVENT_TYPE_REWARD_DEALLOCATED - EVENT_TYPE_REWARD_SENT status: $ref: '#/components/schemas/coinbase.engine.webhooks_api.v1.WebhookStatus' description: Updated status of the webhook. title: Status examples: - WEBHOOK_STATUS_INACTIVE identifier: type: string description: Updated external identifier for clients. title: Identifier examples: - updated-webhook-1 description: type: string description: Updated human-readable description of the webhook's purpose. title: Description examples: - Updated payment notifications for order processing description: Request to update an existing webhook. title: PutWebhookRequest examples: - id: wh_123456789 url: https://updated-example.com/webhooks events: - payment.authorized - payment.captured status: WEBHOOK_STATUS_INACTIVE identifier: updated-webhook-1 google.protobuf.Any: type: object properties: '@type': type: string additionalProperties: {} google.protobuf.NullValue: type: string google.rpc.Status: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: type: object $ref: '#/components/schemas/google.protobuf.Any' securitySchemes: Bearer: type: apiKey description: >- Authorization header using the Bearer scheme. Learn more about JWT tokens in the Coinbase Developer Portal. name: Authorization in: header