Overview
The order object is a core concept of the Prahsys Gateway API. In essence, the order object is the root object for the payment flow. It contains all the information about the payment, the customer, the merchant, and the transactions that occurred during that payment flow. An order represents the sale of goods/services by a merchant to a cardholder for a specified amount.
The order is the state of the payment flow and all the information about what has happened in the order thus far. It is the source of truth for the payment flow. The order is made up of several properties that describe the order, the customer, the merchant, the payment method, and the transactions that have occurred.
Order ID
Order IDs are generated by you and passed to the Prahsys Gateway API when you create an order. The order ID is a unique identifier for the order and is used to reference the order in subsequent API calls. By using the same order ID in each transaction, this will provide banks with the ability to link together related transactions.
Here is an example of initiating a checkout session then updating the session with the order ID.
Create Session
curl --request POST 'https://test-lighthouse.prahsys.com/api/rest/version/82/merchant/{{merchantId}}/session' \
--header 'Content-Type: application/json'
Update Session with Order ID
curl --request PUT '/merchant/{{merchantId}}/session/{{sessionId}}' \
--header 'Content-Type: application/json' \
--data '{
"order": {
"id":"{{orderId}}", <-- Generated by you
"amount": "100.00",
"currency": "USD"
}
}
'
Authorizing Payment
You must always authorize before capturing a payment. Authorizing ensures that the payment method is valid and that the funds are available for the capture.
To authorize an order for payment, you will need to update the order with the sourceOfFunds property on the
authorization request. You will either need to use the Prahsys Pay Portal (where we collect this sensitive financial information for you) or
use the Prahsys Pay Core (our API) to send over the collected payment information like in the shown example.
You will use the sessionId after the user completed the Hosted Checkout or Hosted Session form.
The session will be updated with the newly sourceOfFunds information and you will be able to see the payment
information in the response object.
Read more about Authorization Request
The transactionId must be unique. This is generated by you and sent to us. Every new transaction operation
(authorize, capture, refund) must have a new transactionId.
Here is an example of updating an order with the source of funds.
Authorize Order for Payment with Payment Information
curl --location --request PUT 'https://test-lighthouse.prahsys.com/api/rest/version/82/merchant/{{merchantId}}/order/{{orderId}}/transaction/{{transactionId}}' \
--header 'Content-Type: application/json' \
--data '{
"apiOperation": "AUTHORIZE",
"order": {
"amount": "100.00",
"currency": "USD"
},
"sourceOfFunds": {
"provided": {
"card": {
"nameOnCard": "Wayne Campbell",
"number": "4242424242424242",
"expiry": {
"month": "01",
"year": "2099"
},
"securityCode": "123"
}
}
},
"session": {
"id": "{{sessionId}}"
}
}
'
Capturing Payment
By this point, you have authorized the order and you are ready to capture the payment. Capturing the payment is
quite simple!
Because you have already authorized the order and said what sourceOfFunds you are using, you can now capture the
payment with a small light weight request.
Read more about Capture Request
The transactionId must be unique. This is generated by you and sent to us. Every new transaction operation
(authorize, capture, refund) must have a new transactionId.
No need to provide the sourceOfFunds property in the capture request. The sourceOfFunds is already stored in
the order object because of your previous authorization request.
Capture Payment for Order
curl --request PUT 'https://test-lighthouse.prahsys.com/api/rest/version/82/merchant/{{merchantId}}/order/{{orderId}}/transaction/{{transactionId}}' \
--header 'Content-Type: application/json' \
--data '{
"apiOperation": "CAPTURE",
"transaction": {
"amount": "100.00",
"currency": "USD"
}
}
'
Transactions
Transactions are the individual operations that occur on an order. These operations include authorizing, capturing, refunding, and voiding payments. Each transaction represents a distinct step in the payment process and contains crucial information about what occurred during that specific stage.
In the example request, we retrieve the order and we can see the transactions that occurred on the order.
Read more about Transaction Object
In the example response, we have simplified the object to make it easier to read. The actual response will contain more fields.
Fetch Order
curl --request GET 'https://test-lighthouse.prahsys.com/api/rest/version/82/merchant/{{merchantId}}/order/{{orderId}}' \
--header 'Content-Type: application/json'
Transaction ID
Transactions IDs are generated by you and passed to the Prahsys Gateway API when you want to perform an operation on a transaction (authorize, capture, refund, void). The transaction ID is a unique identifier for the transaction and will be seen in the Transaction Array inside the order object.
FAQ
When is an order complete?
An order is considered complete when the payment has been captured and the funds have been disbursed to the merchant. Though it is important to state that the order could be refunded or voided. In that case, that would be the end of the order. You cannot call the refund or void unless the order has been captured.
What are the requirements to capture a payment for an order?
To capture a payment for an order, you must have previously authorized the order. The order status must be in an AUTHORIZED state.
Do I collect the payment information or do you?
This is what a typical workflow would look like, where Prahsys would collect the user's payment information for you and mitigate your security liability at the same time:
