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
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/login 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
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/services 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
Data.id Category id Int Yes
Data.name_ar Category name (Arabic) String Yes
Data.name_en Category name (English) String Yes
Data.providers.name_ar Provider name (Arabic) String Yes
Data.providers.name_en Provider name ( English) String Yes
Data.providers.services.id Service id Int Yes
Data.providers.services.type 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
Data.providers.services.name_en Service name (English) String Yes
Data.providers.services.name_ar Service name (Arabic) String Yes
Data.providers.services.description_ar Service Description String No
(Arabic)
Data.providers.services.description_en Service Description String No
(English)
Data.providers.services. 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
Data.providers.services.action Action is the type of ----- -----
transaction requests that
you can call for this
service inquiry and
payment or payment only
Data.providers.services.action.type Inquiry means that you Enum Yes
can call inquiry request for
this service. Payment
means that you can call
payment request for this
service
Data.providers.services.action. 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
Data.providers.services.action. Service amount Double No
service_value
Data.providers.services.action. Service amount should be String No
service_service_value_list split using ;
Data.providers.services.action. Service min amount Double No
min_value
Data.providers.services.action. Service max amount Double No
max_value
Data.providers.services.action. Parameter ID Int Yes
parameters.id
Data.providers.services.action. Parameter key should be String Yes
parameters.key sent in transactions
-4-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Data.providers.services.action. Parameter name (Arabic) String Yes
parameters.name_ar
Data.providers.services.action. Parameter name (English) String Yes
parameters.name_en
Data.providers.services.action. Yes: if input is required Enum Yes
parameters.required No: if input in optional
Data.providers.services.action. N: input should be number Enum Yes
parameters.type C: input should be string
Data.providers.services.action. Min length for input Int No
parameters.min_length
Data.providers.services.action. Min length for input Int No
parameters.max_length
Data.providers.services.action. 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
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/inquiry 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
Data.amount Amount without Double Yes
commission
Data.fees Commission Double Yes
Data.totalAmount Amount with commission Double Yes
Data.asyncRqUID Should be included to String Yes
payment method if
available
Data.extraBillInfo Should be included to String Yes
payment method if
available
Data.billRefNumber Should be included to String Yes
payment method if
available
Data.statusDescription More description String Yes
-7-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
4- payment
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/payment 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
Data.amount Amount without Double Yes
commission
Data.fees Commission Double Yes
Data.totalAmount Amount with commission Double Yes
Data.reciept Reciept(what should print) Object Yes
-9-
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
Data.reciept.invoiceId Invoice Id Int Yes
Data.reciept.serviceName Service name String Yes
Data.reciept. providerName Provider name String Yes
Data.reciept date Date String Yes
Data.reciept.time Time String Yes
Data.reciept.fields Extra info that should be Array No
print
Data.reciept.fields.FieldName Field name String No
Data.reciept.fields. FieldValue Field Value String No
Data.reciept.inputs Data which entered Array No
Data.reciept. inputs.FieldName Data name String No
Data.reciept. inputs.FieldValue Data value String No
Data.statusDescription Status description String Yes
- 10 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
5- transactionStatus
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/transactionStatus 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
Data.amount Amount without Double Yes
commission
Data.fees Commission Double Yes
Data.totalAmount Amount with commission Double Yes
Data.reciept Reciept(what should print) Object Yes
Data.reciept.invoiceId Invoice Id Int Yes
Data.reciept.serviceName Service name String Yes
Data.reciept. providerName Provider name String Yes
Data.reciept date Date String Yes
Data.reciept.time Time String Yes
Data.reciept.fields Extra info that should be Array No
print
Data.reciept.fields.FieldName Field name String No
Data.reciept.fields. FieldValue Field Value String No
Data.reciept.inputs Data which entered Array No
Data.reciept. inputs.FieldName Data name String No
Data.reciept. inputs.FieldValue Data value String No
Data.statusDescription Status description String Yes
- 12 -
JOY FOR MARKETING SERVICES E-PAYMENTS API V1.0
6- getBalance
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/getBalance 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
https://us-central1-joybank-ecf6b.cloudfunctions.net/api/getHistory 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
Data.TimeStamp Operation date in String Yes
Unix Timestamp format
Data.TimeStamp.Before User’s credit before the String Yes
operation
Data.TimeStamp.After User’s credit after the String Yes
operation
Data.TimeStamp.Amount Operation total amount String Yes
Data.TimeStamp.Gain The returned obtained by String Yes
the user from the operation
Data.TimeStamp.reciept 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 -
