Onecloudpay API Documentation

Quick Start

New merchants can sign up and receive an API key at Merchant Signup. Payments created with that key show the merchant business name in checkout automatically.

API base URL:

https://onecloudpay.com/api.php

Payment endpoint: https://onecloudpay.com/api.php/v1/payments

Development API key configured in config.php:

vp_test_1234567890abcdef

Before using production, change the API key in config.php, enable HTTPS, and keep storage/ inaccessible from the browser.

1. Create a payment

curl -X POST "https://onecloudpay.com/api.php/v1/payments" \
  -H "Authorization: Bearer vp_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "currency": "USD",
    "merchant_reference": "ORDER-1001",
    "description": "Order 1001",
    "return_url": "https://merchant.example/success",
    "cancel_url": "https://merchant.example/cancel",
    "customer": {
      "name": "Demo Customer",
      "email": "[email protected]"
    }
  }'

2. Redirect the customer to checkout

Use data.checkout_url from the response to redirect the customer or build a payment button.

Authentication

Every endpoint under /v1 requires an API key sent as a Bearer token.

Authorization: Bearer vp_test_1234567890abcdef

Keep API keys on the server side only. Do not place keys in browser JavaScript. API keys created from signup are automatically tied to the merchant name.

Endpoints

GET`/health`

Check whether the API is running. This endpoint does not require an API key.

curl "https://onecloudpay.com/api.php/health"

POST`/v1/payments`

Create a new payment request.

Field	Type	Required	Description
`amount`	number	Yes	Payment amount, up to 2 decimal places.
`currency`	string	No	Default: `USD`.
`merchant_reference`	string	No	Order number or reference from the merchant system.
`description`	string	No	Payment description.
`return_url`	url	No	URL after payment succeeds or remains pending.
`cancel_url`	url	No	URL when the customer cancels.
`customer`	object	No	`name`, `email`, `phone`.
`metadata`	object	No	Additional merchant data.

Response

{
  "data": {
    "id": "pay_1234567890abcdef",
    "object": "payment",
    "amount": "50.00",
    "currency": "USD",
    "status": "pending",
    "merchant_name": "Demo Merchant",
    "merchant_reference": "ORDER-1001",
    "checkout_url": "https://onecloudpay.com/payment.php?payment_id=pay_1234567890abcdef",
    "payment_url": "https://onecloudpay.com/payment.php?payment_id=pay_1234567890abcdef",
    "created_at": "2026-05-29T04:00:00+00:00",
    "expires_at": "2026-05-30T04:00:00+00:00"
  }
}

GET`/v1/payments/{payment_id}`

Retrieve payment details and current status.

curl "https://onecloudpay.com/api.php/v1/payments/pay_1234567890abcdef" \
  -H "Authorization: Bearer vp_test_1234567890abcdef"

GET`/v1/payments`

List payments for the current merchant. Supports limit and merchant_reference.

curl "https://onecloudpay.com/api.php/v1/payments?limit=10" \
  -H "Authorization: Bearer vp_test_1234567890abcdef"

POST`/v1/payments/{payment_id}/cancel`

Cancel a payment that is still in pending status.

curl -X POST "https://onecloudpay.com/api.php/v1/payments/pay_1234567890abcdef/cancel" \
  -H "Authorization: Bearer vp_test_1234567890abcdef"

Payment Statuses

Status	Meaning
`pending`	The payment was created and is waiting for the customer to enter checkout.
`requires_review`	The customer submitted the checkout form; the merchant should review it or continue with a real payment processor.
`approved`	The payment was approved by admin.
`rejected`	The payment was rejected by admin.
`cancelled`	The payment was cancelled.

Error Format

{
  "error": {
    "code": "validation_failed",
    "message": "Payment request is invalid.",
    "details": {
      "amount": "Amount must be greater than zero."
    }
  }
}

HTTP	Code	Description
400	`invalid_json`	The request body is not valid JSON.
401	`unauthorized`	The API key is missing or invalid.
404	`not_found`	The endpoint or payment was not found.
409	`invalid_status`	The action is not valid for the current status.
422	`validation_failed`	A request field is invalid.

Security Notes

No Raw Card API

Merchants should not send card numbers or CVV through the API. Use hosted checkout URLs only.

API Keys

Create a new production key in config.php, and rotate keys when needed.

HTTPS

Production must use HTTPS before merchants or customers use it.

Storage

storage/ contains payment state and the audit log. Do not serve this directory publicly.