API Documentation — 4Poch Gateway

Introduction

The 4Poch Payment Gateway API lets businesses accept payments from 4Poch users. Integrate once and accept payments via 4Poch HTG, 4Poch USD, MonCash, and USDT (TRC20).

Base URL: https://4poch.com/api/gateway/v1

All requests and responses are in JSON format. Timestamps are ISO 8601.

Authentication

Every API request requires two headers. You get these from your Gateway Dashboard.

Live Keys

X-API-Key:     gw_your_api_key_here
X-Secret-Key:  sk_your_secret_key_here

Test Keys (Sandbox)

X-API-Key:     test_gw_your_test_api_key_here
X-Secret-Key:  test_sk_your_test_secret_key_here

Sandbox mode: Use test keys (starting with test_gw_) for development. Test payments are auto-completed with no real funds moved. Switch between live and test mode in your Gateway Settings.

Both key pairs are generated when your business account is created. Keep your Secret Keys private — never share them or expose them in client-side code.

Errors

The API uses standard HTTP status codes. All errors return a JSON object:

{
  "success": false,
  "message": "Description of what went wrong"
}

Code	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API keys
404	Not found — resource doesn't exist
429	Too many requests — rate limit exceeded
500	Internal server error

Webhooks

When a payment is completed, we'll send a POST request to your webhook_url with a signed payload. Use the signature to verify the request came from 4Poch.

Payload

{
  "event":        "payment.completed",
  "payment_id":   "4poch_abc123...",
  "amount":       100.00,
  "currency":     "HTG",
  "net_amount":   92.50,
  "fee":          7.50,
  "status":       "completed",
  "payment_method": "4poch_htg",
  "customer_email": "user@example.com",
  "timestamp":    "2026-06-02T12:00:00+00:00",
  "signature":    "sha256_hmac_hex"
}

Verification

Generate the HMAC-SHA256 signature using your Secret Key and compare it to the signature field:

// PHP
$expected = hash_hmac('sha256', json_encode($payload), $secretKey);

// Node.js
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', secretKey)
  .update(JSON.stringify(payload)).digest('hex');

Create Payment

Initialize a new payment. Returns a checkout_url to redirect the customer to.

POST /gateway/v1/payments Create a new payment

Request Body

Parameter	Type		Description
amount	number	required	Payment amount (min 0.01)
currency	string	required	`HTG` or `USD`
payment_method	string	required	One of: `4poch_htg`, `4poch_usd`, `moncash`, `usdt`
redirect_url	string	optional	URL to redirect after successful payment
cancel_url	string	optional	URL to redirect if payment is cancelled
customer_email	string	optional	Payer's email
customer_phone	string	optional	Payer's phone number
customer_name	string	optional	Payer's name
description	string	optional	Order description (max 500 chars)

Example Request

curl -X POST https://4poch.com/api/gateway/v1/payments \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "currency": "HTG",
    "payment_method": "4poch_htg",
    "redirect_url": "https://example.com/thank-you",
    "customer_email": "customer@example.com"
  }'

Response

{
  "success": true,
  "message": "Payment created successfully.",
  "data": {
    "payment_id":   "4poch_a1b2c3d4e5f6...",
    "checkout_url": "https://4poch.com/gateway/pay/4poch_a1b2c3d4e5f6...",
    "amount":       150.00,
    "currency":     "HTG",
    "fee":          8.75,
    "net_amount":   141.25,
    "status":       "pending",
    "expires_at":   "2026-06-02T14:00:00+00:00"
  }
}

Get Payment Status

Check the status of a payment by its ID.

GET /gateway/v1/payments/{payment_id} Get payment details

Example Request

curl https://4poch.com/api/gateway/v1/payments/4poch_a1b2c3d4e5f6 \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "data": {
    "payment_id":     "4poch_a1b2c3d4e5f6",
    "amount":         150.00,
    "currency":       "HTG",
    "net_amount":     141.25,
    "fee":            8.75,
    "payment_method": "4poch_htg",
    "status":         "completed",
    "customer_email": "customer@example.com",
    "created_at":     "2026-06-02T12:00:00+00:00",
    "updated_at":     "2026-06-02T12:02:00+00:00"
  }
}

Refund Payment

Refund a completed payment. The net amount is returned to your balance.

POST /gateway/v1/payments/{payment_id}/refund Refund a payment

Example Request

curl -X POST https://4poch.com/api/gateway/v1/payments/4poch_a1b2c3d4e5f6/refund \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "message": "Payment refunded successfully."
}

List Transactions

Retrieve a paginated list of your transactions with optional filters.

GET /gateway/v1/transactions List all transactions

Query Parameters

Parameter	Type	Description
status	string	Filter by: `pending`, `processing`, `completed`, `failed`, `refunded`
payment_method	string	Filter by method: `4poch_htg`, `moncash`, etc.
from	date	Start date (YYYY-MM-DD)
to	date	End date (YYYY-MM-DD)
per_page	integer	Results per page (default: 20)

Example Request

curl "https://4poch.com/api/gateway/v1/transactions?status=completed&per_page=5" \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "data": [
    {
      "payment_id":     "4poch_...",
      "amount":         150.00,
      "currency":       "HTG",
      "payment_method": "4poch_htg",
      "fee":            8.75,
      "net_amount":     141.25,
      "status":         "completed",
      "created_at":     "2026-06-02T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page":     5,
    "total":        42,
    "last_page":    9
  }
}

Get Balance

Check your current gateway balance and total received amount.

GET /gateway/v1/balance Check balance

Example Request

curl https://4poch.com/api/gateway/v1/balance \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "data": {
    "balance":        1542.75,
    "total_received": 1542.75,
    "currency":       "HTG"
  }
}

List Payment Methods

Get all available payment methods with their details.

GET /gateway/v1/methods Available methods

Example Request

curl https://4poch.com/api/gateway/v1/methods \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "data": [
    { "code": "4poch_htg", "name": "4Poch HTG", "currency": "HTG" },
    { "code": "moncash", "name": "MonCash", "currency": "HTG" }
  ]
}

Test Webhook

Send a test webhook to your configured webhook URL to verify your integration.

POST /gateway/v1/webhook/test Test webhook delivery

Example Request

curl -X POST https://4poch.com/api/gateway/v1/webhook/test \
  -H "X-API-Key: gw_your_api_key" \
  -H "X-Secret-Key: sk_your_secret_key"

Response

{
  "success": true,
  "message": "Webhook delivered successfully.",
  "http_status": 200,
  "response_body": "..."
}

4Poch Gateway API v1

Introduction

Authentication

Live Keys

Test Keys (Sandbox)

Errors

Webhooks

Payload

Verification

Create Payment

Request Body

Example Request

Response

Get Payment Status

Example Request

Response

Refund Payment

Example Request

Response

List Transactions

Query Parameters

Example Request

Response

Get Balance

Example Request

Response

List Payment Methods

Example Request

Response

Test Webhook

Example Request

Response