List Cash Collection Transactions

The Payiano's list transactions endpoint allows partners to see a comprehensive list of all payment transactions they've collected or need to be collected on behalf of the Payiano. It's similar to checking a bank statement, where you can view all the transactions processed through the partner's platform. This endpoint is invaluable for partners to keep track of payments, monitor transaction statuses over time. It ensures transparency and helps in managing financial records efficiently.

GET/cash_collection/transactions
Sandbox: https://api-partner.payiano.dev/v1/cash_collection/transactions
Live: https://api-partner.payiano.com/v1/cash_collection/transactions
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
Query parameters:
page
Type: integer|null
Default: 1

The page number to be retrieved, for the list of transactions. So, a combination of page=1 and per_page=25 returns the first 25 transactions. A combination of page=2 and per_page=25 returns the next 25 transactions.

per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]

The maximum number of transactions to return in the response.

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:
total_pages
Type: integer

The total number of pages that are available for the transactions search criteria.

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of transactions items return per page.

total_items
Type: integer

The total number of transactions that match the search criteria.

items
Type: array_of_objects

The list of transactions that match the search criteria.

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 "per_page": 25, 3 "total_pages": 1, 4 "total_items": 1, 5 "current_page": 1, 6
"items": [
7
{
8 "id": "01hqpes2y80bgzsemcv93b8fvj", 9 "currency_code": "EGP", 10 "amount": 1140, 11 "reference_id": null, 12 "inquiry_code": 313222, 13 "expires_at": "1722572118554", 14 "is_expired": false, 15 "payer_id": "01hqpesc925831rw4gt5vgdrgp", 16
"payer": {
17 "id": "01hqpqw63s6jg9nq8m4fpddrmn", 18 "name": "Mohsen Ali", 19 "email": "mohsen@gawaab.com", 20 "phone_number": "+201000333000", 21 "created_at": "1722572118554", 22 "updated_at": "1722572118554" 23 }, 24 "paid_at": null, 25 "is_paid": false, 26 "created_at": "1722572118554", 27 "updated_at": "1722572118554" 28 } 29 ] 30}