Pay by Link - APIs

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

Advantages of Geidea's Pay by Link APIs

AdvantageDescription
PersonalizationThe APIs empower you to tailor the digital user experience and equip you with robust tools for monitoring payment links.
ControlTake full command of the payment process using our Pay by Link 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!

List of APIs

API ReferenceDescription
Create Payment LinkCreate a new payment link.
Update Payment LinkUpdate a payment link that has been created and not paid.
Delete Payment LinkDelete a payment link that has been issued.
Fetch Payment Link DetailsAPI to view Payment Link details by providing the Payment Link id
Fetch All or Search Payment LinksThis API helps you retrieve all payment links based on some filter criteria. You can use this API to search among payment links created by you.
Send Payment Link by e-mailThis API helps you send the payment link to your customer to the email used in the Create Payment Intent API call
Send Payment Link by SMSThis API helps you send the payment link to your customer as an SMS to the phone number used in the Create Payment Intent API call

Creating a Payment Link

Step 1: Creating a Payment Intent

You can create a Payment Link by calling the Create Payment Intent API.

πŸ“˜

A payment intent is a contractual agreement between a customer and a merchant to finalize a transaction. It encompasses essential details like the payment amount and currency. Geidea Payment Gateway utilizes payment intents to authorize and process payments, particularly in online marketplaces and subscription services. They ensure secure payment handling and protect customers from unauthorized charges.

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

ParameterDatatypeDescription
amountfloatThe total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.
currencystringCurrency 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.
callbackUrlstringThis 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.
customerobjectDetails of the customer for whom the payment link is being generated
customer.emailstringEmail of customer. Either email or phoneNumber must be present.
customer.namestringCustomer name
customer.phoneCountryCodestringCountry code of customer's phone number eg: "+971". If phoneNumber is passed, phoneCountryCode must be passed
customer.phoneNumberstringCustomer's phone number eg: "511111111". If phoneCountryCode is passed, phoneNumber must be passed.

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

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

