API Reference

SamaPay APIs are built using REST principles. We use standard HTTP response codes, authentication, and verbs.

Base URL

The base URL for all API requests is: https://api.samapay.gm/v1

Authentication

Identify your requests with your API Key. Your secret key should be kept strictly confidential.

---

Shared Schemas

The Transaction Object

Every payment transaction returned by the API follows this structure:

{
  "id": "tx_881293",
  "amount": 2500,
  "currency": "GMD",
  "status": "completed",
  "provider": "wave",
  "customer": {
    "phone": "220-777-1234",
    "name": "Ebrima Jatta"
  },
  "metadata": {
    "order_id": "9981"
  },
  "created_at": "2024-10-25T14:30:00Z"
}

---

Error Handling

SamaPay uses standard HTTP status codes to indicate the success or failure of an API request.

• 200 - OK: Everything worked as expected.
• 400 - Bad Request: The request was unacceptable, often due to a missing parameter.
• 401 - Unauthorized: No valid API key provided.
• 402 - Request Failed: The parameters were valid but the request failed (e.g., payment declined).
• 429 - Too Many Requests: You have hit the rate limit.

---

Active Endpoints

All endpoints are categorized by their primary function:

• Checkout API: Handle customer payments.
• Payout API: Disburse merchant funds.
• Transactions API: Retrieve payment details.
• Authentication API: Tokenize sensitive data.