GEgeidea

Create Subscriptions

This page will help you get started with Checkout - Subscription.

post/direct/subscription

Request

  • Base URL
    https://api.ksamerchant.geidea.net/subscriptions/api/v1
  • URL
    https://api.ksamerchant.geidea.net/subscriptions/api/v1/direct/subscription
  • Auth
    HTTP basic

Request body

recurringPaymentAmountnumber float required

Subscription amount ex: 100.00

currency'EGP' | 'SAR' | 'USD' | 'EUR' required

The currency of the payment. This is a 3-digit alphabetic code, following the ISO 4217 currency code standard. For example: AED

cycleInterval'day' | 'week' | 'month' | 'year' required

Frequency for which a subscription transaction must be executed.

cycleFrequencyinteger required

Number of times the subscription must be executed 1, 2, etc...

typeOfPayment'RecurringLink' | 'RecurringPayment' required

Indicates type of Recurring Payment. RecurringPayment: means subsequent payment will be auto-collected from the customer based on his first payment RecurringLink: means a payment link will be sent to the customer based on the cycle interval and frequency. The customer needs to be present every time to pay If you are using Geidea Session or direct API's then you can pass typeOfPayment" = 'RecurringPayment"& "isFirstPmtPBL":false and collect the first payment from the customer via HPP. The subsequent payments will be auto-collected from the customer based on the scheduled job

customerIdstring

If you have already created a customer using the customerRequest object, you can pass it here. One of customerRequest Object or customerId is mandatory.

descriptionstring

The description of the subscription ex: TV channel plan A

startDatestring

Start date of subscription. Ex: "2024-03-05T09:26:07.472Z"

endDatestring

The end date of the subscription. For creating an endless subscription do not pass the endDate. For creating a subscription for a specific period, pass the endDate or numberOfPayments

numberOfPaymentsstring

The number of payments for the subscription. For creating an endless subscription do not pass the endDate. For creating a subscription for a specific period, pass the endDate or numberOfPayments

language'en' | 'ar'

The language to be used on the checkout page.

isFirstPmtPBLboolean

Use this parameter as with value true or false depending upon how you would like to collect the first payment. If you pass this as true the customer will receive the first payment request as a payment link. If you are using Geidea Session or direct API's please pass the value as false. Default value will be true

paylinkExpirationPeriodstring

The payment link expiration date, is required only when the isFirstPmtPBL parameter is set to true. The default expiration period for the payment link is 7 days. If you want to use any cycle frequency less than 7 days, please make sure you are passing the expiration period accordingly.

timestampstring

The timestamp of the moment at which the create subscription request has been initiated.

signaturestring required

A parameter to ensure the security and authenticity of API communications. It involves generating a signature using the contents of the API request and secret keys, which is then sent along with the request.

AmountVariability'VARIABLE' | 'FIXED'

Indicates whether the subscription amount is fixed or changing during the subscription. If value is "FIXED" then the amount does not change during the subscription. If the value is "VARIABLE" then amount can be changed for the subscription. Note: If "FIXED" is used then "currency", "recurringPaymentAmount" and "cycleFrequency" can't be updated

Response

200

responseCodestring
detailedResponseCodestring

Example response

{
  "subscription": {
    "customerName": "hsbc",
    "customerEmail": "sub.test@geidea.net",
    "customerPhoneCountryCode": "+971",
    "customerPhone": "529872786",
    "subscriptionId": "8a055aa4-13d9-4f74-421d-08dc3cbb381c",
    "merchantId": "0ee5274f-5b1a-4415-62a8-08dc20998061",
    "merchantPublicKey": "db5d957d-a0fd-4a1e-9312-5eb7ae6b3db4",
    "description": "Subscription #453293393959",
    "recurringPaymentAmount": 100,
    "currency": "AED",
    "startDate": "2024-03-08T00:00:00Z",
    "endDate": "2124-03-08T00:00:00Z",
    "cycleInterval": "Month",
    "cycleFrequency": 3,
    "occurrences": [
      {
        "occurrenceId": "9c6e2c11-82c1-4fc2-7e67-08dc3cbb3826",
        "subscriptionId": "8a055aa4-13d9-4f74-421d-08dc3cbb381c",
        "type": "Recurring",
        "amount": 100,
        "date": "2024-03-08T00:00:00Z",
        "status": "NotProcessed"
      }
    ],
    "nextOccurrenceDate": "2024-03-08T00:00:00Z",
    "status": "Created",
    "typeOfPayment": "RecurringPayment",
    "paylinkExpirationPeriod": 7,
    "customerId": "d0edbc67-38b9-4ef4-7329-08dc3cbb2fe8",
    "number": "453293393959",
    "language": "AR",
    "amountVariability": "FIXED",
    "isFirstPmtPBL": true,
    "createdDate": "2024-03-08T05:08:46.896845Z",
    "createdBy": "DirectApi",
    "updatedDate": "2024-03-08T05:08:46.896845Z"
  },
  "responseCode": "000",
  "detailedResponseCode": "000"
}

Changes

No recorded changes to this operation across all 1 revision of this API.