Retrieve Cash Collection Transaction

The Payiano's inquiry transaction endpoint serves as a detective tool for partners, enabling them to investigate the status of a transaction or verify its details. Suppose a customer inquires whether their payment has been processed successfully. In that case, partners can use this endpoint to look up the transaction using its unique identifier and provide real-time updates on its status. It's a way to offer peace of mind to both the partner and the customer by ensuring transparency and building trust.

To access transaction details, there are several methods available. You can use the transaction ID, inquiry code, or reference ID. To do this, simply send a request to /cash_collection/transactions/{id}, accompanied by the identify_by query parameter. The value of this parameter can be set to either id, inquiry_code, or reference_id, depending on the identifier you wish to use. This flexibility allows for a variety of ways to access transaction details. For more detailed instructions on how to identify a resource using these methods, please refer to the Identify Resource section.

Note that the default identify_by query parameter value is id.

GET/cash_collection/transactions/{id}
Sandbox: https://api-partner.payiano.dev/v1/cash_collection/transactions/{id}
Live: https://api-partner.payiano.com/v1/cash_collection/transactions/{id}
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to this permission cash_collection_transactions_view
Request
Request body schema:
application/json
Path parameters:
id
required
Type: ulid
Length: 26

The unique ID assigned to each transaction which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every transaction. This ULID is automatically created by our system and is used to uniquely identify and track each transaction in our database.

Query parameters:
identify_by
Type: enum|null
Possible values:
[
"id", "reference_id", "inquiry_code" ]

This attribute specifies which identifier is being used to interact with a resource in the Payiano API. It helps the system understand how to identify resource when processing API requests. By default, the identify_by attribute is set to id, so you only need to specify it if you're using a different identifier.

includes
Type: array_of_enums|null
Possible values:
[
"transaction.payer" ]

A list of additional transaction relations to return, if available. Feel free to send the relations you would like to return with every item. See Including Resources to better understand how this is working.

Response
200
Response schema:
application/json
Response body:
transaction
Type: object

The transaction model details.

id
Type: ulid
Length: 26

The unique ID assigned to each transaction which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every transaction. This ULID is automatically created by our system and is used to uniquely identify and track each transaction in our database.

currency_code
Type: enum
Possible values:
[
"EGP" ]

The three-character ISO-4217 Currency Code that identifies the currency for the transaction. Your business should be eligible to use the selected currency code.

amount
Type: decimal

The amount value that needs to be collected for the transaction. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each transaction. It's primary role is to distinguish one transaction from another, ensuring that each transaction can be individually tracked and managed without any confusion. Please notice that duplicate values are not allowed and it's allowed to use alpha dash only [A-Za-z0-9-_]. The reference_id value is used to Identify Resource when you consume any transaction endpoint with sending identify_by query parameter with value reference_id.

inquiry_code
Type: integer

This attribute represents the unique inquiry code that customers must provide to the partner. This code is essential for partners to look up the transaction details and to process the payment on behalf of the customer. It serves as a key to access specific transaction information, ensuring that payments are accurately matched to the correct transaction. You can simulate a complete transaction payment through our Pay Order POS terminal flow to test this service effectively. This allows for a hands-on experience to ensure that the payment process is efficient and user-friendly at actual retail locations.

expires_at
Type: datetime|null

It indicates when the transaction becomes invalid. It ensures payments are made within a specified timeframe, useful for time-sensitive offers. It informs both the payer and the recipient about the exact deadline until which the payment can be processed. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

is_expired
Type: boolean

This attribute indicates whether the transaction is expired or not. If the transaction expires_at attribute is filled, then this attribute value will be true.

payer_id
Type: ulid

This field is the key to associating each transaction with the correct payer, enhancing the personalization and accuracy of the transaction process. It's not only enhances transaction precision but also contributes significantly to effective payer relationship management and data analysis.

payer
Type: object

The payer model for the transaction.

id
Type: ulid
Length: 26

The unique ID assigned to each payer which is generated by our system using the ULID format. Each ID is precisely 26 characters long, ensuring a unique and consistent identifier for every payer. This ULID is automatically created by our system and is used to uniquely identify and track each payer in our database.

name
Type: string
Min: 2
Max: 100

This is the fundamental attribute representing the payer's full legal or preferred name. It's used in all forms of communication and identification. It's crucial for personalization and ensures that all correspondences and documents are correctly addressed.

email
Type: string
Min: 5
Max: 255

The email address is a key point of contact for digital communication. It's used for sending transactional emails, marketing material and support communications.

phone_number
Type: string

This attribute stores the payer's mobile number. It's essential for direct contact, SMS notifications, and can also be used in cases where email communication is insufficient or inappropriate.

created_at
Type: datetime

The created datetime of the payer. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

updated_at
Type: datetime

The updated datetime of the payer. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

paid_at
Type: datetime|null

This attribute indicates the exact timestamp when the transaction was paid. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

is_paid
Type: boolean

This attribute indicates whether the transaction is paid or not. If the transaction paid_at attribute is filled, then this attribute value will be true.

created_at
Type: datetime

The created datetime of the transaction. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

updated_at
Type: datetime

The updated datetime of the transaction. This attribute can be formatted as an ISO 8601 string or a UNIX timestamp in milliseconds, depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or 1722572118554). By default, the format is UNIX timestamp in milliseconds.

Response sample:
1
{
2
"transaction": {
3 "id": "01hqpes2y80bgzsemcv93b8fvj", 4 "currency_code": "EGP", 5 "amount": 1140, 6 "reference_id": null, 7 "inquiry_code": 313222, 8 "expires_at": "1722572118554", 9 "is_expired": false, 10 "payer_id": "01hqpesc925831rw4gt5vgdrgp", 11
"payer": {
12 "id": "01hqpqw63s6jg9nq8m4fpddrmn", 13 "name": "Mohsen Ali", 14 "email": "mohsen@gawaab.com", 15 "phone_number": "+201000333000", 16 "created_at": "1722572118554", 17 "updated_at": "1722572118554" 18 }, 19 "paid_at": null, 20 "is_paid": false, 21 "created_at": "1722572118554", 22 "updated_at": "1722572118554" 23 } 24}