Verify Single Payment

Use this endpoint to retrieve the latest status of a single payment using the onusReference you received during initiation.

• Path: /api/v1/payment-requests/businesses/{businessId}
• Method: GET
• Query Params:
• onusReference (string, required): The reference returned by PayOnUs during payment initiation.

Example:

GET https://core-sandbox.payonus.com/api/v1/payment-requests/businesses/{businessId}?onusReference={onus_reference}

Headers

• Accept: application/json
• Authorization: Bearer {merchant_api_bearer_token}

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": "xxx-xxx-xxx-xxx-xxx",
    "merchantUserId": null,
    "amount": 100.00,
    "amountPaid": 100.00,
    "settlementAmount": 95.00,
    "acceptablePaymentType": "ACCEPT_FULL_VALUE_ONLY",
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "countryCode": "NG",
    "paymentGateway": "SAFEHAVENMFB",
    "accountNumber": "60222xxxxx",
    "accountName": "Merchant Checkout",
    "email": "test@merchant.com",
    "mobileNumber": "+2347012345678",
    "bankName": "SAFE HAVEN MFB",
    "bankCode": "090286",
    "totalChargedFee": 5.00,
    "transactionFee": 5.00,
    "providerFee": 0.00,
    "vat": 0.00,
    "providerVat": 0.00,
    "stampDutyApplied": false,
    "waveStampDuty": false,
    "forWalletFunding": false,
    "onusReference": "ONUS-NUB-1234567890123-01012025-110010",
    "reference": "ONUS-NUB-1234567890123-01012025-110010",
    "sessionId": "100033250101110010728767414342",
    "providerReference": "100033250101110010728767414342",
    "merchantReference": "xxx-xxx-xxx-xxx-xxx",
    "notificationUrl": null,
    "redirectUrl": null,
    "senderName": "Merchant Checkout",
    "senderAccount": "SafeHaven Microfinance Bank",
    "senderAccountNumber": "7087654321",
    "merchantNotified": false,
    "forwardedForSettlement": true,
    "ipAddress": "127.0.0.1",
    "narration": "Merchant Collection",
    "paymentStatus": "SUCCESSFUL",
    "createdDate": "2025-01-01 11:00:11",
    "lastUpdatedDate": "2025-01-01 11:00:11",
    "merchantCheckoutReference": null,
    "providerResponse": null,
    "businessName": "Test Business",
    "merchantName": "Test Merchant",
    "businessId": "xxx-xxx-xxx-xxx-xxx",
    "fixedAccount": false,
    "fixedAccountId": "xxx-xxx-xxx",
    "fixedAccountMerchantReference": "xxx-xxx-xxx"
  }
}

Notes: - Always store both your merchantReference and our onusReference so you can reconcile and query later. - This endpoint is applicable to all Payins methods (Card, Dynamic Account, Fixed Account, Mobile Money).

---

List Payment Requests

Search and page through payment requests using query parameters.

• Method: GET
• Path: /api/v1/payment-requests

When to use this endpoint

Use this endpoint to list payment requests your application has created or can access, with optional filtering (e.g., status, reference, date range) and pagination.

If the token is missing or invalid, the API returns 401 Unauthorized. If the token lacks the required authority, the API returns 403 Forbidden.

Request

• HTTP method: GET
• URL: /api/v1/payment-requests
• Query parameters:
  • status: Payment request status (e.g., PROCESSING, PENDING, SUCCESSFUL, FAILED)
  • businessId: UUID of the business
  • reference: Merchant reference
  • onusReference: Onus-generated reference
  • fromDate / toDate: ISO-8601 dates for filtering by creation time (e.g., 2025-01-01)
• Pagination
  • page: Zero-based page index (e.g., 0)
  • size: Page size (e.g., 20)

Notes: - All query parameters must be provided on the URL (no request body). - Parameters are validated; invalid values result in 400 Bad Request with details.

Responses

• 200 OK — A paginated list of payment requests
• 400 Bad Request — Invalid query parameter(s)
• 401 Unauthorized — Missing or invalid token
• 403 Forbidden — Insufficient authority

200 OK — Response body

Type: PaginatedResponse<PaymentRequest>

PaginatedResponse<T> typically contains the following fields: - content: Array of PaymentRequest - page: Current page index (number) - size: Page size (number) - totalElements: Total number of items across all pages (number) - totalPages: Total number of pages (number) - sort: Sort expression applied (string or array)

Example:

{
  "status": 200,
  "message": "Success",
  "data": {
    "pageNo": 1,
    "pageSize": 30,
    "lastPage": 1,
    "totalNumberOfItems": 1,
    "content": [
      {
        "id": "xxx-xxx-xxx-xxx-xxx",
        "merchantUserId": null,
        "amount": 100.00,
        "amountPaid": 100.00,
        "settlementAmount": 95.00,
        "acceptablePaymentType": "ACCEPT_FULL_VALUE_ONLY",
        "paymentChannel": "BANK_TRANSFER",
        "currency": "NGN",
        "countryCode": "NG",
        "paymentGateway": "SAFEHAVENMFB",
        "accountNumber": "60222xxxxx",
        "accountName": "Merchant Checkout",
        "email": "test@merchant.com",
        "mobileNumber": "+2347012345678",
        "bankName": "SAFE HAVEN MFB",
        "bankCode": "090286",
        "totalChargedFee": 5.00,
        "transactionFee": 5.00,
        "providerFee": 0.00,
        "vat": 0.00,
        "providerVat": 0.00,
        "stampDutyApplied": false,
        "waveStampDuty": false,
        "forWalletFunding": false,
        "onusReference": "ONUS-NUB-1234567890123-01012025-110010",
        "reference": "ONUS-NUB-1234567890123-01012025-110010",
        "sessionId": "100033250101110010728767414342",
        "providerReference": "100033250101110010728767414342",
        "merchantReference": "xxx-xxx-xxx-xxx-xxx",
        "notificationUrl": null,
        "redirectUrl": null,
        "senderName": "Merchant Checkout",
        "senderAccount": "SafeHaven Microfinance Bank",
        "senderAccountNumber": "7087654321",
        "merchantNotified": false,
        "forwardedForSettlement": true,
        "ipAddress": "127.0.0.1",
        "narration": "Merchant Collection",
        "paymentStatus": "SUCCESSFUL",
        "createdDate": "2025-01-01 11:00:11",
        "lastUpdatedDate": "2025-01-01 11:00:11",
        "merchantCheckoutReference": null,
        "providerResponse": null,
        "businessName": "Test Business",
        "merchantName": "Test Merchant",
        "businessId": "xxx-xxx-xxx-xxx-xxx",
        "fixedAccount": false
      }
    ]
  }
}

Examples

cURL — Basic paginated list

curl -X GET \
  "https://core-sandbox.payonus.com/api/v1/payment-requests?page=0&size=20" \
  -H "Authorization: Bearer <access_token>"

cURL — Filter by business, status and date range

curl -G "https://core-sandbox.payonus.com/api/v1/payment-requests" \
  -H "Authorization: Bearer <access_token>" \
  --data-urlencode "businessId=<business-uuid>" \
  --data-urlencode "status=SUCCESSFUL" \
  --data-urlencode "fromDate=2025-01-01" \
  --data-urlencode "toDate=2025-01-31" \
  --data-urlencode "page=0" \
  --data-urlencode "size=50"

Usage notes and best practices

• Prefer using fromDate/toDate in UTC and ISO-8601 format to avoid timezone issues.
• Use pagination (page/size) to optimize performance and response sizes.