Create Transaction

Create a new Buy Now, Pay Later transaction. The transaction starts in PENDING status and the customer receives an SMS to confirm.

Endpoint

POST /api/v1/public/partner/transactions

Authentication

X-Service-Key: <your-api-key>

Request body

Field	Type	Required	Description
`customerPhone`	string	Yes	Customer phone — digits only, no `+` (e.g. `212612345678`)
`total`	decimal	Yes	Total amount in MAD
`currency`	string	Yes	Must be `MAD`
`items`	array	Yes	At least 1 item required
`items[].name`	string	Yes	Product name (max 200 chars)
`items[].reference`	string	No	Product SKU (max 100 chars)
`items[].quantity`	integer	Yes	Min: 1
`items[].unitPrice`	decimal	Yes	Unit price in MAD (min: 0.01)
`items[].categoryId`	long	No	Product category ID
`vendorReference`	string	No	Your unique order ID — returned in webhooks for matching

Example

curl -X POST https://api.alyapay.com/api/v1/public/partner/transactions \
  -H "X-Service-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerPhone": "212612345678",
    "total": 1500.00,
    "currency": "MAD",
    "vendorReference": "ORDER-001",
    "items": [
      {
        "name": "iPhone 15",
        "reference": "SKU-001",
        "quantity": 1,
        "unitPrice": 1500.00,
        "categoryId": 1
      }
    ]
  }'

Response `201`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "orderReference": "ALY-20260626-001",
  "vendorReference": "ORDER-001",
  "status": "PENDING",
  "totalAmount": 1500.00,
  "currency": "MAD",
  "customerPhone": "212612345678",
  "merchantName": "Acme",
  "storeName": "Main Store",
  "items": [
    {
      "id": "uuid",
      "name": "iPhone 15",
      "reference": "SKU-001",
      "quantity": 1,
      "unitPrice": 1500.00,
      "categoryId": 1
    }
  ],
  "createdAt": "2026-06-26T09:00:00Z",
  "updatedAt": null
}

Transaction statuses

Status	Description
`PENDING`	Created, waiting for customer confirmation
`APPROVED`	Customer confirmed — webhook sent
`CANCELED`	Canceled by merchant or system
`EXPIRED`	Customer did not confirm within the agreed expiry period

Common errors

Status	Description
`400`	Validation error (missing field, invalid phone format)
`401`	Invalid or missing API key
`409`	`vendorReference` already exists for this merchant
`422`	Business rule violation (amount limits, inactive merchant, credit limit)

Create Transaction

On this page