Skip to main content

Payment Intents

Payment Intent is the Core Object in the Finternet Payment Gateway’s Payment API. It facilitates the exchange and confirmation of payment information between buyer and merchant and also enables interaction with the smart modules that host the conditional payment logic.

What is a Payment Intent?​

A payment intent is a record that:

  • Represents a payment request
  • Tracks payment status through its lifecycle
  • Contains all information needed to process the payment
  • Links blockchain transactions to fiat settlements

Payment Intent Object​

{
  "id": "intent_2xYz9AbC123",
  "object": "payment_intent",
  "status": "SUCCEEDED",
  "amount": "100.00",
  "currency": "USDC",
  "type": "DELIVERY_VS_PAYMENT",
  "description": "Order #12345",
  "settlementMethod": "OFF_RAMP_MOCK",
  "settlementDestination": "bank_account_123",
  "settlementStatus": "IN_PROGRESS",
  "contractAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f42318",
  "transactionHash": "0xabc123def456...",
  "chainId": 11155111,
  "typedData": { ... },
  "signature": "0x1234...",
  "signerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f42318",
  "phases": [
    {
      "phase": "SIGNATURE_VERIFICATION",
      "status": "COMPLETED",
      "timestamp": 1704067200
    },
    {
      "phase": "BLOCKCHAIN_CONFIRMATION",
      "status": "COMPLETED",
      "timestamp": 1704067250
    },
    {
      "phase": "SETTLEMENT",
      "status": "IN_PROGRESS",
      "timestamp": 1704067300
    }
  ],
  "metadata": {
    "orderId": "ORD-123",
    "customerId": "CUST-456"
  },
  "paymentUrl": "https://pay.fmm.finternetlab.io/?intent=intent_2xYz9AbC123",
  "created": 1704067200,
  "updated": 1704067300
}

Core Fields​

id​

Unique identifier for the payment intent. Format: intent_ followed by alphanumeric characters.

status​

Current status of the payment. See Status & Lifecycle for all statuses.

amount​

Payment amount as a string. Always includes decimal places (e.g., "100.00").

currency​

Currency code. Supported: USDC, USDT, DAI.

type​

Payment type. Options:

  • DELIVERY_VS_PAYMENT - Conditional payment with delivery verification

settlementMethod​

How funds are converted to fiat. Options:

  • OFF_RAMP_MOCK - Mock settlement (testing)
  • OFF_RAMP_TO_RTP - Real-Time Payment settlement
  • OFF_RAMP_TO_BANK - Bank transfer settlement

settlementDestination​

Where fiat funds are sent (bank account, RTP identifier, etc.).

Phases​

Payment intents track progress through multiple phases:

PhaseDescription
SIGNATURE_VERIFICATIONVerifying EIP-712 signature
BLOCKCHAIN_CONFIRMATIONWaiting for blockchain transaction confirmation
ESCROW_LOCKEDFunds locked in escrow (DvP only)
AWAITING_DELIVERY_PROOFWaiting for delivery confirmation (DvP only)
SETTLEMENTProcessing fiat settlement

Each phase has a status: IN_PROGRESS, COMPLETED, or FAILED.

Metadata​

Store custom data with payment intents:

{
  "metadata": {
    "orderId": "ORD-123",
    "customerId": "CUST-456",
    "invoiceNumber": "INV-789",
    "customField": "any value"
  }
}

Metadata is:

  • ✅ Stored with the payment intent
  • ✅ Returned in all API responses
  • ✅ Included in webhooks
  • ✅ Searchable in audit logs

Payment URL​

Every payment intent includes a paymentUrl that directs payers to complete payment:

https://pay.fmm.finternetlab.io/?intent=intent_2xYz9AbC123

This URL:

  • Opens the payment interface
  • Pre-fills payment details
  • Handles wallet connection
  • Processes payment execution

Lifecycle​

INITIATED
  ↓
REQUIRES_SIGNATURE (optional)
  ↓
PROCESSING
  ↓
SUCCEEDED
  ↓
SETTLED
  ↓
FINAL

See Status & Lifecycle for detailed state transitions.

Creating Payment Intents​

curl https://api.fmm.finternetlab.io/v1/payment-intents \
  -H "X-API-Key: sk_test_your_key" \
  -X POST \
  -d '{
    "amount": "100.00",
    "currency": "USDC",
    "type": "DELIVERY_VS_PAYMENT",
    "settlementMethod": "OFF_RAMP_MOCK",
    "settlementDestination": "bank_account_123"
  }'

Retrieving Payment Intents​

curl https://api.fmm.finternetlab.io/v1/payment-intents/intent_2xYz9AbC123 \
  -H "X-API-Key: sk_test_your_key"