Checkout

​

Authentication

  const headers = {
    'apiKey': 'YOUR_API_KEY' // Replace with your actual API key
  };

​

How to Create Payment Intent

​

Parameters

​

Payment Intent Request

​

Payment Item

​

Split Payment Details

​

Important Validation Rules

​

Interface Explanation

• amount: The total amount for the payment. This is a required field.
• items: An array of objects representing the items included in the payment. This field is optional and can be null or empty if the amount is set. If both items and amount are specified, the sum of items.price must equal the amount.
  • PaymentItem:
    • name: The name of the item. (required)
    • description: A description of the item. (optional)
    • image: URL of the item’s image. (optional)
    • quantity: The quantity of the item. Must be an integer with a minimum value of 1. (required)
    • type: The type of the item. Can be one of SERVICE, DIGITAL_PRODUCT, or PHYSICAL_PRODUCT. (required)
    • price: The price of the item. (required)
• currency: The currency for the payment. Supported values are ETB and USD. This is a required field.
• paymentIntentUniqueId: A unique identifier for the payment intent. This idempotent key is used to identify a unique payment intent shared between Fenan Pay and the merchant system. It must be unique for every payment intent. (required)
• methods: An array of strings representing the payment methods to be accepted. If this field is empty, all enabled payment methods will be selected. Supported values include TELE_BIRR_USSD, CBE, ETS_SWITCH, and M_PESA. (required). If empty array is passed, all enabled methods will be selected.
• splitPayment: An array of objects detailing the split payment among multiple beneficiaries. This field is optional and can be null.
  • SplitPaymentDetails:
    • amount: The amount to be split. Can be a percentage or a number. (required)
    • bank: The bank for the split payment. Ensure the bank supports withdrawal to avoid errors. (required)
    • splitType: The type of split. Can be PERCENTAGE or NUMBER. (required)
    • creditAccount: The credit account for the split payment. (required)
• returnUrl: The URL to redirect the user after payment completion. This should be a valid URL. (required)
• expireIn: The time in seconds before the payment intent expires. Once expired, the user can no longer make a purchase, and an Expire event will be sent as a webhook. (required)
• callbackUrl: The URL to notify the merchant system of the payment status. If null, it defaults to the webhook settings on the dashboard. This URL will notify the merchant system of events such as failure, timeout/expired, and success. (optional)
• commissionPaidByCustomer: Indicates if the commission is paid by the customer. (required)
• customerInfo: An object containing information about the customer. This field is optional but can be used to take advantage of Fenan Pay’s analytics service.
  • CustomerInfoRequestDto:
    • email: The email of the customer. (optional)
    • phone: The phone number of the customer. (optional)
    • name: The name of the customer. (optional)

1. Amount or Items Required:
   • You must provide either an amount or a non-empty list of items
   • If both are provided, the sum of item prices must equal the amount field
   • The total amount must be greater than or equal to 1.00
2. URL Requirements:
   • returnUrl must be provided and must be a valid URL format
   • callbackUrl, if provided, must be a valid URL format
3. Payment Items:
   • Each item must have a name, quantity (minimum 1), type, and price
   • Price must be a positive number with up to two decimal places
4. Split Payment:
   • If provided, each split payment must include amount, bank, splitType, and creditAccount
   • Amount must be a positive number with up to two decimal places

​

Example Request

{
  "amount": 1,
  "items": [
      {
        "name": "Product 1",
        "description": "Description of Product 1",
        "image": "https://example.shop/storage/app/public/product/thumbnail/2024-01-27-65b55b6b622aa.png",
        "quantity": 1,
        "type": "PHYSICAL_PRODUCT",
        "price": 0.5
      },
      {
          "name": "Product 2",
          "description": "Description of Product 2",
          "image": "https://example.shop/storage/app/public/product/thumbnail/2024-05-09-663c84d4ba7af.png",
          "quantity": 1,
          "type": "DIGITAL_PRODUCT",
          "price": 0.5
      }
  ],
  "currency": "ETB",
  "paymentIntentUniqueId": "95s5wfr000d39s33d01dlhs2521s8",
  "methods": ["TELE_BIRR_USSD", "CBE", "ETS_SWITCH"],
  "returnUrl": "https://fenanpay.com",
  "expireIn": 36000,
  "callbackUrl": "https://webhook.site/d3c8694f-6bc5-4375-b4df-ef3d923d0ab7",
  "commissionPaidByCustomer": false,
  "customerInfo": {
    "email": "customer@example.com",
    "phone": "251710214707",
    "name": "Customer Name"
  }
}

​

Response of the Request

​

Successful Response

  {
    "status": 200,
    "message": "Payment intent saved successfully.",
    "content": "https://checkout.fenanpay.com/payment/checkout/ad882d19-e58a-435f-9a31-fb74ed60bdb5"
  }

​

Error Response

  {
    "status": 409,
    "message": "Duplicate key violation: Key (unique_id)=(95s5wfr000d39s33d01dsslhs2521sshj81) already exists."
  }

​

Making payment