Pay by Invoice

You can use our Pay by Invoice APIs to create your custom flows to personalize the digital journey of your customers.

Advantages of Geidea's Pay by Invoice APIs

Advantage	Description
Personalization	The APIs empower you to tailor the digital user experience and equip you with robust tools for monitoring payment invoices.
Control	Take full command of the payment process using our Pay by Invoice APIs. They offer a multitude of capabilities, including configuring accepted payment methods, customizing invoices to reflect your brand identity, sending reminders, and more.

📘
Please check out the prerequisites section before beginning your integration!

📘
Usage of the API environment endpoints
Please make sure you use the correct endpoint based on your environment

KSA Environment: https://api.ksamerchant.geidea.net/

List of APIs

API Reference	Description
Create Payment Invoice	Create a new standard payment invoice.
Create Quick Payment Invoice	Create a new quick payment invoice.
Update Payment Invoice	Update a payment invoice that has been created and not paid.
Delete Payment Invoice	Delete a payment invoice that has been issued.
Fetch Payment Invoice Details	API to view Payment Invoice details by providing the Payment Intent Id
Fetch All or Search Payment Invoices	This API helps you retrieve all payment invoices based on some filter criteria. You can use this API to search among payment invoices created by you.
Send Payment Invoice by e-mail	This API helps you send the payment invoice to your customer to the email used in the Create Payment Invoice API call
Send Payment Invoice by SMS	This API helps you send the payment invoice to your customer as an SMS to the phone number used in the Create Payment Invoice API call

Creating a Payment Invoice

❗️
To use the Quick Payment Invoice feature, you’ll need to generate a signature as demonstrated below

Quick Pay By Invoice Signature

Concatenate merchantPublicKey amountStr orderCurrency orderMerchantReferenceId timeStamp
Amount must be formatted with 2 decimals
Hash (SHA-256) the above concatenated string by MerchantAPIPassword
Convert Hashed Value to Base64Str

Step 1: Creating a Payment Invoice

You can create a Payment Invoice by calling the Create Payment Invoice API.

📘
What's a Payment Invoice !

Payment Invoice is a unique ID that you can generate to allow customers to make payments online.

It can contain details about the goods or services sold and the amount you want to collect from your customers. They ensure secure payment handling and protect customers from unauthorized charges.

To initiate a Create Payment Invoice API call, you will need to provide the following required fields along with the payload of the API.

