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

Request

Headers

Header	Required	Value
`X-Api-Key`	Yes	Your API key
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Validation	Description
`customerPhone`	string	Yes	10-15 digits (no + sign)	Customer's phone number
`total`	decimal	Yes	Min: 500.00, Max: 15,000.00	Total amount in MAD
`currency`	string	Yes	Must be `MAD`	Currency code
`items`	array	Yes	At least 1 item	Products/services
`items[].name`	string	Yes	Max 200 chars	Product name
`items[].reference`	string	No	Max 100 chars	Product SKU
`items[].quantity`	integer	Yes	Min: 1	Quantity
`items[].unitPrice`	decimal	Yes	Min: 0.01	Unit price in MAD
`items[].categoryId`	long	No	-	Product category ID
`vendorReference`	string	No	Max 100 chars	Your order ID

Example

curl -X POST "https://api.alyapay.com/api/v1/public/partner/transactions" \
  -H "X-Api-Key: sk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "customerPhone": "212612345678",
    "total": 500.00,
    "currency": "MAD",
    "items": [
      {
        "name": "iPhone Case",
        "reference": "CASE-001",
        "quantity": 1,
        "unitPrice": 500.00
      }
    ],
    "vendorReference": "ORDER-2024-001"
  }'

Response

Success (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "orderReference": "AB12345",
  "vendorReference": "ORDER-2024-001",
  "status": "PENDING",
  "totalAmount": 500.00,
  "currency": "MAD",
  "customerPhone": "212612345678",
  "merchantName": "My Store",
  "storeName": "Downtown Branch",
  "items": [...],
  "createdAt": "2024-12-08T10:30:00Z",
  "updatedAt": null
}

Transaction Statuses

Status	Description
`PENDING`	Waiting for customer confirmation
`APPROVED`	Customer confirmed (webhook sent)
`CANCELED`	Transaction canceled
`COMPLETED`	All installments paid

Common Errors

Status	Code	Description
400	`INVALID_REQUEST`	Validation error
401	`UNAUTHORIZED`	Invalid API key
409	`DUPLICATE_VENDOR_REFERENCE`	vendorReference already exists
422	`PURCHASE_AMOUNT_EXCEEDS_LIMIT`	Credit limit exceeded

Best Practices

Always store the transaction id for future reference
Use vendorReference with your order ID for easy lookup
Validate phone format - 10-15 digits without + sign (e.g., 212612345678)
Handle duplicate errors - Check for existing transactions before retrying

Create Transaction

On this page