Direct Order API

This guide explains how to create direct order through API call . After calling the API successfully the user will be notified by email and/or SMS (according to API parameters).

REQUEST

testing server:

POST https://staging.xpay.app/api/orders/create-direct-order/

production(Live) server:

POST https://community.xpay.app/api/orders/create-direct-order/

Parameters

Authorization

This method requires authorization, supply the header with a key value pair with that structure

"x-api-key" : string

Required Properties

Property name	Value	Description	Notes
x-api-key	string	API key linked to your community	generate API key

Request body

Required Properties

Property name	Value	Description	Notes
name	string	direct order's name
community_id	string	ID that is uniques to your community
amount.amount	float	represents the amount you want to charge the user	if your community fees is Added in bill then use the value returned from prepare amount endpoint , otherwise use the amount you want to charge the user directly.
amount.currency	string	Currency	supported currencies are "EGP", "USD", "EUR", "SAR", "AED" and "GBP". default is "EGP"
payment_methods	array	allowed payment methods.	see payment available payment methods
customer_name	string	user first and last name	must contain first and last name in english letters with space between them.
customer_email	string	user email
customer_mobile	string	user phone number	must contain country code prefixed

danger

Hardcoding the customer data in the production version of your app will raise a risk in the payment processor and the transaction will be declined

Optional Properties

Property name	Value	Description	Notes
discount_amount.amount	float	will be subtracted from the amount
discount_amount.currency	string	supported "EGP", "USD", "EUR", "SAR", "AED" and "GBP".	default is "EGP"
allow_recurring_payments	boolean	Change from regular to reccuring payment	Needed if your payment is recurring
expiry_date	string	Expiry Date of the reccuring payment	Needed if your payment is recurring
minimum_days_between_payments	integer	Number of days between each payment	Needed if your payment is recurring
custom_fields	array	Custom Fields
order_description	string	Order description
address	string	billing address
customer_title	string	Customer title used when sending notification.	e.g. Mr, Mrs, Doctor,... etc.
vat_percentage	float	The percentage will be calculated and added to the amount.	will show in the payment pages as a separate entity titled VAT
send_by_email	boolean	If true notify customer by email .
cc_email	string	CC email in case of email sent.
send_by_sms	boolean	If true notify customer by mobile.
redirect_url	string	redirect url
callback_url	string	callback url
paid	boolean	default false	May be use in case of recurring payment and you want to mark the first payment as paid.
tags	string	payment tags see the example below

Response

If successful, this method returns a response body with the following structure:

{
    "status": {
        "code": 201,
        "message": "success",
        "errors": []
    },
    "data": {
        "success": true,
        "merchant_id": "xL4rPB7",
        "payment_id": "1BlbR48",
        "payment_link": "https://staging-iframe.xpay.app/i/community/xL4rPB7/direct-order/1BlbR48",
        "message": "Direct order created successfully. SMS and email notifications sent."
    },
    "count": null,
    "next": null,
    "previous": null
}

Property name	Value	Description	Notes
merchant_id	string	Merchant's id	Same as the community_id which sent in the request.
payment_id	string	Direct order's unique id
payment_link	string	Payment Link

Example

{
    "name": "Monthly rent",
    "address": "123 Main St, City",
    "order_description": "Monthly rent payment", 
    "customer_title": "Mr.", 
    "customer_name": "Mahmoud mmm", 
    "customer_email": "test@example.com", 
    "allow_recurring_payments": false, 
    "customer_mobile": "+201223456789", 
    "cc_email": "cc@example.com", 
    "amount": {
        "amount": 100.0,
        "currency": "EGP"
    },
    "discount_amount": {
        "amount": 10.0,
        "currency": "EGP"
    },
    "community_id": "xL4rPB7", 
    "paid": false, 
    "tags": [ 
        {
            "id": 1,
            "name": "test-checkoutpage"
        }
    ],
    "payment_methods": [ 
        "CARD",
        "FAWRY"
    ],
    "vat_percentage": 5.0, 
    "expiry_date": "2025-05-31", 
    "minimum_days_between_payments": 30, 
 "custom_fields": [
    {
      "field_label": "test label1",
      "field_type": "TEXT"
    },
    {
      "field_label": "check example",
      "field_type": "CHECKBOX"
    },
    {
      "field_label": "number example",
      "field_type": "NUMBER",
      "required": false
    },
    {
      "field_label": "drop down example",
      "field_type": "DROPDOWNLIST",
      "field_choices": "c1,c2,c3",
      "required": true
    }
  ],
    "send_by_email": true, 
    "send_by_sms": true, 
    "redirect_url": "https://webhook.site/90b597de-669b-499a-a595-423054d9d46d",
    "callback_url": "https://webhook.site/90b597de-669b-499a-a595-423054d9d46d"
}

{
    "status": {
        "code": 201,
        "message": "success",
        "errors": []
    },
    "data": {
        "success": true,
        "merchant_id": "xL4rPB7",
        "payment_id": "1BlbR48",
        "payment_link": "https://staging-iframe.xpay.app/i/community/xL4rPB7/direct-order/1BlbR48",
        "message": "Direct order created successfully. SMS and email notifications sent."
    },
    "count": null,
    "next": null,
    "previous": null
}

Recurring Payment

Just follow the example above and don't forget to include the recurring payment paramaters

Payment Options

There are four payment options available at the moment

card
kiosk (aman)
fawry (both kiosk and fawryPay)
mobile wallets
valU

Custom Fields

If you wish to request extra data from user during paymner, you can send custom fields array. each field in custom fields array contains:

Property name	Value	Description
field_label	string	label that will appears to the customer on payment
field_type	string	field type: TEXT, NUMBER, CHECKBOX or DROPDOWNLIST
required	boolean	optional parameter indicates if the field is mandatory
field_choices	string	only used in case of DROPDOWNLIST (comma separated values of the drop down list)

Example

Request body

{
  ....
  "custom_fields": [
    {
      "field_label": "test label1",
      "field_type": "TEXT"
    },
    {
      "field_label": "check example",
      "field_type": "CHECKBOX"
    },
    {
      "field_label": "number example",
      "field_type": "NUMBER",
      "required": false
    },
    {
      "field_label": "drop down example",
      "field_type": "DROPDOWNLIST",
      "field_choices": "c1,c2,c3",
      "required": true
    }
  ]
  ....
}

Redirect Url

if it is assigned then once the payment is completed a redirect to the url will happen and will contain the following as query paramaters:

Property name	Value	Description
total_amount_piasters	float	transaction amount in piasters
total_amount	float	transaction amount
transaction_uuid	string	transaction UUID in XPay system
transaction_status	string	transaction status

and if there iscustom fields then it will be included in query parameters

Callback url

If it is assigned, a POST request will be send after the customer pay the direct order with json body that includes:

Property name	Value	Description
total_amount_piasters	float	transaction amount in piasters
total_amount	float	transaction amount
transaction_uuid	string	transaction UUID in XPay system
transaction_status	string	transaction status

and if there is custom fields then it will be included in the request json body.

The following is an example of the parametes sent to callback url:

{
  "message": "SportingClub Monthly rent callback", // message describes the callback
  "member_id": null,
  "payment_id": "W29gzjQ", // Direct order's unique id
  "merchant_id": "xL4rPB7", // Merchant id
  "test label1": "",//custom field
  "total_amount": 99.99,
  "check example": true,//custom field
  "number example": "",//custom field
  "transaction_id": "0901eddd-f71c-4f31-81a9-f03d08c328b5",
  "drop down example": "c2",//custom field
  "transaction_status": "SUCCESSFUL",
  "total_amount_piasters": 9999
}