Parameter	Description	Mandatory
`amount`	The total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.	Yes
`currency`	Currency of the order for which the authentication is initiated. Please follow ISO 4217 alpha code standards for the currency code. The currency code must be 3 characters in length. The currencies must be limited to the list configured for your merchant account.	Yes
`callbackUrl`	This callback is a plain HTTP POST request to a merchant-defined URL endpoint to receive the response payload after a transaction is successful or failed.	No
`customer`	Details of the customer for whom the payment invoice is being generated	Yes
`customer.email`	Email of customer. Either email or phoneNumber must be present.	Conditional
`customer.name`	Customer name	Yes
`customer.phoneCountryCode`	Country code of customer's phone number eg: "+971". If phoneNumber is passed, phoneCountryCode must be passed	Conditional
`customer.phoneNumber`	Customer's phone number eg: "511111111". If phoneCountryCode is passed, phoneNumber must be passed.	Conditional
`eInvoiceDetails`	Details of the eInvoice that includes item details and price breakdown	Yes
`eInvoiceDetails.eInvoiceItems`	List of e-Invoice items	Yes
`eInvoiceDetails.eInvoiceItems.price`	Item Price	Yes
`eInvoiceDetails.eInvoiceItems.quantity`	Quantity of item	Yes
`eInvoiceDetails.eInvoiceItems.description`	Item description. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.eInvoiceItemId`	e-Invoice item ID	No
`eInvoiceDetails.eInvoiceItems.itemDiscountType`	Type of discount applied on item. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.eInvoiceItems.taxType`	Type of tax levied on item. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.eInvoiceItems.total`	Total price including tax levied. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity]	Yes
`eInvoiceDetails.eInvoiceItems.priceWithDiscount`	Item price after discount is applied. If not set in request, it is set to value of eInvoiceItems.price automatically and the value is returned in response	No
`eInvoiceDetails.eInvoiceItems.priceTax`	Tax on Item Price. If not set in request, it is set to zero automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.priceTotal`	Total Price inclusive of Tax. If not set in request, it is set to value of eInvoiceItems.price automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.sku`	Item SKU. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.itemDiscount`	Discount applied on item. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.tax`	Tax on item. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.totalWithoutTax`	Total price of item without tax. If not set in request, it is set to value of amount automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.totalTax`	Tax for the item. If not set in request, it is set to zero automatically and the value is returned in response.	No
`eInvoiceDetails.subtotal`	Amount for which payment invoice is created. Amount must be greater than 0.01. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity]	Yes
`eInvoiceDetails.grandTotal`	Grand Total. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity]. Must be same as amount.	Yes
`eInvoiceDetails.subtotalWithoutTax`	Subtotal exclusive of tax. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity] if passed. If not set in request, it is set to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity] value automatically and the value is returned in response.	No
`eInvoiceDetails.subtotalTax`	Subtotal tax. If not set in request, it is set to zero automatically and the value is returned in response	No
`eInvoiceDetails.extraChargesType`	Type of extra charges levied. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.invoiceDiscountType`	Type of discount applied on invoice. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.type`	Type of eInvoice. If not set in request, it is set to "Detailed" automatically and the value is returned in response.	No
`eInvoiceDetails.collect` CustomersBillingShippingAddress`	Flag indicating to capture Customer's billing and shipping addresses. If not set in request, it is set to false automatically and the value is returned in response	No
`eInvoiceDetails.preAuthorizeAmount`	Flag indicating whether to preauthorize the amount. If not set in request, it is set to false automatically and the value is returned in response.	No
`eInvoiceDetails.extraCharges`	Extra charges levied. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.chargeDescription`	Description of charge levied. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.merchantReferenceId`	The merchant account identifier for which the payment invoice is created.	No
`eInvoiceDetails.invoiceDiscount`	Discount applied on invoice. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.language`	Language to be displayed in Payment Page. If not set in request, it is set to "EN" automatically and the value is returned in response.	No

You can find a complete list of parameters that can be used with the Create Payment Invoice API here.

Below is an example of executing a Create payment invoice call for a payment of 123.21 EGP with the mandatory parameters.

curl --request POST \
     --url https://api.ksamerchant.geidea.net/payment-intent/api/v1/direct/eInvoice \
     --header 'accept: application/json' \
     --header 'authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOjI2ZDMxOTE3LTcxNWUtNDhhYy1iMDcyLWRhOTczODAxNmFmNQ==' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 20,
  "currency": "SAR",
  "customer": {
    "name": "John",
    "email": "[email protected]",
    "phoneCountryCode": "+20",
    "phoneNumber": "8003030083"
  },
  "eInvoiceDetails": {
    "subtotal": 20,
    "grandTotal": 20,
    "extraChargesType": "Amount",
    "invoiceDiscountType": "Amount",
    "eInvoiceItems": [
      {
        "eInvoiceItemId": "17e95202-d151-43ff-d6af-08db4614f0bb",
        "description": "Subscription for tech",
        "price": 10,
        "quantity": 2,
        "itemDiscountType": "Amount",
        "taxType": "Amount",
        "total": 20,
        "priceWithDiscount": 10,
        "priceTax": 0,
        "priceTotal": 10,
        "sku": "1245",
        "itemDiscount": 0,
        "tax": 0,
        "totalWithoutTax": 20,
        "totalTax": 0
      }
    ],
    "callbackurl": "https://webhook.site/eb350004-1c84-48ef-8436-55c5a734cce4",
    "language": "EN",
    "invoiceDiscount": 0,
    "merchantReferenceId": "ref123",
    "chargeDescription": "charge amount",
    "extraCharges": 0,
    "subtotalWithoutTax": 20,
    "preAuthorizeAmount": false,
    "collectCustomersBillingShippingAddress": false,
    "type": "Detailed",
    "subtotalTax": 0
  },
  "expiryDate": "2024-05-10",
  "activationDate": "2024-03-18"
}
'

{
  "paymentIntent": {
    "link": "",
    "customer": {
      "customerId": "938e6122-c42a-4ee1-4634-08dc400e9226",
      "email": "[email protected]",
      "phoneNumber": "8003030083",
      "phoneCountryCode": "+20",
      "name": "John",
      "updatedBy": null,
      "updatedDate": "2024-03-18T12:36:20.6459781Z",
      "addresses": [],
      "customValue": null
    },
    "eInvoiceDetails": {
      "type": "Detailed",
      "collectCustomersBillingShippingAddress": false,
      "preAuthorizeAmount": false,
      "subtotalWithoutTax": 20,
      "subtotalTax": 0,
      "subtotal": 20,
      "grandTotal": 20,
      "extraCharges": 0,
      "extraChargesType": "Amount",
      "extraChargesLabel": null,
      "chargeDescription": "charge amount",
      "merchantReferenceId": "ref123",
      "invoiceDiscount": 0,
      "invoiceDiscountType": "Amount",
      "language": "EN",
      "eInvoiceItems": [
        {
          "eInvoiceItemId": "e77e4795-8d14-4899-855b-08dc4011fb90",
          "description": "Subscription for tech",
          "price": 10,
          "priceWithDiscount": 10,
          "priceTax": 0,
          "priceTotal": 10,
          "quantity": 2,
          "sku": "1245",
          "itemDiscount": 0,
          "itemDiscountType": "Amount",
          "tax": 0,
          "taxType": "Amount",
          "totalWithoutTax": 20,
          "totalTax": 0,
          "total": 20
        }
      ],
      "callbackUrl": "https://webhook.site/eb350004-1c84-48ef-8436-55c5a734cce4",
      "addOnFees": null,
      "addOnFeesType": null,
      "addOnFeesLabel": null
    },
    "eInvoiceSentLinks": [],
    "customFields": null,
    "invoiceId":"INV-202604-120825148618",
    "paymentIntentId": "8f67f208-7a6d-4e5c-741e-08dc400e92f5",
    "parentPaymentIntentId": null,
    "number": "956638821339",
    "urlSlug": "w23-ctb-8y9-78o",
    "type": "EInvoice",
    "amount": 20,
    "currency": "SAR",
    "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
    "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
    "expiryDate": "2024-05-10T00:00:00Z",
    "activationDate": "2024-03-18T00:00:00Z",
    "status": "Created",
    "customerId": "938e6122-c42a-4ee1-4634-08dc400e9226",
    "eInvoiceUploadId": null,
    "staticPaylinkId": null,
    "subscriptionId": null,
    "subscriptionOccurrenceId": null,
    "orders": [],
    "isPending": true,
    "createdDate": "2024-03-18T12:41:39.74096Z",
    "createdBy": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
    "updatedDate": null,
    "updatedBy": null
  },
  "termsAndConditions": null,
  "responseMessage": "Success",
  "detailedResponseMessage": "The operation was successful",
  "language": "EN",
  "responseCode": "000",
  "detailedResponseCode": "000"
}

API Response

As shown above, the parameter invoiceId is returned in the response. You have the flexibility to programmatically share this invoiceId with your customers via SMS and email. Upon the customer's attempt to use the payment invoiceId, you'll receive notifications regarding the success or failure of the payment transaction..

Step 2: Sending the Payment Invoice to your customer.

Once you've generated the payment invoice, simply share it to your customer for payment completion. Upon receiving the invoiceId, the customer will need to navigate to Geidea official website to complete the payment.

Step 3: Complete Payment using Hosted Payment Page or Direct API.

When the customer receives the Invoice ID, they can copy it and navigate to the official Geidea website. From the homepage, they should select “Pay Invoice” and enter the received Invoice ID.

Once submitted, the customer will be redirected to Geidea’s secure payment page to complete the payment via their desired payment methods.

Upon completing the payment, the customer will be redirected (if the options is enabled by the merchant) to a page displaying a summary of the order.

Update a Payment Invoice

You can also update a payment invoice with the help of our Update Payment Invoice API. This API can be used to carry out actions such as updating the expiry date of a payment invoice, updating the status of a payment invoice after sending the invoiceId to the customer by the Merchant and so on.

When you call the Create Payment Invoice API, a paymentIntentId parameter is returned with the API response. You must use the paymentIntentId parameter in the Update Payment Invoice API call to update the properties of a payment invoice.

To initiate an Update Payment Invoice API call, you will need to provide the following required fields along with the payload of the API.

Parameter	Datatype	Description	Mandatory
`paymentIntentId`	string	Unique ID assigned by the Geidea platform for the payment invoice	Yes
`amount`	double	The total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.	Yes
`currency`	string	Currency of the order for which the authentication is initiated. Please follow ISO 4217 alpha code standards for the currency code. The currency code must be 3 characters in length. The currencies must be limited to the list configured for your merchant account.	Yes
`customer`	object	Details of the customer for whom the payment invoice is being updated	No
`customer.email`	string	Email of the customer.	Optional
`customer.name`	string	Customer name. If customer object is added then having the customer name is mandatory	Yes
`customer.phoneCountryCode`	string	Country code of customer's phone number eg: "+971". If phoneNumber is passed, phoneCountryCode must be passed.	Optional
`customer.phoneNumber`	string	Customer's phone number eg: "511111111". If phoneCountryCode is passed, phoneNumber must be passed. One of email or phoneNumber must be present.	Optional
`customerId`	string	Unique ID for the customer on the Geidea payment gateway. The identifier you can use to uniquely identify your customer on the Geidea platform	No
`eInvoiceDetails`	object	e-Invoice details object	Yes
`eInvoiceDetails.subtotal`	double	Subtotal inclusive of tax. Must be equal to [`eInvoiceItems.price` * `eInvoiceItems.quantity`][`eInvoiceItems.price` * `eInvoiceItems.quantity`] sent in this request	Yes
`eInvoiceDetails.grandTotal`	double	Grand Total. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity] sent in this request.	Yes
`eInvoiceDetails.subtotalWithoutTax`	double	Subtotal exclusive of tax. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity] if passed. If not set in request, it is set to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity] value automatically and the value is returned in response.	No
`eInvoiceDetails.subtotalTax`	double	Subtotal tax. If not set in request, it is set to zero automatically and the value is returned in response	No
`eInvoiceDetails.extraChargesType`	string	Type of extra charges levied. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.invoiceDiscountType`	string	Type of discount applied on invoice. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.type`	string	Type of eInvoice. If not set in request, it is set to "Detailed" automatically and the value is returned in response.	No
`eInvoiceDetails.collectCustomersBilling ShippingAddress`	boolean	Flag indicating to capture Customer's billing and shipping addresses. If not set in request, it is set to false automatically and the value is returned in response	No
`eInvoiceDetails.preAuthorizeAmount`	boolean	Flag indicating whether to preauthorize the amount. If not set in request, it is set to false automatically and the value is returned in response.	No
`eInvoiceDetails.extraCharges`	double	Extra charges levied. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.chargeDescription`	string	Description of charge levied. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.merchantReferenceId`	string	The merchant account identifier for which the payment invoice is created.	No
`eInvoiceDetails.invoiceDiscount`	double	Discount applied on invoice. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.language`	string	Language to be displayed in Payment Page. If not set in request, it is set to "EN" automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems`	object	List of e-Invoice items	Yes
`eInvoiceDetails.eInvoiceItems.price`	double	Updated price for items	Yes
`eInvoiceDetails.eInvoiceItems.quantity`	integer	Updated quantity of items	Yes
`eInvoiceDetails.eInvoiceItems.total`	double	Updated total	Yes
`eInvoiceDetails.eInvoiceItems.eInvoiceItemId`	string	e-Invoice item ID	No
`eInvoiceDetails.eInvoiceItems.description`	string	Item description. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.itemDiscountType`	string	Type of discount applied on item. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.eInvoiceItems.taxType`	string	Type of tax levied on item. Available values are: "Amount" or "Percentage". Default Value: "Amount"	No
`eInvoiceDetails.eInvoiceItems.total`	double	Total price including tax levied. Must be equal to [eInvoiceItems.price eInvoiceItems.quantity][eInvoiceItems.price eInvoiceItems.quantity]	No
`eInvoiceDetails.eInvoiceItems.priceWithDiscount`	double	Item price after discount is applied. If not set in request, it is set to value of eInvoiceItems.price automatically and the value is returned in response	No
`eInvoiceDetails.eInvoiceItems.priceTax`	double	Tax on Item Price. If not set in request, it is set to zero automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.priceTotal`	double	Total Price inclusive of Tax. If not set in request, it is set to value of eInvoiceItems.price automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.sku`	string	Item SKU. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.itemDiscount`	double	Discount applied on item. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.tax`	double	Tax on item. If not set in request, it is set to null automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.totalWithoutTax`	double	Total price of item without tax. If not set in request, it is set to value of amount automatically and the value is returned in response.	No
`eInvoiceDetails.eInvoiceItems.totalTax`	double	Tax for the item. If not set in request, it is set to zero automatically and the value is returned in response.	No
`status`	string	Status of the Payment Invoice. Only SentToCustomer is allowed for merchant to change	No

