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 nameValueDescriptionNotes
x-api-keystringAPI key linked to your communitygenerate API key

​

Request body

Required Properties

Property nameValueDescriptionNotes
community_idstringID that is uniques to your community
amountfloatrepresents the amount you want to charge the userif 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_amountfloatrepresents the service cost without service feesthe amount you want to charge the user directly
currencystringCurrencysupported currencies are "EGP", "USD", "EUR", "SAR", "AED", "GBP" default is "EGP"
variable_amount_idintegerID that refrences an API Paymentcreate/view your api payments
pay_usingstringuser payment methodsee payment available payment methods
billing_data.namestringuser first and last namemust contain first and last name in english letters with space between them.
billing_data.emailstringuser email
billing_data.phone_numberstringuser phone numbermust 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 nameValueDescriptionNotes
membership_idstringID of your community member making the paymentNeeded if your API Payment requires a member id
is_recurringbooleanChange from regular to reccuring paymentNeeded if your payment is recurring
expiry_datestringExpiry Date of the reccuring paymentNeeded if your payment is recurring
minimum_days_between_paymentsintegerNumber of days between each paymentNeeded 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 nameValueDescriptionNotes
iframe_urlstringiframe urlyou can either embed that url in your website or redirect your user it so he/she can proceed with the payment process at.
transaction_idintegertransaction ID in XPay system
transaction_uuidstringtransaction UUID in XPay systemyou can use this value to retrieve transaction info in your app. see available payment methods
transaction_statusstringtransaction status

Example

 // 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 
}

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

{
  "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"
}

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 nameValueDescription
amount_piastersintegertransaction amount in piasters
amountintegertransaction amount
transaction_uuidstringtransaction UUID in XPay system
transaction_statusstringtransaction status

Callback url

Assign it from the dashboard once the payment is completed a POST request will be send with json body includes:

Property nameValueDescription
total_amount_piastersfloattransaction amount in piasters
total_amountfloattransaction amount
transaction_uuidstringtransaction UUID in XPay system
transaction_statusstringtransaction 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,
  "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,
  "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