Paymentjobs
Paymentjobs are the term we use for a transaction in the HUB, since every payment is a job in itself. A Payment Job represents a unit of work responsible for handling financial transactions within our HUB's infrastructure. It acts as a mediator between various integrations/payment methods, orchestrating the flow of funds securely and efficiently.
The paymentjob model
The paymentjob model contains all the information about the transaction between you and POS in the HUB. Payment Jobs are responsible for initiating, tracking, and managing transactions. Developers can use the API to create, retreive transactions, ensuring seamless money transfers.
Properties
- Name
paymentJob- Type
- string
- Description
Unique identifier of the paymentjob.
- Name
orderId- Type
- integer
- Description
Unique identifier of the object that needs to be paid for.
- Name
orderNumber- Type
- string
- Description
Unique identifier of the object that needs to be paid for.
- Name
created- Type
- timestamp
- Description
Timestamp of when the paymentjob was created on.
- Name
lastUpdate- Type
- timestamp
- Description
Timestamp of when the paymentjob was last updated.
- Name
language- Type
- string
- Description
Language the transaction was started in.
- Name
currency- Type
- string
- Description
Currency the transaction was started in.
- Name
amountDue- Type
- float
- Description
Amount that is due for payment.
- Name
amountPaid- Type
- float
- Description
Amount that has been paid.
- Name
paymentMethod- Type
- string
- Description
Payment method selected for the transaction.
- Name
status- Type
- string
- Description
Status of the transaction.
- Name
payUrl- Type
- string
- Description
The URL the paying customer can be redirected to, to perform the payment.
- Name
attributes- Type
- array
- Description
Additional attributes for this paymentjob, could contain return_url and report_url.
- Name
payments- Type
- array
- Description
Complete trace of what happened to the paymentjob.
- Name
error- Type
- string
- Description
If an error occured announcing the transaction, or something else went wrong.
Create a paymentjob
Developers can create a Payment Job by sending a POST request to the designated endpoint. This action initiates a new payment transaction and returns a unique identifier (Job ID) that can be used to track and manage the transaction.
Required parameters
- Name
timestamp- Type
- string
- Description
Unix timestamp of the order announcement. As a rule this is the current date and time.
- Name
currency- Type
- string
- Description
Currency the transaction was started in.
- Name
amount- Type
- float
- Description
Amount that is due for payment.
- Name
return_url- Type
- string
- Description
The URL the paying customer can be redirected back to, once the payment is done.
- Name
report_url- Type
- string
- Description
The callback URL the HUB can use to send a POST request to, once the notification of the PSP has been received.
- Name
payment_method- Type
- string
- Description
Payment method selected for the transaction.
- Name
order_id- Type
- integer
- Description
Unique identifier of the object that needs to be paid for.
- Name
order_number- Type
- string
- Description
Unique identifier of the object that needs to be paid for.
- Name
language- Type
- string
- Description
Language the transaction was started in.
- Name
ip_address- Type
- string
- Description
IP address of the customer.
Request
curl https://api.payocityhub.com/v2/paymentjobs \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json"
-d '{
"timestamp": 1694960469,
"currency": "EUR",
"amount": 23.9,
"return_url": "https:\/\/demo.nl\/payment\/pycideal\/callback",
"report_url": "https:\/\/demo.nl\/payment\/pyc\/notify",
"payment_method": "ideal",
"order_id": "12345",
"order_number": "12345",
"language": "en",
"ip_address": "12.345.678.90"
}'
Response
{
"paymentJob": "ba984c1f-eab5-4c75-a57e-51d28a6f9386",
"orderId": "12345",
"orderNumber": "12345",
"created": "2023-09-17T14:21:09.000000Z",
"lastUpdate": "2023-09-17T14:21:52.000000Z",
"language": "en",
"currency": "EUR",
"amountDue": "26.80",
"amountPaid": 0,
"paymentMethod": "ideal",
"status": "SUCCESS",
"payUrl": "https:\/\/demo.nl",
"attributes": {
"returnUrl": "https:\/\/demo.nl\/payment\/pycideal\/callback",
"reportUrl": "https:\/\/demo.nl\/payment\/pycideal\/notify"
},
"payments": {
"steps": [
{
"creationDate": "2023-09-17T14:21:09.877579Z",
"transactionId": "3facab28-dada-4fc1-9bdf-25915f0188b4",
"action": "Start",
"status": "PENDING",
"amountDue": "26.80",
"amountPaid": "0.00"
}
]
},
"error": null
}
Get a paymentjob
By making GET requests with the paymentjob ID, developers can retrieve real-time information about the status of a Payment Job. This allows applications to provide users with up-to-date information about their transactions.
Request
curl -G https://api.payocityhub.com/v2/paymentjobs/{paymentjob_id} \
-H "Authorization: Bearer {token}"
Response
{
"paymentJob": "ba984c1f-eab5-4c75-a57e-51d28a6f9386",
"orderId": "12345",
"orderNumber": "12345",
"created": "2023-09-17T14:21:09.000000Z",
"lastUpdate": "2023-09-17T14:21:52.000000Z",
"language": "en",
"currency": "EUR",
"amountDue": "0.00",
"amountPaid": "23.90",
"paymentMethod": "ideal",
"status": "SUCCESS",
"payUrl": "https:\/\/demo.nl",
"attributes": {
"returnUrl": "https:\/\/demo.nl\/payment\/pycideal\/callback",
"reportUrl": "https:\/\/demo.nl\/payment\/pycideal\/notify"
},
"payments": {
"creationDate": "2023-09-17T14:21:51.693034Z",
"status": "SUCCESS",
"amountDue": "0.00",
"amountPaid": "23.90",
"steps": [
{
"creationDate": "2023-09-17T14:21:09.877579Z",
"transactionId": "edcb5756-0ed4-48d0-9c2a-705dd5448e83",
"action": "Start",
"status": "PENDING",
"amountDue": "23.90",
"amountPaid": "0.00"
},
{
"creationDate": "2023-09-17T14:21:51.693000Z",
"action": "Return",
"status": "SUCCESS",
"amountDue": "0.00",
"amountPaid": "23.90"
},
{
"creationDate": "2023-09-17T14:21:52.157430Z",
"action": "Statuspull",
"status": "SUCCESS",
"amountDue": "0.00",
"amountPaid": "23.90"
}
]
},
"error": null
}