Home
SupportDashboard

Create Subscription

Suggest Edits

Paymob provides a subscription module for merchants to manage their subscriptions weekly, monthly, or yearly according to their needs.

You can contact your Account manager or you can raise the ticket through the portal to make your customized Subscription by giving information regarding the amount, time span, Retries, reminders, and all other related information regarding your subscription plan.

Once you get your "subscription_plan_id", you will utilize this subscription plan ID for the first/Initial 3DS transaction. After that Paymob's subscription module will manage your all subscriptions.

👍

Note:

Download the Subscription module Postman collection.

To start with the Subscription plan, you will follow the simple Payment API flow as given below :

1. Authentication Request:

The Authentication request is an elementary step you should do before dealing with any of Accept's APIs.
It is a post request with a JSON object that contains your api_key found in your dashboard - Profile tab.

URL: https://accept.paymob.com/api/auth/tokens

Method: POST

Source: Merchant's server

Recipient: Accept's server

Content-Type: JSON

Example request data: 

{
    "api_key": "ZXlKaGJHY2lPaUpJVXpVe..."
}
ParameterRequiredDescription
api_keyYesIt is a unique identifier for the merchant which used to authenticate your requests calling any of Accept's API.

Example response: 

{
    "token": "ZXlKaGJHY2lPaUpJVXpVeE1pSXNJ..."
}
ParameterRequired for the next requestDescription
tokenYesAuthentication token, which is valid for one hour from the creation time.

2. Order Registration API

At this step, you will register an order to Accept's database, so that you can pay for it later using a transaction.
Order ID will be the identifier that you will use to link the transaction(s) performed to your system, as one order can have more than one transaction.

URL: https://accept.paymob.com/api/ecommerce/orders

Method: POST

Source: Merchant's server

Recipient: Accept's server

Content-Type: JSON

Example request data: 

{
  "auth_token":  "ZXlKaGlPaUpJVXpVeE1pSX1Y0NJmV5Sn...",
  "delivery_needed": "false",
  "amount_cents": "100",
  "currency": "EGP",
  "merchant_order_id": 5,
  "items": [
    {
        "name": "ASC1515",
        "amount_cents": "500000",
        "description": "Smart Watch",
        "quantity": "1"
    },
    { 
        "name": "ERT6565",
        "amount_cents": "200000",
        "description": "Power Bank",
        "quantity": "1"
    }
    ],
  "shipping_data": {
    "apartment": "803", 
    "email": "[email protected]", 
    "floor": "42", 
    "first_name": "Clifford", 
    "street": "Ethan Land", 
    "building": "8028", 
    "phone_number": "+86(8)9135210487", 
    "postal_code": "01898", 
     "extra_description": "8 Ram , 128 Giga",
    "city": "Jaskolskiburgh", 
    "country": "CR", 
    "last_name": "Nicolas", 
    "state": "Utah"
  },
    "shipping_details": {
        "notes" : " test",
        "number_of_packages": 1,
        "weight" : 1,
        "weight_unit" : "Kilogram",
        "length" : 1,
        "width" :1,
        "height" :1,
        "contents" : "product of some sorts"
    }
}
ParameterRequiredDescription
auth_tokenYesThe authentication token obtained from Step 1
delivery_neededYesSet it to be true if your order needs to be delivered by Accept's product delivery services.
amount_centsYesThe price of the order is in cents.
merchant_order_idNoA unique alpha-numeric value, for example: "E6RR3".
Discard it from the request if you don't need it.
itemsYeslist of objects contains the contents of the order if it exists, send it as an empty array if it is not available. However, Mandatory for Souhoula and GET_GO payment methods.
shipping_dataNoMandatory if your order needs to be delivered, otherwise you can delete the whole object.
shipping_detailsNoMandatory if your order needs to be delivered, otherwise you can delete the whole object.

Example response:

{
  "id": 103,
  "created_at": "2017-01-10T05:41:15.700814Z",
  "delivery_needed": "false",
  "merchant": {
      "id": 28,
      "created_at": "2016-11-17T15:02:53.646620Z",
      "phones": [
          "011111111111",
          "012324151432"
      ],
      "company_emails": [
          "[email protected]",
          "[email protected]"
      ],
      "company_name": "Wuckert, Zieme and Dach",
      "state": "Oklahoma",
      "country": "Oman",
      "city": "Port Arvillachester",
      "postal_code": "83372",
      "street": "Walker Ramp"
  },
  "collector": "null",
  "amount_cents": 100,
  "shipping_data": {
      "id": 80,
      "first_name": "test",
      "last_name": "account",
      "street": "example",
      "building": "6",
      "floor": "4",
      "apartment": "404",
      "city": "cairo",
      "state": "egypt",
      "country": "egypt",
      "email": "[email protected]",
      "phone_number": "00201000212058",
      "postal_code": "123456",
      "extra_description": "test asdf",
      "shipping_method": "EM",
      "order_id": 103,
      "order": 103
  },
  "currency": "EGP",
  "is_payment_locked": "false",
  "merchant_order_id": "null",
  "wallet_notification": "null",
  "paid_amount_cents": 0,
  "items": []
}
ParameterRequired for the next requestDescription
idYesThis is the ID of your order in Accept's database, so you can use this reference to perform any action to this Order.

3. Payment Key Request

At this step, you have to pass "subscription_plan_id" with your integration ID so that this transaction would be considered the first transaction/Initial transaction associated with the mentioned subscription plan.

After that Payment will be deducted from the cardholder's account at your selected frequency which can be set as "weekly, biweekly, monthly, quarterly, Half Annual, and yearly".

you will obtain a payment_key token in response to this API. This key will be used to authenticate your payment request. It will be also used for verifying your transaction request metadata.

URL: https://accept.paymob.com/api/acceptance/payment_keys

Method: POST

Source: Merchant's server

Recipient: Accept's server

Content-Type: JSON

Example request data: 

{
  "auth_token": "ZXlKaGlPaUpJVXpVeE1pSX1Y0NJmV5Sn...",
  "amount_cents": "100", 
  "expiration": 3600, 
  "order_id": "103",
  "billing_data": {
    "apartment": "803", 
    "email": "[email protected]", 
    "floor": "42", 
    "first_name": "Clifford", 
    "street": "Ethan Land", 
    "building": "8028", 
    "phone_number": "+86(8)9135210487", 
    "shipping_method": "PKG", 
    "postal_code": "01898", 
    "city": "Jaskolskiburgh", 
    "country": "CR", 
    "last_name": "Nicolas", 
    "state": "Utah"
  }, 
  "currency": "EGP", 
  "integration_id": 1,
  "subscription_plan_id":12,
  "lock_order_when_paid": "false"
}
ParameterRequiredDescription
auth_tokenYesAuthentication token obtained from step 1.
amount_centsYesThe price should be paid through this payment channel with this payment key token.
expirationYesThe expiration time of this payment token is in seconds. (The maximum is 3600 seconds which is an hour)
order_idYesThe id of the order you want to perform this payment for.
billing_dataYesThe billing data related to the customer related to this payment.
All the fields in this object are mandatory, you can send any of this information if it isn't available, please send it to be "NA", except, first_name, last_name, email, and phone_number cannot be sent as "NA".
currencyYesThe currency related to this payment.
integration_idYesAn identifier for the payment channel you want your customer to pay through.
subscription_plan_idYesA unique identifier will be given to you by your account manager to link your transaction with the subscription plan.
lock_order_when_paidNoA flag prevents this order from being paid again if it is paid.

Sample response:

{
    "token": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6VX..."
}
ParameterRequired for the next requestDescription
tokenYesThe payment token that you will use with the pay API.

Updated 5 months ago