1.0 - Create Checkout Session

Description

Handles a payment initiation request to the ArifPay API by creating a checkout session. This is only the checkout session creation step, not the full payment lifecycle.

🛑 Note for Production: Set BASE_URL to http://gateway.arifpay.net/api in production environments.

Environment Variables

| Variable | Description | Default | | -------------- | -------------------------------------------- | -------------------------------- | | BASE_URL | Base URL of the ArifPay API | http://gateway.arifpay.net/api | | CHECKOUT_URL | Path segment to initiate a checkout session | /checkout/session | | API_KEY | Bearer token for authenticating with ArifPay | (must be set by user) |

Required Fields (User must provide)

| Field | Type | Description | | --------------- | ------ | --------------------------------------------------- | | phone | String | Must start with 251 and be exactly 12 digits long | | cancelUrl | String | Redirect URL if user cancels payment | | errorUrl | String | Redirect URL on error | | notifyUrl | String | Webhook to receive payment updates | | successUrl | String | Redirect URL on successful payment | | items | Array | List of items to be paid for | | beneficiaries | Array | List of recipient bank accounts |

Optional Fields (Set or auto-generated by the package)

| Field | Type | Default | Description | | ---------------- | ------ | -------------------------------------- | ---------------------------------------------- | | email | String | undefined | Optional payer email | | nonce | String | uuidv4() | Unique ID for tracking session | | paymentMethods | Array | Predefined ArifPay payment method list | Options like TELEBIRR, CBE, MPESSA, etc. | | expireDate | String | +1 hour from now (ISO UTC) | Defaults to current time + 1 hour | | lang | String | "en" | Language for ArifPay UI |

How to Use the SDK

import { createCheckoutSession } from "arifpay-express";

const result = await createCheckoutSession({
  cancelUrl: "https://example.com",
  phone: "251954926213",
  errorUrl: "http://error.com",
  notifyUrl: "https://example.com",
  successUrl: "http://example.com",
  items: [
    {
      name: "ምዝ",
      quantity: 1,
      price: 2,
      description: "Fresh Banana"
    }
  ],
  beneficiaries: [
    {
      accountNumber: "01320811436100",
      bank: "AWINETAA",
      amount: 2.0
    }
  ]
});

Sample Request Body (All Fields)

{
  "cancelUrl": "https://example.com",
  "phone": "251954926213",
  "email": "[email protected]",
  "nonce": "AAAa1289832asdrs",
  "errorUrl": "http://error.com",
  "notifyUrl": "https://example.com",
  "successUrl": "http://example.com",
  "paymentMethods": [
    "TELEBIRR", "AWASH", "AWASH_WALLET", "PSS", "CBE",
    "AMOLE", "BOA", "KACHA", "TELEBIRR_USSD", "HELLOCASH", "MPESSA"
  ],
  "expireDate": "2025-02-01T03:45:27",
  "items": [
    {
      "name": "ምዝ",
      "quantity": 1,
      "price": 2,
      "description": "Fresh Corner premium Banana.",
      "image": "https://4.imimg.com/data4/KK/KK/GLADMIN-/product-8789_bananas_golden-500x500.jpg"
    }
  ],
  "beneficiaries": [
    {
      "accountNumber": "01320811436100",
      "bank": "AWINETAA",
      "amount": 2.0
    }
  ],
  "lang": "EN"
}

Sample Request Body (Only Required Fields)

{
  "cancelUrl": "https://example.com",
  "phone": "251954926213",
  "errorUrl": "http://error.com",
  "notifyUrl": "https://example.com",
  "successUrl": "http://example.com",
  "items": [
    {
      "name": "ምዝ",
      "quantity": 1,
      "price": 2,
      "description": "Fresh Banana"
    }
  ],
  "beneficiaries": [
    {
      "accountNumber": "01320811436100",
      "bank": "AWINETAA",
      "amount": 2.0
    }
  ]
}

Validations

• All required fields must be present.

• phone must follow Ethiopian format: start with 251 and contain exactly 12 digits.

• expireDate must be a valid ISO 8601 timestamp in the future.

• items must include:

  • name: string
  • quantity: number
  • price: number

• beneficiaries must include:

  • accountNumber: string
  • bank: string
  • amount: number

Responses

✅ 200 OK

{
  "message": "Success",
  "data": { /* ArifPay response object */ }
}

❌ 400 Bad Request

{
  "message": "Invalid phone number. Use 2519xxxxxxxx"
}

{
  "message": "All fields are required"
}

❌ 500 Internal Server Error

{
  "message": "Internal server error"
}

Function Summary

/**
 * Handles payment initiation via ArifPay API.
 *
 * - Validates required fields from the request body
 * - Checks if the phone number is a valid Ethiopian number
 * - Ensures the expiration date is in the future
 * - Confirms all item quantities and prices are numeric
 * - Uses a unique nonce to prevent duplicate requests
 * - Sends a POST request to ArifPay's checkout/session endpoint
 * - Returns the ArifPay response or an appropriate error message
 *
 * @param {Object} req - Express request object containing payment data
 * @param {Object} res - Express response object used to return API response
 */