Contract Interactions

Contract interactions let a business register approved EVM contracts or Solana programs, then expose a constrained execution surface to its backend. Use this when PayChain needs to help a business safely call smart contracts as part of a payment, treasury, or automation workflow.

Important note: Contract interactions are not the same as normal invoice collection. Invoices track customer payments. Contract interactions are approved automation actions that may read from or write to a chain program or contract.

When to use contract interactions

A fintech app needs a controlled on-chain execution after a payment.
A marketplace wants to trigger a settlement contract.
A product needs safe reads from EVM contracts or Solana programs.
A backend needs repeatable execution with audit history.

EVM contracts

For EVM contracts, an authorized dashboard user registers:

Contract address.
Chain and network.
ABI.
Allowed functions or published actions.
Optional execution constraints.

Developer-facing usage should focus on the approved action, required inputs, quote or simulation result, and terminal execution status.

Security note: Do not expose private keys, signing credentials, or infrastructure credentials in your integration. Developers should call PayChain’s approved action surface.

Solana programs

For Solana programs, an authorized dashboard user registers:

Program ID.
Network.
Anchor IDL where available.
Approved instructions or account reads.
Account mappings required by published actions.

Solana actions should be documented with expected accounts, simulation behavior, and terminal execution status.

Dashboard setup vs backend execution

Step	Who does it	Purpose
Register contract or program	Authorized dashboard user	Defines the on-chain surface PayChain can understand.
Review functions or instructions	Authorized dashboard user	Confirms what can be read or executed.
Publish approved action	Authorized dashboard user	Creates a constrained action for backend usage.
Quote or simulate	Backend developer	Checks cost, expected behavior, and failure risk before execution.
Execute action	Backend developer	Runs only the approved action through PayChain.
Reconcile history	Dashboard or backend user	Tracks status, tx hash, errors, and business impact.

Reads vs writes

Reads query contract or program state and do not move funds by themselves.
Writes broadcast transactions and can consume sponsored gas credits when PayChain sponsors the network cost.

Gas credit note: Sponsored contract execution can reduce the business gas-credit balance. If credits are insufficient, eligible sponsored execution may pause until the business tops up.

Recommended developer flow

Confirm the business has an approved contract integration.
Fetch the published actions available to the API key or backend service.
Validate your own product state before requesting execution.
Quote or simulate when the endpoint supports it.
Execute with an idempotency key.
Store the PayChain execution ID and request ID.
Wait for terminal execution status or webhook notification.
Reconcile the transaction hash and business object state.

REST examples

Contract execution uses approved action IDs. The action must already be published from the dashboard and the API key must be scoped for contract execution.

Quote an approved action

curl -X POST "$PAYCHAIN_API_URL/contract-actions/$PAYCHAIN_CONTRACT_ACTION_ID/quote" \
  -H "x-api-key: $PAYCHAIN_CONTRACT_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order_123_contract_quote" \
  -d '{
    "params": {
      "amount": "25.00",
      "recipient": "0x0000000000000000000000000000000000000000"
    },
    "metadata": {
      "orderId": "order_123"
    }
  }'

Execute an approved action

curl -X POST "$PAYCHAIN_API_URL/contract-actions/$PAYCHAIN_CONTRACT_ACTION_ID/execute" \
  -H "x-api-key: $PAYCHAIN_CONTRACT_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: order_123_contract_execute" \
  -d '{
    "params": {
      "amount": "25.00",
      "recipient": "0x0000000000000000000000000000000000000000"
    },
    "metadata": {
      "orderId": "order_123"
    }
  }'

Fetch execution status

curl "$PAYCHAIN_API_URL/contract-executions/exec_123" \
  -H "x-api-key: $PAYCHAIN_CONTRACT_API_KEY"

Idempotency note: Treat contract writes like financial actions. Use an idempotency key, store the execution ID, and fetch execution state before retrying after a timeout.

Example use cases

Payment-triggered contract action

A merchant collects a fixed invoice, waits for invoice.paid, fetches the canonical invoice, then executes an approved contract action tied to the order. Use this when:

The payment and contract action are separate steps.
Your backend must validate order state before execution.
The contract action should only happen after confirmed settlement.

Treasury automation action

An approved user publishes a constrained action for a known token or settlement contract. The backend quotes and executes only that published action when your approval rules pass. Use this when:

The business wants repeatable treasury movement.
Your team needs audit history.
Developers should not manage private signing credentials.

Read-only contract view

A backend or dashboard can query approved read functions to display contract state without broadcasting a transaction. Use this when:

You need contract state for reconciliation.
You need a pre-execution check.
You need visibility without moving funds.

What to document for each action

Action name.
Chain and network.
Contract address or program ID.
Function or instruction.
Required parameters.
Required accounts, where relevant.
Whether it is read-only or writes to chain.
Whether it can consume sponsored gas credits.
Expected success state.
Common failure states.
Required API key or auth mode.

Common mistakes

Treating a contract execution as invoice payment confirmation.
Exposing private signing credentials or other secrets.
Retrying a write action without an idempotency key.
Letting client-side code choose unsafe contract parameters.
Ignoring simulation or quote results before execution.
Forgetting that sponsored execution can become gas-blocked.

Start here

Developers

Go live

Contract interactions

Contract Interactions

When to use contract interactions

EVM contracts

Solana programs

Dashboard setup vs backend execution

Reads vs writes

Recommended developer flow

REST examples

Quote an approved action

Execute an approved action

Fetch execution status

Example use cases

Payment-triggered contract action

Treasury automation action

Read-only contract view

What to document for each action

Common mistakes

​Contract Interactions

​When to use contract interactions

​EVM contracts

​Solana programs

​Dashboard setup vs backend execution

​Reads vs writes

​Recommended developer flow

​REST examples

​Quote an approved action

​Execute an approved action

​Fetch execution status

​Example use cases

​Payment-triggered contract action

​Treasury automation action

​Read-only contract view

​What to document for each action

​Common mistakes

Contract Interactions

When to use contract interactions

EVM contracts

Solana programs

Dashboard setup vs backend execution

Reads vs writes

Recommended developer flow

REST examples

Quote an approved action

Execute an approved action

Fetch execution status

Example use cases

Payment-triggered contract action

Treasury automation action

Read-only contract view

What to document for each action

Common mistakes