Client API Integration Guide

1) Base URL

Use this base URL for all examples on this page:

https://merchant.letsia-pay.com/client-api

2) Authentication

• All requests (except login) require the header Authorization: Bearer <ACCESS_TOKEN>.
• The token is generated through POST /login.
• The account must be API Enabled from the control panel.
• API mode (live or sandbox) is tied to the token at login time.

3) Response Shape (Unified)

Most successful responses follow this structure:

{
  "status": true,
  "message": "Any message",
  "data": {}
}

Error responses generally look like:

{
  "status": false,
  "message": "Error message"
}

4) Modes

live: normal production behavior.

sandbox: test-only behavior.

• Invoice code starts with SBOX-.
• Payment links are internal fake sandbox links.
• No real external gateway is triggered.
• Use sandbox simulate endpoint to move invoice statuses.

5) Endpoint: Login

Method: POST

URL: /login

Auth: No

Request:

{
  "email": "[email protected]",
  "password": "secret",
  "device_name": "postman"
}

Success (200):

{
  "status": true,
  "message": "Login successful.",
  "data": {
    "token_type": "Bearer",
    "access_token": "TOKEN_VALUE",
    "user": {
      "id": 1,
      "name": "Client Name",
      "email": "[email protected]",
      "api_mode": "live"
    }
  }
}

Errors: 401 invalid credentials, 403 API disabled.

6) Endpoint: Create Invoice

Method: POST

URL: /invoices

Auth: Yes

Request:

{
  "customer_email": "[email protected]",
  "amount": 150.75,
  "title": "New Payment",
  "payment_methods": [1, 2]
}

Success (201):

{
  "status": true,
  "message": "Invoice created successfully.",
  "data": {
    "id": 1001,
    "invoice_number": "UID-1-001",
    "code": "INV-70062780-f4ba-44d2-b77b-aba5693686a5",
    "status": "pending",
    "title": "New Payment",
    "amount": "150.75",
    "customer_email": "[email protected]",
    "public_payment_url": "https://merchant.letsia-pay.com/invoice/INV-70062780-f4ba-44d2-b77b-aba5693686a5",
    "payment_methods": [
      {
        "id": 1,
        "name": "PayPal",
        "payment_link": null,
        "payment_status": "pending"
      }
    ],
    "created_at": "2026-02-13T10:00:00+00:00",
    "updated_at": "2026-02-13T10:00:00+00:00"
  }
}

Error: 422 validation/business input errors.

7) Endpoint: Invoice Status

Method: GET

URL: /invoices/{reference}/status

Auth: Yes

reference accepts invoice_number or code.

Success (200):

{
  "status": true,
  "message": "Invoice status retrieved.",
  "data": {
    "id": 1001,
    "invoice_number": "UID-1-001",
    "code": "INV-70062780-f4ba-44d2-b77b-aba5693686a5",
    "status": "pending",
    "title": "New Payment",
    "amount": "150.75",
    "customer_email": "[email protected]",
    "public_payment_url": "https://merchant.letsia-pay.com/invoice/INV-70062780-f4ba-44d2-b77b-aba5693686a5",
    "payment_methods": [
      {
        "id": 1,
        "name": "PayPal",
        "payment_link": "https://www.paypal.com/invoice/p/#XXXX",
        "payment_status": "pending"
      }
    ],
    "created_at": "2026-02-13T10:00:00+00:00",
    "updated_at": "2026-02-13T10:05:00+00:00"
  }
}

Error: 404 invoice not found.

8) Endpoint: Request Refund

Method: POST

URL: /invoices/{reference}/refund

Auth: Yes

Rule: invoice must be paid.

Success (200):

{
  "status": true,
  "message": "Refund request submitted.",
  "data": {
    "invoice_number": "UID-1-001",
    "status": "request_refund"
  }
}

Errors: 404 invoice not found, 422 invoice not paid or no paid method.

9) Endpoint: Cancel Invoice

Method: POST

URL: /invoices/{reference}/cancel

Auth: Yes

Rule: invoice must be paid.

Success (200):

{
  "status": true,
  "message": "Invoice cancelled successfully.",
  "data": {
    "invoice_number": "UID-1-001",
    "status": "CANCELLED"
  }
}

Errors: 404 invoice not found, 422 invoice not paid.

10) Endpoint: Refresh Invoice

Method: POST

URL: /invoices/{reference}/refresh

Auth: Yes

Behavior: updates invoice/payment methods updated_at for background reprocessing.

Success (200):

{
  "status": true,
  "message": "Invoice refresh triggered.",
  "data": {
    "invoice_number": "UID-1-001",
    "status": "pending"
  }
}

Errors: 404 invoice not found, 422 refresh constraints.

11) Endpoint: Sandbox Simulate Status

Method: POST

URL: /sandbox/invoices/{reference}/simulate

Auth: Yes

Available only when api_mode = sandbox.

Request:

{
  "status": "paid"
}

Allowed values: pending, paid, failed.

Success (200):

{
  "status": true,
  "message": "Sandbox status updated.",
  "data": {
    "invoice_number": "SBOX-UID-1-001",
    "status": "paid"
  }
}

Errors: 404 invoice not found, 422 account not sandbox or invalid status.

12) cURL Quick Start

Login:

curl -X POST "https://merchant.letsia-pay.com/client-api/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email":"[email protected]",
    "password":"secret",
    "device_name":"postman"
  }'

Create invoice:

curl -X POST "https://merchant.letsia-pay.com/client-api/invoices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN_VALUE" \
  -d '{
    "customer_email":"[email protected]",
    "amount":150.75,
    "title":"New Payment",
    "payment_methods":[1,2]
  }'

Invoice status:

curl -X GET "https://merchant.letsia-pay.com/client-api/invoices/UID-1-001/status" \
  -H "Authorization: Bearer TOKEN_VALUE"

13) Integration Notes

• Store access_token securely.
• Handle 401/403 by forcing re-login or notifying user.
• Treat 422 responses as business/validation errors.
• Do not assume payment_link appears immediately in live mode.
• In sandbox mode, invoice code starts with SBOX- and links are test-only.