You can find a complete list of parameters that can be used with the Update Payment Invoice API here.

Below is an example of executing an Update Payment Invoice API call for a payment of 123.2 SAR with the mandatory parameters.

curl --request PUT \
     --url https://api.ksamerchant.geidea.net/payment-intent/api/v1/direct/eInvoice \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentIntentId": "8f67f208-7a6d-4e5c-741e-08dc400e92f5",
  "amount": 20,
  "currency": "SAR",
  "customer": {
    "name": "John",
    "email": "[email protected]",
    "phoneCountryCode": "+20",
    "phoneNumber": "8003030083"
  },
  "eInvoiceDetails": {
    "subtotal": 20,
    "grandTotal": 20,
    "extraChargesType": "Amount",
    "invoiceDiscountType": "Amount",
    "eInvoiceItems": [
      {
        "eInvoiceItemId": "17e95202-d151-43ff-d6af-08db4614f0bb",
        "description": "Subscription for tech1",
        "price": 10,
        "quantity": 2,
        "itemDiscountType": "Amount",
        "taxType": "Amount",
        "total": 20,
        "priceWithDiscount": 10,
        "priceTax": 0,
        "priceTotal": 10,
        "itemDiscount": 0,
        "tax": 0,
        "totalWithoutTax": 20,
        "totalTax": 0,
        "sku": "12456"
      }
    ],
    "type": "Detailed",
    "collectCustomersBillingShippingAddress": false,
    "preAuthorizeAmount": true,
    "subtotalWithoutTax": 20,
    "subtotalTax": 0,
    "extraCharges": 0,
    "chargeDescription": "charge amount update",
    "merchantReferenceId": "ref123",
    "invoiceDiscount": 0,
    "language": "EN"
  },
  "status": "SentToCustomer"
}
'

