1 Create Order

1.1 Create Credit Card Order (Direct)

POST https://api.stripay.io/v1/direct/pay

{
  sku: '1',
  title: 'test',
  quantity: '1',
  amount: '9.9',
  image: 'https://xxx.com/test.jpeg',
  url: 'https://xxx.com/product/test/'
}

1.2 Create Credit Card Order (Inline)

POST https://api.stripay.io/v1/inline/pay

{
  sku: '1',
  title: 'test',
  quantity: '1',
  amount: '9.9',
  image: 'https://xxx.com/test.jpeg',
  url: 'https://xxx.com/product/test/'
}

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') {
      // payment success, e.data.value is successUrl
      location.href = e.data.value
    } else if (e.data.action === 'pay_fail') {
      // payment failed, e.data.value is error message
      errorElement.innerHTML = e.data.value
    } else if (e.data.action === 'pay_3ds') {
      // trigger 3DS, e.data.value is iframe height
      iframeElement.style.setProperty('height', e.data.value + 'px')
    } else if (e.data.action === 'pay_validate_error') {
      // credit card verification failed, e.data.value is error message
      errorElement.innerHTML = e.data.value
    } else if (e.data.action === 'height') {
      // iframe height changed, e.data.value is iframe height
      iframeElement.style.setProperty('height', e.data.value + 'px')
    }
  }
})

1.3 Create Credit Card Order (Checkout)

POST https://api.stripay.io/v1/checkout/pay

{
  sku: '1',
  title: 'test',
  quantity: '1',
  amount: '9.9',
  image: 'https://xxx.com/test.jpeg',
  url: 'https://xxx.com/product/test/'
}

1.4 Create PayPal Order

POST https://api.stripay.io/v1/paypal/pay

{
  sku: '1',
  title: 'test',
  quantity: '1',
  amount: '9.9',
  image: 'https://xxx.com/test.jpeg',
  url: 'https://xxx.com/product/test/'
}

1.5 Create Order Response

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": "[email protected]"
}

Successful response body:

{
    "status": "success",
    "statusNote": null,
    "redirectUrl": "https://stripay.io/v1/success.html"
}

Failed response body:

{
    "status": "fail",
    "statusNote": "No account avaliable",
    "redirectUrl": "https://stripay.io/v1/fail.html"
}

Need to redirect to the URL of the payment/3DS page:

{
    "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 of [20, 100]
}

Response body:

{
    "total": 90,
    "orders": [
        {
            "id": 1,
            "merchantId": 1,
            "merchantOrderId": "your order id",
            "amount": 1.99,
            "currency": "USD",
            "successUrl": "https://stripay.io/v1/success.html",
            "failUrl": "https://stripay.io/v1/fail.html",
            "email": "[email protected]",
            "ip": "102.171.177.216",
            "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 and orderId, choose one
    "orderId": "stripay order id" // Recommend. merchantOrderId and orderId, choose one
}

Response body:

{
    "order": {
        "id": 1,
        "merchantId": 1,
        "merchantOrderId": "your order id",
        "amount": 1.99,
        "currency": "USD",
        "successUrl": "https://stripay.io/v1/success.html",
        "failUrl": "https://stripay.io/v1/fail.html",
        "email": "[email protected]",
        "ip": "102.171.177.216",
        "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

The order status has the following values:

• pending: Order created, not paid
• rejected: Order rejected, such as refusing payment after risk control is triggered
• 3ds: 3ds is triggered, but the user does not complete the 3ds verification process and gives up payment
• 3dsSuccess: 3ds is triggered and 3ds verification is successful, but payment fails due to insufficient credit card balance/credit card expiration/card issuing bank rejection, etc.
• 3dsFail: 3ds is triggered, but 3ds verification fails
• completed: Order paid
• canceled: Order canceled
• expired: Order expired
• refunded: Order refunded
• disputed: Order disputed

3 Webhook

If you pass notifyUrl when creating an order, a POST request will be made to notifyUrl when the order status changes (completed/refunded/disputed), with the following content:

{
    "id": 1,
    "merchantId": 1,
    "merchantOrderId": "your order id",
    "amount": 1.99,
    "currency": "USD",
    "successUrl": "https://stripay.io/v1/success.html",
    "failUrl": "https://stripay.io/v1/fail.html",
    "email": "[email protected]",
    "ip": "102.171.177.216",
    "riskScore": 0,
    "status": "completed",
    "statusNote": null,
    "is3ds": false,
    "createdAt": "2023-01-10T03:39:53.000Z",
    "updatedAt": "2023-01-10T03:43:37.000Z",
    "sign": "4a04cdd85f623f3785fe29655b03854f"
}

notifyUrl needs to return an OK string, otherwise it is considered a failure. Stripay will try up to 5 times: immediately, after 10 minutes, after 30 minutes, after 60 minutes, after one day.

3.1 Verify Sign

Sort all parameter keys in lexicographic order, concatenate their values, and finally concatenate the merchant key to calculate md5. eg:

function genSign (key, data) {
  let signStr = ''

  Object.keys(data)
    .sort()
    .forEach(key => {
      if (key === 'sign') {
        return
      }
      const value = data[key]
      if (value === '' || value == null) {
        return
      }
      signStr += value
    })

  return md5(signStr + key)
}

4 Testing

Test account and test credit card reference:

• Stripe: https://stripe.com/docs/testing
• Adyen: https://docs.adyen.com/development-resources/testing/test-card-numbers
• PayPal: https://developer.paypal.com/tools/sandbox