Skip to main content

​
Payment Intents

Payment intents provide a two-phase payment flow. You create an intent to declare the payment parameters, then confirm it when the customer is ready to pay. This is useful when you need to collect customer details or authorize a payment before processing it. If you are coming from Stripe, this will feel familiar.

​
Create a Payment Intent

POST /api/v1/payment-intents
​
amount
number
required
Amount in USD.
​
currency
string
default:"USD"
Currency code.
​
description
string
Description of the payment.
​
capture_method
string
default:"automatic"
automatic to capture immediately on confirmation, or manual to authorize only.
​
expires_in_seconds
integer
default:"86400"
Time in seconds before the intent expires. Default is 24 hours.
​
metadata
object
Arbitrary key-value pairs attached to the intent.

​
Example

curl -X POST https://api.zendfi.tech/api/v1/payment-intents \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.99,
    "description": "Enterprise license",
    "capture_method": "automatic"
  }'

​
Response

{
  "id": "pi_test_abc123",
  "client_secret": "pi_test_abc123_secret_xyz789",
  "amount": 99.99,
  "currency": "USD",
  "description": "Enterprise license",
  "status": "requires_payment",
  "capture_method": "automatic",
  "created_at": "2026-03-01T12:00:00Z",
  "expires_at": "2026-03-02T12:00:00Z"
}
​
client_secret
string
Secret used to confirm the intent from the client side. Pass this to your frontend.
​
status
string
Current intent status. See the state machine below.

​
List Payment Intents

GET /api/v1/payment-intents
Returns all payment intents for the authenticated merchant.

​
Query Parameters

​
status
string
Filter by status: requires_payment, processing, succeeded, canceled, failed.
​
limit
integer
default:"20"
Number of results to return.

​
Get a Payment Intent

GET /api/v1/payment-intents/{id}
​
id
string
required
The payment intent ID (e.g., pi_test_abc123).

​
Get Payment Intent Events

GET /api/v1/payment-intents/{id}/events
Returns the event history for a payment intent, useful for debugging the flow.

​
Confirm a Payment Intent

POST /api/v1/payment-intents/{id}/confirm
Confirms the intent and triggers payment processing. The customer wallet must be provided at this stage.
​
customer_wallet
string
required
The Solana wallet address of the customer making the payment.
​
client_secret
string
required
The client secret for verification. This must match the secret returned when the intent was created.
​
payment_type
string
Type of payment transaction (e.g., direct, gasless).
​
auto_gasless
boolean
When true, ZendFi sponsors the gas fees for this transaction.
​
metadata
object
Additional metadata to attach at confirmation time.

​
Example

curl -X POST https://api.zendfi.tech/api/v1/payment-intents/pi_test_abc123/confirm \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  }'

​
Cancel a Payment Intent

POST /api/v1/payment-intents/{id}/cancel
Cancels a payment intent that has not yet been confirmed. Once canceled, it cannot be reused.

​
Intent Status Lifecycle

StatusDescription
requires_paymentIntent created, waiting for confirmation
processingConfirmed, payment being processed
succeededPayment completed successfully
canceledIntent was canceled before confirmation
failedPayment processing failed
expiredIntent expired (default: 24 hours)

​
When to Use Payment Intents

Use payment intents when you need:
  • Two-phase flow: Separate intent creation (server-side) from confirmation (client-side).
  • Client secrets: Securely pass payment parameters to the frontend without exposing your API key.
  • Manual capture: Authorize a payment now, capture it later (e.g., after shipping).
  • Expiration control: Set custom expiration windows for long-lived checkout sessions.
For simpler flows where you just need a payment and a URL, use the Payments API directly.