Pay endpoint

This endpoint will take the required payment info and pass them to our Core Payment API and return the resultant response.

After the payment cycle ends, the user will be redirected to the url filled while creating the API Payment and will return member id and transaction id as query paramaters.

REQUEST

testing server:

POST https://staging.xpay.app/api/v1/payments/pay/variable-amount

production(Live) server:

POST https://community.xpay.app/api/v1/payments/pay/variable-amount

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
community_id	string	ID that is uniques to your community
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.
original_amount	float	represents the service cost without service fees	the amount you want to charge the user directly
currency	string	Currency	supported currencies are "EGP", "USD", "EUR", "SAR", "AED", "GBP" default is "EGP"
variable_amount_id	integer	ID that refrences an API Payment	create/view your api payments
pay_using	string	user payment method	see payment available payment methods
billing_data.name	string	user first and last name	must contain first and last name in english letters with space between them.
billing_data.email	string	user email
billing_data.phone_number	string	user phone number	must contain country code prefixed

danger

Hardcoding the billing 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
membership_id	string	ID of your community member making the payment	Needed if your API Payment requires a member id
is_recurring	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

Response

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

{
  "status": {
    "code": integer,
    "message": string,
    "errors": []
  },
  "data": {
    "iframe_url": string,
    "transaction_id": integer,
    "transaction_status": string,
    "transaction_uuid": string
  },
  "count": integer,
  "next": string,
  "previous": string
}

Property name	Value	Description	Notes
iframe_url	string	iframe url	you can either embed that url in your website or redirect your user it so he/she can proceed with the payment process at.
transaction_id	integer	transaction ID in XPay system
transaction_uuid	string	transaction UUID in XPay system	you can use this value to retrieve transaction info in your app. see available payment methods
transaction_status	string	transaction status

Example

Request Body
Response Body

 // payment with EGP currency
{
  "billing_data": {
    "name": "Islam Rostom",
    "email": "irostom@xpay.app",
    "phone_number": "+201119045759"
  },
  "amount": 53.36,
  "original_amount": 50, 
  "currency": "EGP", // default 
  "variable_amount_id": 4,
  "language":"en",
  "community_id": "zogDmQW",
  "pay_using": "card" // default 
}
 // payment with foreign currency say "USD"
{
    "billing_data": {
        "name": "Mahmoud Shehata",
        "email": "m@xpay.app",
        "phone_number": "+201551236623"
    },
    "amount": 10.27,
    "original_amount": 10, 
    "currency": "USD",
    "variable_amount_id": 25,
    "language": "en",
    "community_id": "zogDmQW",
    "pay_using": "card" // default 
}

{
  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  },
  "data": {
    "iframe_url": "https://dev-payment.xpay.app/core/payment_iframe/2733/",
    "transaction_id": 3220,
    "transaction_status": "PENDING",
    "transaction_uuid": "94fdb93f-c7f0-4b4d-8c8f-1c463c931344"
  },
  "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

Pay using any payment method

just follow the example above but replace the <pay_using> attribute in the request body to the desired payment method ("card" ,"fawry", "meeza/digital").

Pay using kiosk (aman)

to use payment using kiosk, change the value of <pay_using> attribute in the request body to "kiosk".

Request body

{
  "pay_using": "kiosk"
}

Response

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

{
  "status": {
    "code": integer,
    "message": string,
    "errors": []
  },
  "data": {
    "iframe_url": string,
    "transaction_id": integer,
    "transaction_status": string,
    "transaction_uuid": string,
    "message": string,
    "bill_refrence": integer
  },
  "count": integer,
  "next": string,
  "previous": string
}

Example

Request Body
Response Body

{
  "billing_data": {
    "name": "Islam Rostom",
    "email": "irostom@xpay.app",
    "phone_number": "+201119045759"
  },
  "amount_piasters": 5000,
  "variable_amount_id": 4,
  "community_id": "1",
  "pay_using": "kiosk"
}

{
  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  },
  "data": {
        "iframe_url": null,
        "transaction_id": 3220,
        "transaction_status": "PENDING",
        "transaction_uuid": "94fdb93f-c7f0-4b4d-8c8f-1c463c931344"
        "message": "Go to the nearest kiosk that has Masary/Aman payment machines and ask the seller to pay for(Madfouaat Mutanouea Accept مدفوعات متنوعة اكسبت) and give them that number 4424",
        "bill_reference": 4424
    },
  "count": null,
  "next": null,
  "previous": null
}

Custom Fields

If you wish to save extra data with the invoice data, you can send this data within the request body inside a new custom_fields parameter which takes an array of the following structure:

{
  "field_label": "custom field label value",
  "field_value": "custom field input value"
}

note

The field_value parameter can be string, number OR boolean.

Example

Request body

{
  ...
  "custom_fields": [
    {
      "field_label": "test label1",
      "field_value": "test one"
    },
    {
      "field_label": "test label3",
      "field_value": false
    },
    {
      "field_label": "test label2",
      "field_value": 25
    }
  ]
}

Redirect Url

Assign it from the dashboard once the payment is completed the url will contain the following as query paramaters:

Property name	Value	Description
amount_piasters	integer	transaction amount in piasters
amount	integer	transaction amount
transaction_uuid	string	transaction UUID in XPay system
transaction_status	string	transaction status

Callback url

Assign it from the dashboard once the payment is completed a POST request will be send with json body 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 request body sent to callback url in case of SUCCESSFUL transaction:

{
  "member_id": null,
  "payment_id": "25", // Variable amount's unique id (similar to the one sent in request)
  "merchant_id": "zogDmQW", // Merchant id  (similar to "community id" that sent in request)
  "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
}

The following is an example of the request body sent to callback url in case of FAILED transaction:

{
  "member_id": null,
  "payment_id": "25", // Variable amount's unique id (Similar to the one sent in the request)
  "merchant_id": "zogDmQW", // Merchant id  (Same as the community_id sent in the request)
  "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": "FAILED",
  "total_amount_piasters": 9999
}

Note: callback we be sent in case of success and failure of the transaction