{
    "paymentIntent": {
        "link": "",
        "customer": {
            "customerId": "938e6122-c42a-4ee1-4634-08dc400e9226",
            "email": "[email protected]",
            "phoneNumber": "8003030083",
            "phoneCountryCode": "+20",
            "name": "John",
            "updatedBy": "PGW",
            "updatedDate": "2024-03-19T09:23:31.4158777Z",
            "addresses": [],
            "customValue": null
        },
        "eInvoiceDetails": {
            "type": "Detailed",
            "collectCustomersBillingShippingAddress": false,
            "preAuthorizeAmount": true,
            "subtotalWithoutTax": 20,
            "subtotalTax": 0,
            "subtotal": 20,
            "grandTotal": 20,
            "extraCharges": 0,
            "extraChargesType": "Amount",
            "extraChargesLabel": null,
            "chargeDescription": "charge amount update",
            "merchantReferenceId": "ref123",
            "invoiceDiscount": 0,
            "invoiceDiscountType": "Amount",
            "language": "EN",
            "eInvoiceItems": [
                {
                    "eInvoiceItemId": "7ca2efb5-8721-4539-b43f-08dc40161532",
                    "description": "Subscription for tech1",
                    "price": 10,
                    "priceWithDiscount": 10,
                    "priceTax": 0,
                    "priceTotal": 10,
                    "quantity": 2,
                    "sku": "12456",
                    "itemDiscount": 0,
                    "itemDiscountType": "Amount",
                    "tax": 0,
                    "taxType": "Amount",
                    "totalWithoutTax": 20,
                    "totalTax": 0,
                    "total": 20
                }
            ],
            "callbackUrl": "https://webhook.site/eb350004-1c84-48ef-8436-55c5a734cce4",
            "addOnFees": null,
            "addOnFeesType": null,
            "addOnFeesLabel": null
        },
        "eInvoiceSentLinks": [],
      "customFields": null,
        "invoiceId":"INV-202604-120825148618",
        "paymentIntentId": "8f67f208-7a6d-4e5c-741e-08dc400e92f5",
        "parentPaymentIntentId": null,
        "number": "956638821339",
        "urlSlug": "w23-ctb-8y9-78o",
        "type": "EInvoice",
        "amount": 20,
        "currency": "SAR",
        "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
        "expiryDate": "2024-05-10T00:00:00Z",
        "activationDate": "2024-03-18T00:00:00Z",
        "status": "SentToCustomer",
        "customerId": "938e6122-c42a-4ee1-4634-08dc400e9226",
        "eInvoiceUploadId": null,
        "staticPaylinkId": null,
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "orders": [],
        "isPending": true,
        "createdDate": "2024-03-18T12:41:39.74096Z",
        "createdBy": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "updatedDate": "2024-03-19T09:23:31.3091588Z",
        "updatedBy": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b"
    },
    "termsAndConditions": null,
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

Delete Payment Invoice

You can delete Payment Invoices issued to your customers using the Delete payment invoice API.

📘
You can only delete Payment Invoices that are in the Created state.

You need to pass the following parameter(s) as path parameter(s) in the API request

Parameter	Datatype	Description	Mandatory
`paymentIntentId`	string	Payment Intent ID that was generated when the payment invoice was created.	Yes

Below is an example of executing a Delete Payment Invoice API call.

curl --location --request DELETE 'https://api.ksamerchant.geidea.net/payment-intent/api/v1/direct/eInvoice/9fca0f3d-bd93-469b-0782-08daf7ec2bc4' \
--header 'accept: text/plain' \
--header 'Authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOmRmMGZjNjg3LTc4M2ItNDA1OC1hZjYzLTllODc2NDQ0YjM1Nw=='

{
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

Send Payment Invoice via e-mail

You can send a Payment Invoice to your customers via e-mail using the Send Payment Invoice by email API.

📘
You can only send Payment Invoices that are in the Created state.

You need to pass the following parameter(s) as path parameter(s) in the API request

Parameter	Datatype	Description	Mandatory
`paymentIntentId`	string	Payment Intent ID that was generated when the payment invoice was created.	Yes

Below is an example of executing a Send Payment Invoice by Email API call.

curl --location --request POST 'https://api.ksamerchant.geidea.net/payment-intent/api/v1/direct/eInvoice/219e4abd-901f-4f79-a4de-08db661548fa/SendByEmail' \
--header 'Authorization: Basic ZDllZmU5MDUtZTAxNS00ZjgyLWI5YTAtOTAwNjUxZmZhZTZlOjFiNzFkNjY1LTk0YjUtNDM3OS04ODQ4LWFiOWRlMjFmYzE2ZQ==' \
--data ''

{
    "paymentIntent": {
        "link": "",
        "customer": {
            "customerId": "d5ace925-35a0-4b2c-c768-08db6623eb3b",
            "email": "[email protected]",
            "phoneNumber": "1008529854",
            "phoneCountryCode": "+20",
            "name": "sidra",
            "updatedBy": null,
            "updatedDate": "2023-06-25T16:16:27.7450601Z",
            "addresses": []
        },
        "eInvoiceDetails": {
            "type": "Detailed",
            "collectCustomersBillingShippingAddress": false,
            "preAuthorizeAmount": false,
            "subtotalWithoutTax": 1000.00,
            "subtotalTax": 0.00,
            "subtotal": 1000.00,
            "grandTotal": 1000.00,
            "extraCharges": null,
            "extraChargesType": "Amount",
            "chargeDescription": null,
            "merchantReferenceId": "MECH990",
            "invoiceDiscount": null,
            "invoiceDiscountType": "Amount",
            "language": "EN",
            "eInvoiceItems": [
                {
                    "eInvoiceItemId": "2b261d67-b789-45d7-b811-08db66739c9a",
                    "description": null,
                    "price": 100.00,
                    "priceWithDiscount": 100.00,
                    "priceTax": 0.00,
                    "priceTotal": 100.00,
                    "quantity": 10,
                    "sku": null,
                    "itemDiscount": null,
                    "itemDiscountType": "Amount",
                    "tax": null,
                    "taxType": "Amount",
                    "totalWithoutTax": 1000.00,
                    "totalTax": 0.00,
                    "total": 1000.00
                }
            ]
        },
        "eInvoiceSentLinks": [
            {
                "sentDate": "2023-07-02T05:16:04.1401636Z",
                "channel": "Email",
                "recipient": "[email protected]"
            }
        ],
        "invoiceId":"INV-202604-120825148618",
        "paymentIntentId": "219e4abd-901f-4f79-a4de-08db661548fa",
        "number": "739052552147",
        "urlSlug": "rbt-6sr-5dz-0gt",
        "type": "EInvoice",
        "amount": 1000.00,
        "currency": "EGP",
        "merchantId": "605c83e8-b0e7-4907-8878-08db6b89eb58",
        "merchantPublicKey": "d9efe905-e015-4f82-b9a0-900651ffae6e",
        "expiryDate": "2023-07-26T12:32:44.5226275Z",
        "activationDate": null,
        "status": "SentToCustomer",
        "customerId": "d5ace925-35a0-4b2c-c768-08db6623eb3b",
        "eInvoiceUploadId": null,
        "staticPaylinkId": null,
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "orders": [],
        "isPending": true,
        "createdDate": "2023-06-26T12:32:45.0134668Z",
        "createdBy": "605c83e8-b0e7-4907-8878-08db6b89eb58",
        "updatedDate": "2023-07-02T05:16:04.1856881Z",
        "updatedBy": "PGW"
    },
    "termsAndConditions": null,
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

Send Payment Invoice via SMS

You can send a Payment Invoice to your customers via e-mail using the Send Payment Invoice by SMS API.

You need to pass the following parameter(s) as path parameter(s) in the API request

Parameter	Datatype	Description	Mandatory
`paymentIntentId`	string	Payment Intent ID that was generated when the payment invoice was created.	Yes

Below is an example of executing a Send Payment Invoice via SMS API call.

curl --location --request POST 'https://api.ksamerchant.geidea.net/payment-intent/api/v1/direct/eInvoice/b27ce64c-4dc1-4b52-409a-08db662a73ff/sendBySms' \
--header 'Authorization: Basic ZDllZmU5MDUtZTAxNS00ZjgyLWI5YTAtOTAwNjUxZmZhZTZlOjFiNzFkNjY1LTk0YjUtNDM3OS04ODQ4LWFiOWRlMjFmYzE2ZQ==' \
--data ''

{
    "paymentIntent": {
        "link": "",
        "customer": {
            "customerId": "d5ace925-35a0-4b2c-c768-08db6623eb3b",
            "email": "[email protected]",
            "phoneNumber": "1008529854",
            "phoneCountryCode": "+20",
            "name": "sidra",
            "updatedBy": null,
            "updatedDate": "2023-06-25T16:16:27.7450601Z",
            "addresses": []
        },
        "eInvoiceDetails": {
            "type": "Detailed",
            "collectCustomersBillingShippingAddress": false,
            "preAuthorizeAmount": false,
            "subtotalWithoutTax": 1000.00,
            "subtotalTax": 0.00,
            "subtotal": 1000.00,
            "grandTotal": 1000.00,
            "extraCharges": null,
            "extraChargesType": "Amount",
            "chargeDescription": null,
            "merchantReferenceId": "MECH990",
            "invoiceDiscount": null,
            "invoiceDiscountType": "Amount",
            "language": "EN",
            "eInvoiceItems": [
                {
                    "eInvoiceItemId": "2b261d67-b789-45d7-b811-08db66739c9a",
                    "description": null,
                    "price": 100.00,
                    "priceWithDiscount": 100.00,
                    "priceTax": 0.00,
                    "priceTotal": 100.00,
                    "quantity": 10,
                    "sku": null,
                    "itemDiscount": null,
                    "itemDiscountType": "Amount",
                    "tax": null,
                    "taxType": "Amount",
                    "totalWithoutTax": 1000.00,
                    "totalTax": 0.00,
                    "total": 1000.00
                }
            ]
        },
        "eInvoiceSentLinks": [
            {
                "sentDate": "2023-07-02T05:18:57.5098924Z",
                "channel": "Sms",
                "recipient": "+201008529854"
            },
            {
                "sentDate": "2023-07-02T05:16:04.1401636Z",
                "channel": "Email",
                "recipient": "[email protected]"
            }
        ],
        "invoiceId":"INV-202604-120825148618",
        "paymentIntentId": "219e4abd-901f-4f79-a4de-08db661548fa",
        "number": "739052552147",
        "urlSlug": "rbt-6sr-5dz-0gt",
        "type": "EInvoice",
        "amount": 1000.00,
        "currency": "EGP",
        "merchantId": "605c83e8-b0e7-4907-8878-08db6b89eb58",
        "merchantPublicKey": "d9efe905-e015-4f82-b9a0-900651ffae6e",
        "expiryDate": "2023-07-26T12:32:44.5226275Z",
        "activationDate": null,
        "status": "SentToCustomer",
        "customerId": "d5ace925-35a0-4b2c-c768-08db6623eb3b",
        "eInvoiceUploadId": null,
        "staticPaylinkId": null,
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "orders": [],
        "isPending": true,
        "createdDate": "2023-06-26T12:32:45.0134668Z",
        "createdBy": "605c83e8-b0e7-4907-8878-08db6b89eb58",
        "updatedDate": "2023-07-02T05:16:04.1856881Z",
        "updatedBy": "PGW"
    },
    "termsAndConditions": null,
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}