MardiPay Docs Banner
MARDIPAY // CORE
MardiPay Developer Suitev1.0-devnet

Non-custodial, high-velocity checkout protocol for stablecoin commerce.

Overview

Accept stablecoin payments on Solana.

MardiPay gives developers a simple API for creating hosted USDC checkout experiences on Solana.

1.Create a payment intent with a single HTTP request.
2.Send your customer to the hosted checkout URL.
3.Customer pays from any supported Solana wallet (Phantom, Solflare, Backpack) or MardiPay.
4.Verify payment confirmation on-chain.
1
2
3
4
5
6
7
8
9
10
11
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

Guide

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:

1
2
curl -X GET https://mardipay.in/api/v1/payment_intents/pi_k39f9a2 \
-H "Authorization: Bearer mp_test_xxx"
Architecture

How MardiPay works

Understand the Payment Intent lifecycle from request to on-chain confirmation.

1Your Server
→
2POST /v1/payment_intents
→
3Hosted Checkout
→
4Solana USDC
→
5GET Status
Your backend creates the payment intent, provides the customer with the hosted checkout URL, and monitors payment status. MardiPay inspects the Solana Devnet blockchain in real time using unique transaction references and updates the intent state immediately upon confirmation.
POST

/api/v1/payment_intents

Create a payment intent and receive a hosted checkout URL.

Authentication HeaderAuthorization: Bearer mp_test_xxx

Request Body

Property keyTypeDescription
amount *StringThe exact amount to charge in USDC (e.g. "4.50" or "25.00").
currency *StringCurrently "USDC" on Solana Devnet.
original_amountStringPre-discount amount (e.g. "5.00"). Renders strikethrough price and savings on hosted checkout.
discount_codeStringPromotional coupon code applied to this session (e.g. "STORE10").
product_idStringCatalog product ID created via POST /v1/products for server-authoritative pricing.
plan_intervalStringBilling frequency for subscriptions: "monthly" or "yearly".
descriptionStringProduct name or payment title displayed on the hosted checkout page.
image_urlStringImage URL rendered on the hosted checkout summary.
metadataObjectOptional key-value pairs (max 4KB) for order references and tracking.
Request Payload
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
}
}'
Response (201 Created)
JSON201 Created
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"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
}
GET

/api/v1/payment_intents/:id

Retrieve the latest status, signature, and confirmation state of a payment.

Example Request
1
2
curl -X GET https://mardipay.in/api/v1/payment_intents/pi_k39f9a2 \
-H "Authorization: Bearer mp_test_xxx"
Example Response (200 OK)
JSON200 OK
1
2
3
4
5
6
7
8
9
10
11
12
{
"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

StatusDescription
createdPayment intent created; waiting for customer to visit checkout.
processingPayment detected or pending confirmation on Solana Devnet.
confirmedUSDC transfer verified on-chain. Funds settled to receiving wallet.
expiredPayment session expired before on-chain confirmation.
cancelledCustomer cancelled or lapsed the checkout session.
POST

/api/v1/products

Create one-time digital goods or recurring subscription products with monthly pricing and discounted annual upfront billing.

Authentication HeaderAuthorization: Bearer mp_test_xxx

Request Parameters (POST /api/v1/products)

Property keyTypeDescription
name *StringDisplay title of the product or subscription plan.
billing_type *String"one_time" for one-off sales or "subscription" for recurring plans.
price / monthly_priceNumberPrice in USDC (e.g. 50.00). Required for one-time products or monthly subscription baseline.
has_annual_planBooleanEnable annual upfront subscription billing alongside monthly option.
annual_discount_percentNumberPercentage discount (0-99%) applied when customers choose annual upfront payment.
annual_priceNumberCustom annual price overriding automatic percentage calculation.
image_urlStringProduct visual displayed during hosted checkout.
Create Product Request
1
2
3
4
5
6
7
8
9
10
11
12
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"
}'
Response (201 Created)
JSON201 Created
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"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
}
GET

/api/v1/products

List all active and inactive products registered under your merchant account.

1
2
curl -X GET https://mardipay.in/api/v1/products \
-H "Authorization: Bearer mp_test_xxx"
JSON200 OK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"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
}
]
}
POST

/api/v1/discounts/validate

Server-authoritative coupon validation. Validates eligibility, expiry, per-customer limits, and returns verified savings.

Authentication HeaderAuthorization: Bearer mp_test_xxx

Request Parameters (POST /api/v1/discounts/validate)

Property keyTypeDescription
code *StringDiscount code to validate (e.g. "STORE10").
amount *NumberCurrent order subtotal in USDC (e.g. 5.00).
product_idStringOptional catalog product ID for restricted coupon verification.
plan_intervalStringPlan cycle ("monthly" or "yearly") for subscription coupons.
Validation Request
1
2
3
4
5
6
7
8
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"
}'
Validation Response (200 OK)
JSON200 OK
1
2
3
4
5
6
7
8
9
{
"valid": true,
"code": "STORE10",
"discount_type": "percentage",
"discount_value": 10,
"discount_amount": 0.50,
"final_amount": 4.50,
"duration": "once"
}
POST

/api/v1/discounts

Programmatically create coupon codes with expiration dates, maximum redemption counts, and plan applicability.

1
2
3
4
5
6
7
8
9
10
11
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"
}'
JSON201 Created
1
2
3
4
5
6
7
8
9
10
11
{
"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
}
Hosted Experience

Customize Checkout

Developers control the checkout content directly through the API request. MardiPay hosts the payment UI—no frontend integration or wallet adapter required.

Payload Specification
JSON
1
2
3
4
5
6
7
8
9
{
"amount": "25.00",
"currency": "USDC",
"description": "Premium Hoodie",
"image_url": "https://example.com/hoodie.png",
"metadata": {
"order_id": "ORDER-123"
}
}
How values map to the hosted checkout:
• amount: Formatted as the primary bold headline in USDC.
• description: Displayed as the product or order title.
• image_url: Displayed as the product thumbnail.
• metadata: Safely preserved on the payment record for reconciliation.
Commerce & Pricing

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).

How promotional discounts render on hosted checkout:
Original:$5.00 USDC
Discount:10% OFF (-$0.50 USDC)
Final Total:$4.50 USDC
Promotional Checkout Intent Creation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.

• Server-Authoritative Math: Client-tampered amounts are strictly discarded. MardiPay calculates exact base units (6 decimals) from the database record.
• Coupon Stacking Prevention: A coupon cannot be stacked or redeemed past its limit or expiration timestamp.
• On-Chain Settlement: Payment confirms on Solana Devnet in seconds and triggers post-payment fulfillment events.
Reliability

Idempotency

Pass an Idempotency-Key header to safely retry requests without creating duplicate charges.

HeaderIdempotency-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.

Errors

API Errors

Standard HTTP status codes and uniform JSON error structures.

Error Response Structure
JSON400 Bad Request
1
2
3
4
5
6
7
{
"error": {
"type": "invalid_request",
"code": "invalid_amount",
"message": "Amount must be greater than 0."
}
}

Supported Error Codes

Error CodeHTTP StatusDescription
invalid_request400Malformed JSON body or missing required field.
invalid_amount400Amount is missing or not a positive decimal string.
invalid_currency400Unsupported currency. Only USDC is accepted.
invalid_api_key401API key is missing, invalid, or revoked.
payment_intent_not_found404No payment intent exists with the provided ID.
rate_limit_exceeded429Request volume exceeded 60 requests per minute.
internal_error500Unexpected server error while processing the request.
Security

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.