Expresspay

ExpressPay: Direct Payment Processing

Ideal for applications with a predefined payment flow or a single preferred payment method.

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

If you are coming from the checkout process, everything remains the same except for the baseUrl, method parameter and the Response. You will need to specify one payment method in the method parameter. Every other parameter remains the same. Here method is string only accepting one payment type.

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.

https://api.fenanpay.com/api/v1/payment/express/sandbox/pay

Parameters

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

Express Payment Request

Field	Type	Description	Required
amount	number	The total amount for the payment. Must be a positive number with up to two decimal places.	true*
items	array of objects	List of items included in the payment.	false
currency	string	The currency for the payment.	true
paymentIntentUniqueId	string	Unique identifier for the payment intent.	true
paymentLinkUniqueId	string	Unique identifier for the payment link.	false
phoneNumber	string	Phone number for the payment (required for M-PESA).	false
debitAccount	string	Debit account for the payment.	false
description	string	Description of the payment.	false
method	string	Payment method code (TELE_BIRR_USSD, CBE, ETS_SWITCH, M_PESA).	true
splitPayment	array of objects	Details for splitting the payment among multiple beneficiaries.	false
returnUrl	string	URL to redirect the user after payment completion (required for non-M-PESA).	true*
expireIn	integer	Time in seconds before the payment intent expires.	true
callbackUrl	string	URL to notify the merchant system of the payment status. Must be a valid URL format.	false
commissionPaidByCustomer	boolean	Indicates if the commission is paid by the customer.	true
customerInfo	object	Information about the customer.	false
testMode	object	Test mode configuration (only for sandbox environment).	true*

* returnUrl is required for all payment methods except M-PESA
* testMode is only required in sandbox environment * Either amount or items must be provided

Payment Item

Field	Type	Description	Required
name	string	Name of the item.	true
description	string	Description of the item.	false
image	string	URL of the item’s image.	false
quantity	integer	Quantity of the item.	true
type	string	Type of the item (SERVICE, DIGITAL_PRODUCT, PHYSICAL_PRODUCT).	true
price	number	Price of the item.	true

Split Payment Details

Field	Type	Description	Required
amount	number	Amount to be split.	true
bank	string	Bank for the split payment.	true
splitType	string	Type of split (PERCENTAGE, NUMBER).	true
creditAccount	string	Credit account for the split payment.	true

Customer Info Request

Field	Type	Description	Required
email	string	Email of the customer.	false
phone	string	Phone number of the customer.	false
name	string	Name of the customer.	false

Test Mode (Sandbox Only)

Field	Type	Description	Required
testModeType	string	Type of test mode (ACTUAL_TEST, SIMULATED_TEST).	true
simulationStatus	string	Simulation status (SUCCESS, FAILED, etc.). Required when testModeType is SIMULATED_TEST.	conditional

Interface Explanation

The ExpressPaymentRequestDto interface is used to create an express payment with Fenan Pay. Below is an explanation of each field:

amount: The total amount for the payment. This is a required field with a positive number and up to two decimal places.
items: An array of objects representing the items included in the payment. This field is optional, but either items or amount must be provided.
- 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)
paymentLinkUniqueId: A unique identifier for the payment link. (optional)
phoneNumber: Phone number for the payment. Required for M-PESA payments if not provided in customerInfo. (optional)
debitAccount: Debit account for the payment. (optional)
description: Description of the payment. (optional)
method: A string representing the payment method code. Supported values include TELE_BIRR_USSD, CBE, ETS_SWITCH, and M_PESA. (required)
splitPayment: An array of objects detailing the split payment among multiple beneficiaries. This field is optional.
- 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 for all payment methods except M-PESA.
expireIn: The time in seconds before the payment intent expires. Must be at least 5 seconds. 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. Required for M-PESA if not provided in the phoneNumber field. (optional)
  - name: The name of the customer. (optional)
testMode: An object containing test mode configuration. Required only in sandbox environment.
- TestModeDto:
  - testModeType: The type of test mode. Can be ACTUAL_TEST or SIMULATED_TEST. (required)
  - simulationStatus: The simulation status. Required when testModeType is SIMULATED_TEST. (conditional)

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": "91dhsd52aaadssaaaaaaagaqwa",
  "method": "TELE_BIRR_USSD",
  "returnUrl": "http://cbe.com",
  "expireIn": 36000,
  "callbackUrl": "https://webhook.site/644fdd21-885e-4c51-a2bd-1926e4c30c3b",
  "commissionPaidByCustomer": false,
  "customerInfo": {
      "email": "test@gmail.com",
      "phone": "251710214707",
      "name": "customer name"
  },
  "testMode": {
      "testModeType": "ACTUAL_TEST",
      "simulationStatus": "FAILED"
  }
}

M-PESA Payment Example

{
  "amount": 1,
  "currency": "ETB",
  "paymentIntentUniqueId": "91dhsd52aaadssaaaaaaagaqwa",
  "method": "M_PESA",
  "phoneNumber": "251710214707",
  "expireIn": 36000,
  "callbackUrl": "https://webhook.site/644fdd21-885e-4c51-a2bd-1926e4c30c3b",
  "commissionPaidByCustomer": false,
  "customerInfo": {
      "email": "test@gmail.com",
      "name": "customer name"
  },
  "testMode": {
      "testModeType": "ACTUAL_TEST"
  }
}

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."
  }

Field	Description
status	Status of the response
message	Message indicating success or error
content	Checkout is object Payment Response

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.

Field	Type	Description	Required
paymentUrl	String	URL to redirect the user for completing payment.	false
transactionId	String	Unique identifier for the transaction.	false
status	PaymentStatus	Status of the payment.	true
message	String	Message indicating success or error.	false

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.

Important Validation Rules

Amount or Items Required: You must provide either an amount or a non-empty list of items.
Return URL Requirement: A valid returnUrl is required for all payment methods except M_PESA, TELE_BIRR_USSD, E_BIRR and CBE.
On M_PESA, TELE_BIRR_USSD, E_BIRR and CBE Phone Number Requirement: For phone number must be provided either in the phoneNumber field or in the customerInfo.phone field.

Get Started

Payment

Webhook

Transaction

ExpressPay: Direct Payment Processing

Authentication

How to Create Express payment

Parameters

Express Payment Request

Payment Item

Split Payment Details

Customer Info Request

Test Mode (Sandbox Only)

Interface Explanation

Example Request

M-PESA Payment Example

Response of the Request

Successful Response

Error Response

Payment Response

Making payment

Important Validation Rules

Get Started

Payment

Webhook

Transaction

​ExpressPay: Direct Payment Processing

​Authentication

​How to Create Express payment

​Parameters

​Express Payment Request

​Payment Item

​Split Payment Details

​Customer Info Request

​Test Mode (Sandbox Only)

​Interface Explanation

​Example Request

​M-PESA Payment Example

​Response of the Request

​Successful Response

​Error Response

​Payment Response

​Making payment

​Important Validation Rules

ExpressPay: Direct Payment Processing

Authentication

How to Create Express payment

Parameters

Express Payment Request

Payment Item

Split Payment Details

Customer Info Request

Test Mode (Sandbox Only)

Interface Explanation

Example Request

M-PESA Payment Example

Response of the Request

Successful Response

Error Response

Payment Response

Making payment

Important Validation Rules