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.

POST/v1/paymentjobs

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

POST

/v1/paymentjobs

curl https://payocityhub.com/api/v1/paymentjobs \
    -H "Authorization: Bearer {token}" \
    -H "x-signature: {signature}" \
    -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,
    "payment_method": "ideal",
    "paymentMethod": "ideal",
    "status": "SUCCESS",
    "pay_url": "https:\/\/demo.nl",
    "payUrl": "https:\/\/demo.nl",
    "attributes": {
        "return_url": "https:\/\/demo.nl\/payment\/pycideal\/callback",
        "returnUrl": "https:\/\/demo.nl\/payment\/pycideal\/callback",
        "report_url": "https:\/\/demo.nl\/payment\/pycideal\/notify",
        "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/v1/paymentjobs/:paymentjob_id

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

GET

/v1/paymentjobs/{paymentjob_id}

curl -G https://payocityhub.com/api/v1/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",
    "payment_method": "ideal",
    "paymentMethod": "ideal",
    "status": "SUCCESS",
    "pay_url": "https:\/\/demo.nl",
    "payUrl": "https:\/\/demo.nl",
    "attributes": {
        "return_url": "https:\/\/demo.nl\/payment\/pycideal\/callback",
        "returnUrl": "https:\/\/demo.nl\/payment\/pycideal\/callback",
        "report_url": "https:\/\/demo.nl\/payment\/pycideal\/notify",
        "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
}