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 -