Stripay API Documentation
1 Create Order
All Create Order endpoints accept a POST request with Content-Type: application/json. The tables below describe the JSON fields in the request body.
1.1 Create Credit Card Order (Direct)
POST https://api.stripay.io/v1/direct/pay
Request body:
1.2 Create Credit Card Order (Inline)
POST https://api.stripay.io/v1/inline/pay
Request body:
Trigger submit payment
iframeElement.contentWindow.postMessage({ action: 'pay' })
Listen iframe events
window.addEventListener('message', (e) => {
if (e.data.sender === 'stripay') {
if (e.data.action === 'pay_success') {
location.href = e.data.value // successUrl
} else if (e.data.action === 'pay_fail') {
errorElement.innerHTML = e.data.value // error message
} else if (e.data.action === 'pay_3ds') {
location.href = e.data.value // 3ds url
} else if (e.data.action === 'pay_validate_error') {
errorElement.innerHTML = e.data.value // error message
} else if (e.data.action === 'height') {
iframeElement.style.setProperty('height', e.data.value + 'px')
}
}
})
1.3 Create Credit Card Order (Checkout)
POST https://api.stripay.io/v1/checkout/pay
Request body:
1.4 Create PayPal Order
POST https://api.stripay.io/v1/paypal/pay
Request body:
1.5 Create Order Response
Response body (JSON):
1.6 Example
POST https://api.stripay.io/v1/checkout/pay
Request body:
{
"key": "098f6bcd4621d373cade4e832627b4f6",
"merchantOrderId": "1",
"amount": 0.99,
"successUrl": "https://stripay.io/v1/success.html",
"failUrl": "https://stripay.io/v1/fail.html",
"ip": "38.94.109.229",
"email": "test@stripay.io"
}
Successful response:
{ "status": "success", "statusNote": null, "redirectUrl": "https://stripay.io/v1/success.html" }
Failed response:
{ "status": "fail", "statusNote": "No account avaliable", "redirectUrl": "https://stripay.io/v1/fail.html" }
3DS redirect:
{ "status": "3ds", "statusNote": null, "redirectUrl": "https://checkout.stripe.com/c/pay/cs_test_xxx" }
2 Get Order
2.1 Get Multiple Orders
POST https://api.stripay.io/v1/orders
Request body:
{
"key": "098f6bcd4621d373cade4e832627b4f6",
"page": 1,
"limit": 20 // range [20, 100]
}
Response body:
{
"total": 90,
"orders": [{
"id": 1,
"merchantId": 1,
"merchantOrderId": "your order id",
"amount": 1.99,
"currency": "USD",
"email": "test@stripay.io",
"ip": "102.171.177.216",
"phone": "+1xxxxxxxxxxx",
"riskScore": 65,
"status": "completed",
"statusNote": null,
"is3ds": false,
"createdAt": "2023-02-14T12:39:13.000Z",
"updatedAt": "2023-02-14T12:39:21.000Z"
}]
}
2.2 Get One Order
POST https://api.stripay.io/v1/order
Request body:
{
"key": "098f6bcd4621d373cade4e832627b4f6",
"merchantOrderId": "merchant order id", // merchantOrderId or orderId
"orderId": "stripay order id" // recommend. merchantOrderId or orderId
}
Response body:
{
"order": {
"id": 1,
"merchantId": 1,
"merchantOrderId": "your order id",
"amount": 1.99,
"currency": "USD",
"email": "test@stripay.io",
"ip": "102.171.177.216",
"phone": "+1xxxxxxxxxxx",
"riskScore": 0,
"status": "rejected",
"statusNote": "No valid payment method types for this Checkout Session.",
"is3ds": false,
"createdAt": "2023-01-10T03:39:53.000Z",
"updatedAt": "2023-01-10T03:43:37.000Z"
}
}
2.3 Order Status
- pending — Order created, not paid
- rejected — Order rejected (risk control triggered)
- 3ds — 3ds triggered, user did not complete verification
- 3dsSuccess — 3ds verification succeeded, payment failed (insufficient funds, expired card, bank rejection, etc.)
- 3dsFail — 3ds triggered, verification failed
- completed — Order paid
- canceled — Order canceled
- expired — Order expired
- refunding — Order refunding
- partiallyRefunded — Order partially refunded
- refunded — Order refunded
- disputed — Order disputed (chargeback received)
- disputeWon — Dispute won (chargeback reversed)
- disputeLost — Dispute lost
3 Webhook
If you pass notifyUrl when creating an order, a POST request with Content-Type: application/json will be sent on order status change. The webhook payload is a JSON object with the following fields:
3.1 Event Types
Webhooks are sent for the following eventType values:
3.2 Payload Example
{
"eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "order.completed",
"data": {
"id": 1,
"merchantId": 1,
"merchantOrderId": "your order id",
"amount": 1.99,
"currency": "USD",
"email": "test@stripay.io",
"ip": "102.171.177.216",
"phone": "+1xxxxxxxxxxx",
"riskScore": 0,
"status": "completed",
"statusNote": null,
"is3ds": false,
"createdAt": "2023-01-10T03:39:53.000Z",
"updatedAt": "2023-01-10T03:43:37.000Z",
"sign": "4a04cdd85f623f3785fe29655b03854f"
},
"createdAt": "2023-01-10T03:43:37.000Z",
"updatedAt": "2023-01-10T03:43:37.000Z"
}
notifyUrl must return an OK string, otherwise considered failed. Stripay retries up to 5 times: immediately, 10min, 30min, 60min, 1 day.
3.3 Verify Sign
The data.sign field is generated from the order data. To verify, sort all keys in data (excluding sign, and skipping null/'' values) lexicographically, join as key=value pairs with &, append &key= with your merchant key, then calculate md5:
function genSign (key, data) {
const sortedParams = Object.keys(data)
.filter(k => k !== 'sign' && data[k] != null && data[k] !== '')
.sort()
.map(k => `${k}=${data[k]}`)
.join('&')
return md5(`${sortedParams}&key=${key}`)
}
4 Testing
Test account and test credit card reference:
© 2025 Stripay. All rights reserved.