Non-custodial, high-velocity checkout protocol for stablecoin commerce.
Accept stablecoin payments on Solana.
MardiPay gives developers a simple API for creating hosted USDC checkout experiences on Solana.
curl -X POST https://mardipay.in/api/v1/payment_intents \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-d '{"amount": "4.50","original_amount": "5.00","discount": "10% promotional discount","currency": "USDC","description": "MardiPay Cap (10% Off)","image_url": "https://mardipay.in/Landing/cap.png"}'
Devnet Scope: MardiPay is currently available on Solana Devnet using Devnet USDC. All API requests settle testnet tokens with zero real-world cost.
Get started
Quickstart
Complete an end-to-end USDC payment with four simple steps.
1Get an API key
Navigate to your Merchant Dashboard under the API Keys tab. Generate a Devnet key formatted as mp_test_xxx. Keep this key confidential and store it in your server-side environment variables.
2Create a Payment Intent
Make a POST request to https://mardipay.in/api/v1/payment_intents with your amount and order metadata:
curl -X POST https://mardipay.in/api/v1/payment_intents \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-H "Idempotency-Key: order_123" \-d '{"amount": "4.50","original_amount": "5.00","discount_code": "STORE10","currency": "USDC","description": "MardiPay Cap (10% Off)","image_url": "https://mardipay.in/Landing/cap.png","metadata": {"order_id": "order_123","discount_percent": 10}}'
3Open checkout_url
The API response returns a checkout_url formatted as https://mardipay.in/checkout/pi_xxx. Redirect your buyer to this hosted page to complete payment.
4Verify payment confirmation
When the customer finishes payment or returns to your application, poll or retrieve the Payment Intent to verify on-chain confirmation:
curl -X GET https://mardipay.in/api/v1/payment_intents/pi_k39f9a2 \-H "Authorization: Bearer mp_test_xxx"
How MardiPay works
Understand the Payment Intent lifecycle from request to on-chain confirmation.
/api/v1/payment_intents
Create a payment intent and receive a hosted checkout URL.
Authorization: Bearer mp_test_xxxRequest Body
| Property key | Type | Description |
|---|---|---|
| amount * | String | The exact amount to charge in USDC (e.g. "4.50" or "25.00"). |
| currency * | String | Currently "USDC" on Solana Devnet. |
| original_amount | String | Pre-discount amount (e.g. "5.00"). Renders strikethrough price and savings on hosted checkout. |
| discount_code | String | Promotional coupon code applied to this session (e.g. "STORE10"). |
| product_id | String | Catalog product ID created via POST /v1/products for server-authoritative pricing. |
| plan_interval | String | Billing frequency for subscriptions: "monthly" or "yearly". |
| description | String | Product name or payment title displayed on the hosted checkout page. |
| image_url | String | Image URL rendered on the hosted checkout summary. |
| metadata | Object | Optional key-value pairs (max 4KB) for order references and tracking. |
curl -X POST https://mardipay.in/api/v1/payment_intents \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-H "Idempotency-Key: order_123" \-d '{"amount": "4.50","original_amount": "5.00","discount_code": "STORE10","currency": "USDC","description": "MardiPay Cap (10% Off)","image_url": "https://mardipay.in/Landing/cap.png","metadata": {"order_id": "order_123","discount_percent": 10}}'
{"id": "pi_k39f9a2","object": "payment_intent","amount": "4.50","original_amount": "5.00","discount_amount": "0.50","discount_code": "STORE10","currency": "USDC","status": "created","checkout_url": "https://mardipay.in/checkout/pi_k39f9a2","payment_reference": "7dK9...Wp2","description": "MardiPay Cap (10% Off)","image_url": "https://mardipay.in/Landing/cap.png","metadata": {"order_id": "order_123","discount_percent": 10},"created_at": 1790000000000,"expires_at": 1790000300000}
/api/v1/payment_intents/:id
Retrieve the latest status, signature, and confirmation state of a payment.
curl -X GET https://mardipay.in/api/v1/payment_intents/pi_k39f9a2 \-H "Authorization: Bearer mp_test_xxx"
{"id": "pi_123","object": "payment_intent","amount": "5.00","currency": "USDC","status": "confirmed","checkout_url": "https://mardipay.in/checkout/pi_123","tx_signature": "5abc...421","payer": "7xyz...891","created_at": 1790000000000,"confirmed_at": 1790000020000}
Payment Statuses
| Status | Description |
|---|---|
| created | Payment intent created; waiting for customer to visit checkout. |
| processing | Payment detected or pending confirmation on Solana Devnet. |
| confirmed | USDC transfer verified on-chain. Funds settled to receiving wallet. |
| expired | Payment session expired before on-chain confirmation. |
| cancelled | Customer cancelled or lapsed the checkout session. |
/api/v1/products
Create one-time digital goods or recurring subscription products with monthly pricing and discounted annual upfront billing.
Authorization: Bearer mp_test_xxxRequest Parameters (POST /api/v1/products)
| Property key | Type | Description |
|---|---|---|
| name * | String | Display title of the product or subscription plan. |
| billing_type * | String | "one_time" for one-off sales or "subscription" for recurring plans. |
| price / monthly_price | Number | Price in USDC (e.g. 50.00). Required for one-time products or monthly subscription baseline. |
| has_annual_plan | Boolean | Enable annual upfront subscription billing alongside monthly option. |
| annual_discount_percent | Number | Percentage discount (0-99%) applied when customers choose annual upfront payment. |
| annual_price | Number | Custom annual price overriding automatic percentage calculation. |
| image_url | String | Product visual displayed during hosted checkout. |
curl -X POST https://mardipay.in/api/v1/products \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-d '{"name": "Pro Membership","description": "Access to pro developer analytics & features","billing_type": "subscription","monthly_price": 50.00,"has_annual_plan": true,"annual_discount_percent": 15,"currency": "USDC"}'
{"id": "prod_k92n01x","object": "product","name": "Pro Membership","description": "Access to pro developer analytics & features","price": "50.00","billing_type": "subscription","monthly_price": "50.00","annual_price": "510.00","annual_discount_percent": 15,"has_monthly_plan": true,"has_annual_plan": true,"currency": "USDC","is_active": true,"created_at": 1790000000000}
/api/v1/products
List all active and inactive products registered under your merchant account.
curl -X GET https://mardipay.in/api/v1/products \-H "Authorization: Bearer mp_test_xxx"
{"object": "list","data": [{"id": "prod_k92n01x","object": "product","name": "Pro Membership","price": "50.00","billing_type": "subscription","monthly_price": "50.00","annual_price": "510.00","annual_discount_percent": 15,"has_monthly_plan": true,"has_annual_plan": true,"currency": "USDC","is_active": true,"created_at": 1790000000000}]}
/api/v1/discounts/validate
Server-authoritative coupon validation. Validates eligibility, expiry, per-customer limits, and returns verified savings.
Authorization: Bearer mp_test_xxxRequest Parameters (POST /api/v1/discounts/validate)
| Property key | Type | Description |
|---|---|---|
| code * | String | Discount code to validate (e.g. "STORE10"). |
| amount * | Number | Current order subtotal in USDC (e.g. 5.00). |
| product_id | String | Optional catalog product ID for restricted coupon verification. |
| plan_interval | String | Plan cycle ("monthly" or "yearly") for subscription coupons. |
curl -X POST https://mardipay.in/api/v1/discounts/validate \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-d '{"code": "STORE10","amount": 5.00,"plan_interval": "monthly"}'
{"valid": true,"code": "STORE10","discount_type": "percentage","discount_value": 10,"discount_amount": 0.50,"final_amount": 4.50,"duration": "once"}
/api/v1/discounts
Programmatically create coupon codes with expiration dates, maximum redemption counts, and plan applicability.
curl -X POST https://mardipay.in/api/v1/discounts \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-d '{"code": "STORE10","discount_type": "percentage","discount_value": 10,"max_redemptions": 100,"max_redemptions_per_customer": 1,"duration": "once"}'
{"id": "disc_89fa21","object": "discount_code","code": "STORE10","discount_type": "percentage","discount_value": 10,"max_redemptions": 100,"times_redeemed": 0,"is_active": true,"created_at": 1790000000000}
Customize Checkout
Developers control the checkout content directly through the API request. MardiPay hosts the payment UI—no frontend integration or wallet adapter required.
{"amount": "25.00","currency": "USDC","description": "Premium Hoodie","image_url": "https://example.com/hoodie.png","metadata": {"order_id": "ORDER-123"}}
Discounts & Subscriptions
MardiPay supports promotional discounts, server-verified coupon codes, and recurring billing cycles directly on the hosted checkout page.
Live Showcase: 10% Discount on MardiPay Cap
On the live demo store (/store), the MardiPay Cap features an active 10% promotional discount ($4.50 USDC down from $5.00 USDC regular price with code STORE10).
curl -X POST https://mardipay.in/api/v1/payment_intents \-H "Authorization: Bearer mp_test_xxx" \-H "Content-Type: application/json" \-d '{"amount": "4.50","original_amount": "5.00","discount": "10% promotional discount","discount_code": "STORE10","currency": "USDC","description": "MardiPay Cap (10% Off)","image_url": "https://mardipay.in/Landing/cap.png","metadata": {"item": "MardiPay Vintage Washed Cap","discount_percent": 10,"promo": "STORE10"}}'
Recurring Subscriptions & Plan Toggles
When an intent references a subscription product, the hosted checkout UI displays monthly and annual billing toggles. If the product has an annual discount configured, the customer sees their annual savings highlighted automatically.
Idempotency
Pass an Idempotency-Key header to safely retry requests without creating duplicate charges.
Idempotency-Key: <unique_order_identifier>If a network disconnect occurs while creating a payment, re-send the request with the identical key. MardiPay returns the existing Payment Intent without generating duplicates.
API Errors
Standard HTTP status codes and uniform JSON error structures.
{"error": {"type": "invalid_request","code": "invalid_amount","message": "Amount must be greater than 0."}}
Supported Error Codes
| Error Code | HTTP Status | Description |
|---|---|---|
| invalid_request | 400 | Malformed JSON body or missing required field. |
| invalid_amount | 400 | Amount is missing or not a positive decimal string. |
| invalid_currency | 400 | Unsupported currency. Only USDC is accepted. |
| invalid_api_key | 401 | API key is missing, invalid, or revoked. |
| payment_intent_not_found | 404 | No payment intent exists with the provided ID. |
| rate_limit_exceeded | 429 | Request volume exceeded 60 requests per minute. |
| internal_error | 500 | Unexpected server error while processing the request. |
Security & Limits
Guidelines for API key protection and server environment limits.
Authentication & Storage
All requests require Bearer authentication. Never expose API keys in client-side code, browser applications, or public repositories.
Rate Limits & Payload Scope
Public endpoints enforce a limit of 60 requests per minute per key. JSON payloads are capped at 64KB. Requests exceeding thresholds receive HTTP 429.