curl --location 'https://api.merchant.geidea.net/payment-intent/api/v1/direct/eInvoice' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOmRmMGZjNjg3LTc4M2ItNDA1OC1hZjYzLTllODc2NDQ0YjM1Nw==' \
--data-raw '{
  "amount": 123.21,
  "currency": "EGP",
  "customer": {
    "email": "[email protected]",
    "phoneCountryCode": "+20",
    "phoneNumber": "511111111",
    "name": "John"
  }
}'
{
    "paymentIntent": {
        "link": "https://merchant.geidea.net/payByLink/zie-tsb-2o7-750",
        "customer": {
            "customerId": "e1900e15-06f6-4317-142e-08daf7e8daf6",
            "email": "[email protected]",
            "phoneNumber": "511111111",
            "phoneCountryCode": "+966",
            "name": "John",
            "updatedBy": null,
            "updatedDate": "2023-01-23T22:39:07.7558955Z",
            "addresses": []
        },
        "eInvoiceDetails": {
            "type": "Detailed",
            "collectCustomersBillingShippingAddress": false,
            "preAuthorizeAmount": false,
            "subtotalWithoutTax": 0,
            "subtotalTax": 0,
            "subtotal": null,
            "grandTotal": null,
            "extraCharges": null,
            "extraChargesType": null,
            "chargeDescription": null,
            "merchantReferenceId": null,
            "invoiceDiscount": null,
            "invoiceDiscountType": null,
            "language": "EN",
            "eInvoiceItems": []
        },
        "eInvoiceSentLinks": [],
        "paymentIntentId": "44547a1d-3d38-48e0-48b8-08db1040d2e5",
        "number": "562554044141",
        "urlSlug": "zie-tsb-2o7-750",
        "type": "EInvoice",
        "amount": 123.21,
        "currency": "SAR",
        "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
        "expiryDate": "2023-03-29T03:43:31.9568307Z",
        "activationDate": null,
        "status": "Created",
        "customerId": "e1900e15-06f6-4317-142e-08daf7e8daf6",
        "eInvoiceUploadId": null,
        "staticPaylinkId": null,
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "orders": [],
        "isPending": true,
        "createdDate": "2023-02-27T03:43:32.0344309Z",
        "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 paymentIntent.link is returned in the response. You have the flexibility to programmatically share this link with your customers via SMS and email. Upon the customer's attempt to use the payment link, you'll receive notifications regarding the success or failure of the payment transaction..

Step 2: Sending the Payment Link to your customer.

Once you've generated the payment link, simply share it to your customer for payment completion. Upon clicking the link, your customer will be directed to a Geidea-hosted payment page where they can securely finalize the payment using their preferred payment method.

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

Upon clicking the payment link, a secure Geidea Hosted Payment Page appears where your customer fills in their payment details. The form validates inputs, notifying customers of errors if any. Once validated, the pay button activates, allowing customers to proceed with the payment seamlessly..

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 Link

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

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

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

ParameterDatatypeDescription
paymentIntentIdstringUnique ID assigned by the Geidea platform for the payment link
amountfloatThe total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.
currencystringCurrency 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.
customerobjectDetails of the customer for whom the payment link is being updated
customer.emailstringEmail of customer.
customer.namestringCustomer name
customerIdstringUnique ID for the customer on the Geidea payment gateway. The identifier you can use to uniquely identify your customer on the Geidea platform
eInvoiceDetails.subtotalfloatSubtotal inclusive of tax. Must be equal to [eInvoiceItems.price * eInvoiceItems.quantity] sent in this request
eInvoiceDetails.grandTotalfloatGrand Total. Must be equal to [eInvoiceItems.price * eInvoiceItems.quantity] sent in this request.
eInvoiceDetails.eInvoiceItems.pricefloatUpdated price for items
eInvoiceDetails.eInvoiceItems.quantityintegerUpdated quantity of items
eInvoiceDetails.eInvoiceItems.totalfloatUpdated total

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

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

curl --location --request PUT 'https://api.merchant.geidea.net/payment-intent/api/v1/direct/eInvoice' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOmRmMGZjNjg3LTc4M2ItNDA1OC1hZjYzLTllODc2NDQ0YjM1Nw==' \
--data-raw '{
    "paymentIntentId": "8bd5e3a8-2948-4cc9-47a3-08db1040d2e5",
    "amount": 123.2,
    "currency": "SAR",
    "customer": {
        "email": "[email protected]",
        "name": "John"
    },
    "eInvoiceDetails": {
        "subtotal": 123.2,
        "grandTotal": 123.2,
        "eInvoiceItems": [
            {
                "price": 12.32,
                "quantity": 10,
                "total": 123.2
            }
        ]
    }
}'
{
    "paymentIntent": {
        "link": "https://merchant.geidea.net/payByLink/ato-mfs-75c-vjp",
        "customer": {
            "customerId": "f3fadcaa-20d4-4ee6-bbe0-08db105e01ce",
            "email": "[email protected]",
            "phoneNumber": null,
            "phoneCountryCode": null,
            "name": "John",
            "updatedBy": "PGW",
            "updatedDate": "2023-02-24T07:54:35.4501687Z",
            "addresses": []
        },
        "eInvoiceDetails": {
            "type": "Detailed",
            "collectCustomersBillingShippingAddress": false,
            "preAuthorizeAmount": false,
            "subtotalWithoutTax": 123.20,
            "subtotalTax": 0,
            "subtotal": 123.2,
            "grandTotal": 123.2,
            "extraCharges": null,
            "extraChargesType": null,
            "chargeDescription": null,
            "merchantReferenceId": null,
            "invoiceDiscount": null,
            "invoiceDiscountType": null,
            "language": "EN",
            "eInvoiceItems": [
                {
                    "eInvoiceItemId": "5552cc83-51a1-4746-ace1-08db11e99a5e",
                    "description": null,
                    "price": 12.32,
                    "priceWithDiscount": 12.32,
                    "priceTax": 0,
                    "priceTotal": 12.32,
                    "quantity": 10,
                    "sku": null,
                    "itemDiscount": null,
                    "itemDiscountType": null,
                    "tax": null,
                    "taxType": null,
                    "totalWithoutTax": 123.20,
                    "totalTax": 0,
                    "total": 123.2
                }
            ]
        },
        "eInvoiceSentLinks": [],
        "paymentIntentId": "8bd5e3a8-2948-4cc9-47a3-08db1040d2e5",
        "number": "800879856627",
        "urlSlug": "ato-mfs-75c-vjp",
        "type": "EInvoice",
        "amount": 123.2,
        "currency": "SAR",
        "merchantId": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "merchantPublicKey": "a087f4ca-9890-407b-9c2f-7630836cc020",
        "expiryDate": "2023-03-26T06:17:07.1734542Z",
        "activationDate": null,
        "status": "SentToCustomer",
        "customerId": "f3fadcaa-20d4-4ee6-bbe0-08db105e01ce",
        "eInvoiceUploadId": null,
        "staticPaylinkId": null,
        "subscriptionId": null,
        "subscriptionOccurrenceId": null,
        "orders": [],
        "isPending": true,
        "createdDate": "2023-02-24T06:17:07.4084854Z",
        "createdBy": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b",
        "updatedDate": "2023-02-24T07:54:35.3096269Z",
        "updatedBy": "e80ece7e-fb2a-4c0b-de94-08d8a29a107b"
    },
    "termsAndConditions": null,
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "EN",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

Delete payment link

You can delete Payment Links issued to your customers using the Delete payment link API.

πŸ“˜

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

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

ParameterDatatypeDescription
paymentIntentIdstringPayment Intent ID that was generated when the payment link was created.

Below is an example of executing a Cancel Payment Link API call.

curl --location --request DELETE 'https://api.merchant.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 Link via e-mail

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

πŸ“˜

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

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

ParameterDatatypeDescription
paymentIntentIdstringPayment Intent ID that was generated when the payment link was created.

Below is an example of executing a Cancel Payment Link API call.

curl --location --request POST 'https://api.merchant.geidea.net/payment-intent/api/v1/direct/eInvoice/219e4abd-901f-4f79-a4de-08db661548fa/SendByEmail' \
--header 'Authorization: Basic ZDllZmU5MDUtZTAxNS00ZjgyLWI5YTAtOTAwNjUxZmZhZTZlOjFiNzFkNjY1LTk0YjUtNDM3OS04ODQ4LWFiOWRlMjFmYzE2ZQ==' \
--data ''
{
    "paymentIntent": {
        "link": "https://merchant.geidea.net/payByLink/rbt-6sr-5dz-0gt",
        "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]"
            }
        ],
        "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 Link via SMS

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

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

ParameterDatatypeDescription
paymentIntentIdstringPayment Intent ID that was generated when the payment link was created.

Below is an example of executing a Cancel Payment Link API call.

curl --location --request POST 'https://api.merchant.geidea.net/payment-intent/api/v1/direct/eInvoice/b27ce64c-4dc1-4b52-409a-08db662a73ff/sendBySms' \
--header 'Authorization: Basic ZDllZmU5MDUtZTAxNS00ZjgyLWI5YTAtOTAwNjUxZmZhZTZlOjFiNzFkNjY1LTk0YjUtNDM3OS04ODQ4LWFiOWRlMjFmYzE2ZQ==' \
--data ''
{
    "paymentIntent": {
        "link": "https://merchant.geidea.net/payByLink/rbt-6sr-5dz-0gt",
        "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]"
            }
        ],
        "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"
}