Transactions API Guide

The *Transactions API allows users to retrieve a paginated list of transactions based on their status using the GET method. This API supports filtering transactions using the state parameter and provides details about each transaction, including the recipient, quote, and processing timestamps.

How It Works

The user sends a GET request to the transactions endpoint, optionally filtering by state (e.g., COMPLETED, PENDING, FAILED, REFUNDED).
The API returns a paginated list of transactions, including metadata such as totalPages, size, and page.
Each transaction includes details such as the recipient, payment channel, quote details, and processing timestamps.

Request Method & Endpoint

Endpoint:

GET https://{{baseURL}}/v1/transaction?state=COMPLETED&page=0&size=1

Query Parameters

Parameter	Type	Description	Required
`state`	String	Filter by transaction state (`COMPLETED`, `PENDING`, `FAILED`, `REFUNDED`)	✅ Yes
`page`	Integer	Page number (starting from `0`)	✅ Yes
`size`	Integer	Number of transactions per page	✅ Yes

Headers

Header	Value	Required
`Content-Type`	`application/json`	✅ Yes
`x-api-key`	`YOUR_API_KEY:<your-api-key>`	✅ Yes

cURL Request Example

curl --location --request GET 'https://{{baseURL}}/v1/transaction?state=COMPLETED&page=0&size=1' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY

Success Response (200 OK)

If the request is successful, the API returns the following JSON response:

response.json

{
    "message": "transactions fetched successfully",
    "page": 0,
    "size": 1,
    "totalPages": 1,
    "status": "success",
    "data": [
        {
            "id": "c18d83fe-cb89-470b-81c9-a563ac80f31b",
            "remark": "",
            "reason": "Gift",
            "referenceNumber": "TFDZQ3LOEGWXA",
            "type": "SEND",
            "state": "COMPLETED",
            "quote": {
                "id": "dafc0c85-576e-4dc1-a456-3f7db90b9a1c",
                "source": {
                    "currency": "NGN",
                    "country": "NG",
                    "amount": 18000.00
                },
                "target": {
                    "currency": "CNY",
                    "country": "CN",
                    "amount": 71.13
                },
                "rate": 253.05,
                "fee": {
                    "amount": 2060.00
                }
            },
            "recipient": {
                "name": "Zen Lui",
                "firstName": "Zen",
                "lastName": "Lui",
                "relationship": "SELF",
                "type": "MOBILE",
                "account": {
                    "sortCode": "",
                    "accountNumber": "8612343562723",
                    "branchCode": "",
                    "mobileProvider": ""
                },
                "paymentChannel": "ALI_PAY",
                "currency": "CNY",
                "country": "CN"
            },
            "created": "2025-02-27T14:11:09.720913",
            "processed": "2025-02-27T14:15:55.819866"
        }
    ]
}

Response Breakdown

General Information

Field	Type	Description
`message`	String	Response message
`page`	Integer	Current page number
`size`	Integer	Number of transactions per page
`totalPages`	Integer	Total number of pages available
`status`	String	Status of the response (`success` or `error`)

Transaction Details

Field	Type	Description
`id`	String	Unique transaction ID
`remark`	String	Additional transaction remarks
`reason`	String	Reason for the transaction (e.g., `Gift`)
`referenceNumber`	String	Unique reference number for tracking
`type`	String	Transaction type (e.g., `SEND`)
`state`	String	Transaction status (`COMPLETED`, `PENDING`, etc.)
`created`	String (ISO 8601)	Timestamp when the transaction was created
`processed`	String (ISO 8601)	Timestamp when the transaction was processed

Quote Details

Field	Type	Description
`quote.id`	String	Unique identifier for the quote
`quote.source.currency`	String	Source currency (e.g., `NGN`)
`quote.source.country`	String	Source country (e.g., `NG`)
`quote.source.amount`	Float	Amount sent in source currency
`quote.target.currency`	String	Target currency (e.g., `CNY`)
`quote.target.country`	String	Target country (e.g., `CN`)
`quote.target.amount`	Float	Amount received in target currency
`quote.rate`	Float	Exchange rate applied
`quote.fee.amount`	Float	Transaction fee applied

Recipient Details

Field	Type	Description
`recipient.name`	String	Full name of the recipient
`recipient.firstName`	String	First name of the recipient
`recipient.lastName`	String	Last name of the recipient
`recipient.relationship`	String	Relationship to the sender (e.g., `SELF`)
`recipient.type`	String	Payment type (e.g., `MOBILE`)
`recipient.account.accountNumber`	String	Account or mobile number
`recipient.paymentChannel`	String	Payment method (e.g., `ALI_PAY`)
`recipient.currency`	String	Recipient's currency
`recipient.country`	String	Recipient's country

Payout States

The transaction can have one of the following states:

State	Description
`COMPLETED`	The transaction was successfully processed.
`PENDING`	The transaction is still being processed.
`REFUNDED`	The transaction has been refunded.
`FAILED`	The transaction failed to process.

Error Handling

Status Code	Meaning	Example Response
`400`	Bad Request	`{ "message": "Invalid parameters" }`
`401`	Unauthorized	`{ "message": "Invalid API key" }`
`422`	Unprocessable Entity	`{ "message": "Invalid query parameters" }`
`500`	Internal Server Error	`{ "message": "An internal error occurred" }`

Key Takeaways

This API retrieves a paginated list of transactions based on their state.
Transactions include recipient details, quote information, and timestamps.
The state filter helps users get transactions in specific processing stages.

Best Practices

✅ Include a valid API key (x-api-key) in the request headers for authentication.
✅ Use pagination (page & size) to manage large transaction data efficiently.
✅ Filter transactions by state to retrieve relevant records.
✅ Ensure correct handling of timestamps (created & processed).

Funding your meCash Wallet Get Transactions