Payment Platform API

A robust REST API to manage payments, subscriptions, and customers.

Authentication

Authenticate your requests by including the following headers.


                                X-Client-ID: YOUR_CLIENT_ID (Required)

                                X-Client-Secret: YOUR_CLIENT_SECRET (Required)

                                Idempotency-Key: UUID_OR_UNIQUE_STRING (Recommended)

Response Types & Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

Code	Status	Description
200	OK	The request was successful.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Entity	Validation failed (e.g. invalid email or amount).
500	Server Error	Something went wrong on our end.

Success Response Example (200 OK)

{
    "success": true,
    "data": {
        "intent_id": "pi_...",
        "status": "succeeded"
    }
}

Standard Error Response (400, 401, 500)

{
    "success": false,
    "message": "Invalid API Key provided.",
    "data": []
}

Validation Error Response (422)

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required."
        ],
        "amount": [
            "The amount must be at least 1."
        ]
    }
}

Create Payment Intent

POST /api/platform/intents

Initializes a payment process and returns a link to the checkout page.

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.
`name`	string	Required	Customer's full name.
`reference_id`	string	Required	Unique ID from your system (Max: 100 chars, Regex: `^[a-zA-Z0-9_-]+$`).
`customer_ref_id`	string	Optional	Unique Customer ID from your system (Max: 100 chars).
`order_items`	array	Required	List of items (name, quantity, price).
`integration_type`	string	Required	`iframe` or `url`.
`success_url`	string	Req. if url	Redirect URL on success.
`cancel_url`	string	Req. if url	Redirect URL on cancel.
`tax`	numeric	Optional	Tax amount.
`discount`	numeric	Optional	Discount amount.
`metadata`	object	Optional	Key-value pairs for your internal tracking.

cURL Example:

curl -X POST https://mintro.paywithwallet.net/api/platform/intents \
  -H "X-Client-ID: YOUR_CLIENT_ID" \
  -H "X-Client-Secret: YOUR_CLIENT_SECRET" \
  -H "Idempotency-Key: 2b244b3a-897f-4f3e-ad70-69ea39635b9e" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 80,
    "currency": "USD",
    "intent_type": "recurring",
    "interval_days": 30,
    "email": "customer@example.com",
    "name": "John Doe",
    "reference_id" : "ORDER-123456",
    "customer_ref_id": "CUST-001",
    "integration_type": "iframe",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "metadata": {
        "internal_id": "999"
    },
    "order_items": [
        {
            "name": "Product 1",
            "quantity": 1,
            "price": 50.00
        }
    ]
  }'

Successful Response:

{
    "success": true,
    "data": {
        "intent_id": "pi_96e6c1e3-...",
        "status": "requires_payment",
        "amount": "80.00",
        "payment_url": "https://mintro.paywithwallet.net/pay/xyz123..."
    }
}

Get Payment Intent

GET /api/platform/intents/{uuid}

Retrieve the current status and details of an intent by its UUID.

Sample Response:

{
    "success": true,
    "data": {
        "intent_id": "pi_96e6c1e3-...",
        "reference_id": "ORDER-123456",
        "amount": "80.00",
        "currency": "USD",
        "status": "succeeded",
        "payment_url": "https://mintro.paywithwallet.net/pay/xyz123...",
        "type": "recurring",
        "interval_days": 30,
        "expires_at": "2024-12-31T23:59:59.000000Z",
        "tax": "10.00",
        "discount": "5.00",
        "order_items": [
             {
                "name": "Product 1",
                "quantity": 1,
                "price": "50.00"
            }
        ]
    }
}

Get Intent by Reference

GET /api/platform/intents/reference/{reference_id}

Retrieve an intent using your own system's reference_id.

Sample Response:

{
    "success": true,
    "data": {
        "intent_id": "pi_96e6c1e3-...",
        "reference_id": "ORDER-123456",
        "amount": "80.00",
        "status": "succeeded",
        ...
    }
}

Cancel Payment Intent

POST /api/platform/intents/{uuid}/cancel

Cancel a pending payment intent.

Sample Response:

{
    "success": true,
    "data": {
        "intent_id": "pi_96e6c1e3-...",
        "status": "cancelled"
    }
}

Cancel Subscription

POST /api/platform/subscriptions/{uuid}/cancel

Cancel an active recurring subscription profile.

Sample Response:

{
    "success": true,
    "data": {
        "subscription_id": "sub_7f8g9h0...",
        "status": "cancelled"
    }
}

Webhooks

Configure your endpoint to receive automated event notifications. The payload will be sent as JSON.

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 via API.	`{"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 via API.	`{"subscription_id": "sub_...", "intent_id": "pi_...", "message": "...", "metadata": {...}}`

Iframe Integration (JavaScript Events)

When using the `iframe` integration type, the checkout page emits standard `postMessage` events to your parent window. You can listen for these events to handle the usage flow.

Event Listener Example:

window.addEventListener('message', function(event) {
    const data = event.data;

    // Validate origin if necessary
    // if (event.origin !== 'https://mintro.paywithwallet.net') return;

    switch (data.event) {
        case 'payment.started':
            console.log('User opened checkout:', data.intent_id);
            break;
        case 'payment.success':
            console.log('Payment successful!', data);
            // Close modal, redirect user, etc.
            break;
        case 'payment.failed':
            console.error('Payment failed', data.message);
            break;
        case 'payment.canceled':
            console.warn('User canceled payment');
            break;
        case 'error':
            // Validation errors or system errors
            alert(data.message);
            break;
    }
});

Event Reference:

Event Name	Trigger	Data Payload
`payment.started`	When the checkout page loads.	event, message, intent_id, client_reference_id
`payment.success`	Transaction completed successfully.	event, message, intent_id, client_reference_id, status: 'succeeded'
`payment.failed`	Transaction failed or declined.	event, message, intent_id, client_reference_id, status: 'failed'
`payment.canceled`	User canceled the process or payment voided.	event, message, intent_id, client_reference_id, status: 'canceled'
`error`	Frontend validation error or system error.	type: 'error', message

API Reference

Payment Platform API

Authentication

Response Types & Error Handling

Success Response Example (200 OK)

Standard Error Response (400, 401, 500)

Validation Error Response (422)

Create Payment Intent

Parameters:

cURL Example:

Successful Response:

Get Payment Intent

Sample Response:

Get Intent by Reference

Sample Response:

Cancel Payment Intent

Sample Response:

Cancel Subscription

Sample Response:

Webhooks

Iframe Integration (JavaScript Events)

Event Listener Example:

Event Reference: