Expresspay

​

ExpressPay: Direct Payment Processing

ExpressPay offers a streamlined approach to payment processing. This integration method is designed for scenarios where:

• You have already implemented a checkout process in your application.
• A specific payment method has been pre-selected or is preferred.
• You aim to minimize the number of steps in the payment flow.

With ExpressPay, you can initiate payment requests directly, bypassing the need for a separate checkout page. This results in a more efficient and focused payment experience for your customers.

If you need a modern, standard, intuitive checkout for your platform, Fenan offers a hosted checkout solution. The general flow is that the customer will be redirected to the Fenan checkout page, and after the payment is completed, the customer will be redirected back to your platform. You do this by creating a payment intent first, for which you will get a checkout URL for that specific transaction, and you need to redirect the user to that page. After the payment is done, the customer is redirected back, and a webhook is sent to your server.

​

Authentication

Setting API Key in Headers. Learn more about API Key here.

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

​

How to Create Express payment

To create a payment intent, all you need to do is send a POST HTTP call to the appropriate endpoint based on your environment. Include the apiKey in the request headers and provide the required parameters in the body as described in the Parameters section.

• Test
• Prod

​

Parameters

The following tables describe the fields required for creating a express payment.

​

Express Payment Request

​

Payment Item

​

Split Payment Details

​

Customer Info Request

​

Interface Explanation

The PaymentIntentRequest interface is used to create a payment intent with Fenan Pay. Below is an explanation of each field:

• 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: A string representing the payment method. Supported values include TELE_BIRR, CBE, ETS_SWITCH, and M_PESA. (required).
• 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 minutes 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)

​

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",
    "splitPayment": [],
    "returnUrl": "https://fenanpay.com",
    "expireIn": 36000,
    "callbackUrl": "https://webhook.site/d3c8694f-6bc5-4375-b4df-ef3d923d0ab7",
    "commissionPaidByCustomer": false
  }

​

Response of the Request

When you make a request to the Fenan Pay API, you will receive a response indicating the status of your request. Below are examples of both a successful response and an error response.

​

Successful Response

Successful response will have a status code of 200.

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

​

Error Response

Error response will have a status code of 4xx.

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

​

Payment Response

The Payment Response object contains the details of the response from the payment service provider. Below is a table describing the fields in the PspPaymentResponseDto object.

PaymentStatus is an enumeration that represents the possible statuses of a payment. The possible values are:

• SUCCESS
• FAILURE

​

Making payment

After the payment is done, the customer will be redirected back to your platform. You will receive a webhook notification of the payment status. Learn more about webhooks here.