JOY FOR MARKETING SERVICES E-PAYMENTS API V1.
JOY FOR MARKETING SERVICES
E-PAYMENTS API
Documentation
-0-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
1- log in
URL Method Content-Type
[Link] POST application/json
Parameters needed
Code : user code
Password: user password
Request example
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
Response
{
"Status": true,
"Code": 200,
"Token": "TOKEN",
"Joyid": "TP8avWzSNXS6b5Z1n7Zt5YBT5Cv2",
"Name": "test",
"Balance": "13102.025"
}
Parameter Description Data Type Mandatory
Status True for correct Boolean Yes
requesting
False for errors
Code Status code Int Yes
Token Needed for the String Yes
other operation
Joyid User ID String Yes
Needed for the
other operation
Name User name String Yes
Balance User credit String Yes
-1-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
2- services
URL Method Content-Type
[Link] GET application/json
Description
All Joy available services
Request example
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
Response
{
"Code": 200,
"Msg": ""ناجحة عملية,
"Status": true,
"Data": [
{ "id": 2,
"name_ar": ""الموبايل فواتير دفع,
"name_en": "Mobile Bill Payment",
"providers": [
{
"name_ar": ""اتصاالت فواتير,
"name_en": "Etisalat Bills",
"services": [
{
"action": [
{
"parameters": [
{
"id": 189,
"key": "189",
"max_length": 11,
"min_length": 11,
"name_ar": ""الموبايل رقم,
"name_en": "Mobile",
"required": "yes",
"type": "N"
}
],
"type": "inquiry"
},
-2-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
{
"parameters": [
{
"id": 190,
"key": "190",
"max_length": 11,
"min_length": 11,
"name_ar": ""الموبايل رقم,
"name_en": "Mobile",
"parameter_inquiry_id": 189,
"required": "yes",
"type": "N"
}
],
"price_type": 0,
"type": "payment"
}
],
"id": 79,
"name_ar": ""فواتير,
"name_en": "Bill Payment",
"request_amount_input": "no",
"type": "inquiry_payment"
}
]
},
Parameter Description Data Mandatory
Type
Status True for correct requesting Boolean Yes
False for errors
Code Status code Int Yes
Msg Status massage String Yes
Data Object of data Object Yes
[Link] Category id Int Yes
Data.name_ar Category name (Arabic) String Yes
Data.name_en Category name (English) String Yes
[Link].name_ar Provider name (Arabic) String Yes
[Link].name_en Provider name ( English) String Yes
[Link] Service id Int Yes
[Link] Payment: if service should Int Yes
paid directly, so you
should call payment
function directly without
call inquiry. like (mobile
top-up, donations )
-3-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
inquiry_payment: if
service needs to make
inquiry before call
payment like (Mobile Bills,
ADSL Bills
[Link].name_en Service name (English) String Yes
[Link].name_ar Service name (Arabic) String Yes
[Link].description_ar Service Description String No
(Arabic)
[Link].description_en Service Description String No
(English)
[Link]. Yes: to display amount Enum Yes
request_amount_input input in service and fill by
user like (Mobile top-up)
user should fill the amount
No: to be hidden and
system should send the
amount directly from
backend
[Link] Action is the type of ----- -----
transaction requests that
you can call for this
service inquiry and
payment or payment only
[Link] Inquiry means that you Enum Yes
can call inquiry request for
this service. Payment
means that you can call
payment request for this
service
[Link]. 0 : amount must be Enum Yes
price_type Between Min Max Value
1 : amount should be
Equals Service Value
3 : amount should be One
of Service Value List
4: amount should be get
from inquiry first
[Link]. Service amount Double No
service_value
[Link]. Service amount should be String No
service_service_value_list split using ;
[Link]. Service min amount Double No
min_value
[Link]. Service max amount Double No
max_value
[Link]. Parameter ID Int Yes
[Link]
[Link]. Parameter key should be String Yes
[Link] sent in transactions
-4-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
[Link]. Parameter name (Arabic) String Yes
parameters.name_ar
[Link]. Parameter name (English) String Yes
parameters.name_en
[Link]. Yes: if input is required Enum Yes
[Link] No: if input in optional
[Link]. N: input should be number Enum Yes
[Link] C: input should be string
[Link]. Min length for input Int No
parameters.min_length
[Link]. Min length for input Int No
parameters.max_length
[Link]. Id of same parameter in Int Yes
parameters.parameter_inquiry_id inquiry action
-5-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
3- inquiry
URL Method Content-Type
[Link] POST application/json
Description
To make inquiry transaction
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
joyid From login method String Header Yes
token From login method String Header Yes
service_id Service ID from Int Body Yes
service list
parameters Array of service Array Body Yes
parameters using
below format
[{“parameterKey”:”value”}]
• Response
{
"Code": 200,
"Msg": "sucsess",
"Status": true,
"ServiceId": 26,
"Data": {
"amount": 479.5,
"fees": 5.2,
"totalAmount": 484.7,
"asyncRqUID": null,
"extraBillInfo": null,
"billRefNumber": null,
"statusDescription:": ""ناجحة عملية
}
}
-6-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Parameter Description Data Mandatory
Type
Status True for correct requesting Boolean Yes
False for errors
Code Status code Int Yes
Msg Status massage String Yes
ServiceId service ID Int Yes
Data Object of data Object Yes
[Link] Amount without Double Yes
commission
[Link] Commission Double Yes
[Link] Amount with commission Double Yes
[Link] Should be included to String Yes
payment method if
available
[Link] Should be included to String Yes
payment method if
available
[Link] Should be included to String Yes
payment method if
available
[Link] More description String Yes
-7-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
4- payment
[Link] POST application/json
Description
To make payment transaction
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
joyid From login method String Header Yes
token From login method String Header Yes
service_id Service ID from Int Body Yes
service list
parameters Array of service Array Body Yes
parameters using
below format
[{“parameterKey”:”value”}]
amount Amount should pay Double Body Yes
(if amount should be send)
fees Fees should pay Double Body Yes
(if amount should be send)
asyncRqUID If available in inquiry request String Body Yes
If not send null
extraBillInfo If available in inquiry request String Body Yes
If not send null
billRefNumber If available in inquiry request String Body Yes
If not send null
-8-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
• Response
{
"Code": 200,
"Msg": "sucsess",
"Status": true,
"ServiceId": 4,
"Data": {
"amount": 0,
"fees": 3.57,
"totalAmount": 120.07,
"reciept": {
"invoiceId": "29548282",
"serviceName": ""سداد فاتورة التليفون,
"providerName": ""المصرية لإلتصاالت,
"invoiceDescription": "null",
"date": "2020/8/12",
"time": "14:13",
"fields": null,
"inputs":[
{
"FieldName": ""كود المحافظة,
"FieldValue": "03"
},
{
"FieldName": ""رقم التليفون
"FieldValue": "5461131"
}
]
},
"statusDescription:": "Success"
}
}
Parameter Description Data Mandatory
Type
Status True for correct requesting Boolean Yes
False for errors
Code Status code Int Yes
Msg Status massage String Yes
ServiceId service ID Int Yes
Data Object of data Object Yes
[Link] Amount without Double Yes
commission
[Link] Commission Double Yes
[Link] Amount with commission Double Yes
[Link] Reciept(what should print) Object Yes
-9-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
[Link] Invoice Id Int Yes
[Link] Service name String Yes
[Link]. providerName Provider name String Yes
[Link] date Date String Yes
[Link] Time String Yes
[Link] Extra info that should be Array No
print
[Link] Field name String No
[Link]. FieldValue Field Value String No
[Link] Data which entered Array No
[Link]. [Link] Data name String No
[Link]. [Link] Data value String No
[Link] Status description String Yes
- 10 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
5- transactionStatus
[Link] POST application/json
Description
To check transaction status and print
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
joyid From login method String Header Yes
token From login method String Header Yes
UTID invoiceId which want to Int Body Yes
inquiry about
• Response
{
"Code": 200,
"Msg": "sucsess",
"Status": true,
"Data": {
"amount": 5,
"fees": 0.2,
"totalAmount": 5.2,
"reciept": {
"invoiceId": "29491796",
"serviceName": ""االسكندرية مياه شركة,
"providerName": "االسكندرية مياه شركة ",
"invoiceDescription": "null",
"date": "2020/8/9",
"time": "17:19",
"fields": null,
"inputs": [
{
"FieldName": ""االشتراك رقم,
"FieldValue": "10080000034701"
},
{
"FieldName": "FCRN",
"FieldValue": "4475246316"
}
]
},
"statusDescription:": ""ناجحة عملية
}
}
- 11 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Parameter Description Data Mandatory
Type
Status True for correct requesting Boolean Yes
False for errors
Code Status code Int Yes
Msg Status massage String Yes
ServiceId service ID Int Yes
Data Object of data Object Yes
[Link] Amount without Double Yes
commission
[Link] Commission Double Yes
[Link] Amount with commission Double Yes
[Link] Reciept(what should print) Object Yes
[Link] Invoice Id Int Yes
[Link] Service name String Yes
[Link]. providerName Provider name String Yes
[Link] date Date String Yes
[Link] Time String Yes
[Link] Extra info that should be Array No
print
[Link] Field name String No
[Link]. FieldValue Field Value String No
[Link] Data which entered Array No
[Link]. [Link] Data name String No
[Link]. [Link] Data value String No
[Link] Status description String Yes
- 12 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
6- getBalance
[Link] GET application/json
Description
To get user’s credit
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
joyid From login method String Header Yes
token From login method String Header Yes
• Response
{
"Code": 200,
"Status": true,
"Id": "TP8avWzSNXS6b5Z1n7Zt5YBT5Cv2",
"Balance": "102.02"
}
Parameter Description Data Mandatory
Type
Status True for correct Boolean Yes
requesting
False for errors
Code Status code Int Yes
Id User ID String Yes
Balance User balance Double Yes
- 13 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
6- getHistory
[Link] GET application/json
Description
To get user’s old operations
Parameter Value Type Position Mandatory
code User code String Header Yes
password User password String Header Yes
joyid From login method String Header Yes
token From login method String Header Yes
• Response
{
"Code": 200,
"Status": true,
"Id": "TP8avWzSNXS6b5Z1n7Zt5YBT5Cv2",
"Data": {
"1582223830568": {
"After": "4992.939375",
"Amount": "7.15",
"Before": "5000.0",
"Gain": "0.08937500000000001",
"reciept": "538"
},
}
- 14 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Parameter Description Data Mandatory
Type
Status True for correct requesting Boolean Yes
False for errors
Code Status code Int Yes
Id User ID String Yes
Data Object of data Object Yes
[Link] Operation date in String Yes
Unix Timestamp format
[Link] User’s credit before the String Yes
operation
[Link] User’s credit after the String Yes
operation
[Link] Operation total amount String Yes
[Link] The returned obtained by String Yes
the user from the operation
[Link] Operation Id which used to String Yes
inquiry about it or print it
- 15 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Status Code values
Code Description
302 Authentication Error
200 Successful Transaction
301 Transaction Error
103 Validation Error
- 16 -