Payment Platform API
A robust REST API to manage payments, subscriptions, and customers via NMI.
Authentication
Authenticate your requests by including the following headers. Your API keys can be managed in the Admin Panel.
X-Client-ID: YOUR_CLIENT_ID
X-Client-Secret: YOUR_CLIENT_SECRET
Create Payment Intent
POST /api/platform/intents
Initializes a payment process. Returns a unique Checkout URL.
Parameters:
| Field | Type | Requirement | Description |
|---|---|---|---|
amount | numeric | Required | Transaction total. |
currency | string | Required | ISO 3-letter currency code (e.g. USD). |
intent_type | enum | Required | one_time or recurring. |
interval_days | integer | Required (Recurring) | Billing cycle length (Min: 1). |
email | string | Required | Customer's email address. |
customer_ref_id | string | Optional | Unique ID from your system. |
reference_id | string | Required | Unique ID from your system. |
order_items | array | Required | List of items (name, quantity, price). |
name | string | Optional | Customer's full name. |
tax | numeric | Optional | Tax amount. |
discount | numeric | Optional | Discount amount. |
success_url | string | Optional | Success URL. |
fail_url | string | Optional | Fail URL. |
cancel_url | string | Optional | Cancel URL. |
metadata | object | Optional | Key-value pairs for your internal tracking. |
cURL Example:
curl -X POST https://comatrix.paywithwallet.net/api/platform/intents \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-H "X-Client-Secret: YOUR_CLIENT_SECRET" \
-H "Idempotency-Key: 26b13c75-58c1-4d2e-8770-ae0a056aefa1" \
-H "Content-Type: application/json" \
-d '{
"amount": 80,
"currency": "USD",
"intent_type": "recurring",
"interval_days": 30,
"email": "customer@example.com",
"customer_ref_id": "123456",
"name": "John Doe",
"success_url": "https://example.com/success",
"fail_url": "https://example.com/fail",
"cancel_url": "https://example.com/cancel",
"metadata": {
"order_id": "123456"
},
"reference_id" : "123456",
"order_items": [
{
"name": "Product 1",
"quantity": 1,
"price": 50.00
},
{
"name": "Product 2",
"quantity": 2,
"price": 25.00
}
],
"tax": 10,
"discount": 5
}'Get Payment Intent
GET /api/platform/intents/{id}
Retrieve the current status and full history of an intent.
Sample Response:
{
"success": true,
"data": {
"id": "pi_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
"amount": "100.00",
"status": "succeeded",
"charges": [
{
"id": 105,
"status": "success",
"amount": "100.00",
"gateway_transaction_id": "62837482"
}
]
}
}cURL Example:
curl -X GET https://comatrix.paywithwallet.net/api/platform/intents/pi_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-H "X-Client-Secret: YOUR_CLIENT_SECRET"Cancel Payment Intent
POST /api/platform/intents/{uuid}/cancel
Cancel a pending payment intent.
cURL Example:
curl -X POST https://comatrix.paywithwallet.net/api/platform/intents/pi_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p/cancel \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-H "X-Client-Secret: YOUR_CLIENT_SECRET"Cancel Subscription
POST /api/platform/subscriptions/{uuid}/cancel
Cancel an active recurring subscription profile.
cURL Example:
curl -X POST https://comatrix.paywithwallet.net/api/platform/subscriptions/sub_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p/cancel \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-H "X-Client-Secret: YOUR_CLIENT_SECRET"Webhooks
Configure your endpoint to receive automated event notifications.
| Event | Description | Payload Example |
|---|---|---|
| payment.succeeded | A charge was successful (one-time or initial recurring). | {"intent_id": "pi_...", "charge_id": 105, "metadata": {...}} |
| payment.failed | A charge attempt failed. | {"intent_id": "pi_...", "charge_id": 106, "metadata": {...}} |
| payment.canceled | A payment intent was explicitly canceled. | {"intent_id": "pi_...", "message": "...", "metadata": {...}} |
| subscription.created | New recurring profile started. | {"subscription_id": "sub_...", "intent_id": "pi_...", "metadata": {...}} |
| subscription.renewed | Recurring charge successful. | {"subscription_id": "sub_...", "intent_id": "pi_...", "metadata": {...}} |
| subscription.failed | Recurring charge failed. | {"subscription_id": "sub_...", "intent_id": "pi_...", "message": "...", "metadata": {...}} |
| subscription.canceled | A subscription was explicitly canceled. | {"subscription_id": "sub_...", "intent_id": "pi_...", "message": "...", "metadata": {...}} |
Iframe Integration
Catch payment success events in your parent window:
window.addEventListener('message', function(event) {
if (event.data.event === 'payment.success') {
console.log('Payment ID:', event.data.intent_id);
// Your logic: redirect, show modal, etc.
}
});