Backend Integration

Your backend calls two AlyaPay API endpoints: one to create payment sessions, and one to verify transactions.

Important: Never expose your API key in frontend code. All API calls must be made from your backend.

API Base URLs

Use the appropriate base URL for your environment:

Environment	Base URL
Sandbox	`https://sandbox-api.alyapay.com`
Production	`https://api.alyapay.com`

Use development URL with test API keys during development, and production URL with live keys when going live.

Endpoint 1: Create Session

Create a payment session for checkout.

POST /api/v1/public/sessions

Headers

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json

Request Body

{
  "total": "1799.00",
  "currency": "MAD",
  "items": [
    {
      "id": "PRODUCT_123",
      "name": "Wireless Headphones",
      "price": 1799,
      "quantity": 1
    }
  ]
}

Parameters

Field	Type	Required	Description
`total`	string	Yes	Total order amount
`currency`	string	Yes	Currency code: `MAD`
`items`	array	Yes	Array of order items
`items[].id`	string	Yes	Unique product identifier
`items[].name`	string	Yes	Product name
`items[].price`	number	Yes	Unit price
`items[].quantity`	number	Yes	Quantity

Success Response (200 OK)

{
  "session_token": "eyJraWQiOiJzZXNzaW9uLTIwMjUtMDEi...",
  "expires_in": 3600,
  "session_id": "sess_abc123xyz789"
}

Response Fields:

session_token - Pass this to your frontend (valid for 1 hour)
expires_in - Token lifetime in seconds (3600 = 1 hour)
session_id - Session identifier for reference

Error Responses

Status	Error	Description
400	`INVALID_AMOUNT`	Amount must be greater than 0
400	`INVALID_CURRENCY`	Unsupported currency code
400	`INVALID_ITEMS`	Items array is missing or invalid
400	`AMOUNT_MISMATCH`	Total doesn't match sum of items
401	`INVALID_API_KEY`	API key is invalid or missing
429	`RATE_LIMIT_EXCEEDED`	Too many requests (max 100 per 15 min)

Endpoint 2: Verify Transaction

Verify transaction status after payment completes.

GET /api/v1/public/transactions/{transaction_id}/status

Headers

X-Session-Token: SESSION_TOKEN // from step 1

URL Parameters

Parameter	Description
`transaction_id`	Transaction ID from payment callback

Success Response (200 OK)

{
  "status": "APPROVED",
  "transaction_id": "c335bbf0-ae49-42e7-9a7e-c1a6888406dd",
  "payment_intent_id": "8d17b9b9-aea9-4c7e-b753-8223938d7de6",
  "amount": 1799.00,
  "currency": "MAD",
  "merchant_name": "Your Store",
  "store_name": "Your Store",
  "customer_phone": "212650296165",
  "created_at": "12/10/25 16:28:21",
  "updated_at": "12/10/25 16:28:21"
}

Response Fields:

status - Transaction status (APPROVED, PENDING, or CANCELED)
transaction_id - Unique transaction identifier
payment_intent_id - Payment intent identifier
amount - Transaction amount (number)
currency - Currency code (e.g., MAD)
merchant_name - Your merchant name
store_name - Your store name
customer_phone - Customer's phone number
created_at - Transaction creation timestamp
updated_at - Last update timestamp

Transaction Statuses

Status	Description	What to Do
`APPROVED`	Payment successful	✅ Complete and ship order
`PENDING`	Payment not approved	❌ Don't fulfill order
`CANCELED`	Payment not approved	❌ Don't fulfill order

Error Responses

Status	Error	Description
401	`INVALID_SESSION_TOKEN`	Session token is invalid or expired
404	`TRANSACTION_NOT_FOUND`	Transaction doesn't exist

Security Best Practices

1. Store API Key Securely

# Use environment variables
ALYAPAY_API_KEY=sk_live_your_key_here

Never commit API keys to version control or expose them in frontend code.

2. Validate Input

Before creating a session:

Verify total is positive
Check items array is not empty
Ensure total matches sum of items
Validate currency is supported

3. Always Verify Transactions

Never trust frontend events alone. Always verify transaction status with the API before fulfilling orders.

❌ Bad: Frontend says "paid" → Ship order
✅ Good: Frontend event → Backend verifies → Ship order

4. Use HTTPS

Always use HTTPS in production to protect API keys and session tokens in transit.

5. Handle Errors

Implement proper error handling:

Log errors for debugging
Return user-friendly messages
Retry on transient failures
Monitor for repeated failures

Need Help?

See Frontend Integration for SDK setup
Check Events for payment callbacks
View API Reference for complete details

Email support: support@alyapay.com

Backend Integration

On this page