Skip to main content
GET
/
collections
/
{collectionId}
Get Collection
curl --request GET \
  --url https://api.fyatu.com/api/v3/collections/{collectionId} \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "collectionId": "<string>",
    "batch": "<string>",
    "reference": "<string>",
    "orderId": "<string>",
    "amount": 123,
    "fee": 123,
    "netAmount": 123,
    "currency": "<string>",
    "status": "<string>",
    "description": "<string>",
    "payer": {
      "clientId": "<string>",
      "name": "<string>"
    },
    "refunds": {
      "totalRefunded": 123,
      "remainingRefundable": 123,
      "count": 123
    },
    "metadata": {},
    "callbackUrl": "<string>",
    "webhookUrl": "<string>",
    "completedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Retrieve details of a specific collection by its ID. Use this to verify payment status.

​
Path Parameters

ParameterTypeDescription
collectionIdstringThe collection ID (batch ID)

​
Response

FieldTypeDescription
collectionIdstringUnique collection identifier
referencestringHuman-readable reference
orderIdstringYour order ID (if provided)
amountnumberPayment amount
feenumberProcessing fee
netAmountnumberAmount received (amount - fee)
currencystringCurrency code
descriptionstringPayment description
statusstringPayment status
statusReasonstringReason for status (if failed/refunded)
payerobjectPayer information
metadataobjectYour custom metadata
completedAtstringCompletion timestamp
expiresAtstringSession expiry time
createdAtstringCreation timestamp

​
Payer Object

FieldTypeDescription
emailstringPayer’s email
namestringPayer’s name
accountNamestringFyatu account name
clientIdstringPayer’s Fyatu client ID

​
Status Values

StatusDescription
PENDINGAwaiting payment
COMPLETEDPayment successful
FAILEDPayment failed or expired
REFUNDEDFully refunded
PARTIALLY_REFUNDEDPartially refunded

​
Example Usage

<?php
$collectionId = 'SCI679A1B2C3D4E5';

$response = file_get_contents(
    "https://api.fyatu.com/api/v3/collections/{$collectionId}",
    false,
    stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => 'Authorization: Bearer ' . $accessToken
        ]
    ])
);

$result = json_decode($response, true);

if ($result['success'] && $result['data']['status'] === 'COMPLETED') {
    // Payment confirmed
    $netAmount = $result['data']['netAmount'];
    $payerName = $result['data']['payer']['name'];

    // Fulfill the order
    fulfillOrder($result['data']['orderId']);
}

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "Collection retrieved successfully",
  "data": {
    "collectionId": "SCI679A1B2C3D4E5",
    "reference": "A2B4C6D8E0F2",
    "orderId": "INV-001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "description": "Premium Subscription",
    "status": "COMPLETED",
    "statusReason": null,
    "payer": {
      "email": "[email protected]",
      "name": "John Doe",
      "accountName": "John D.",
      "clientId": "F12345678"
    },
    "metadata": {
      "userId": "12345",
      "plan": "premium"
    },
    "completedAt": "2026-01-08T11:35:00+00:00",
    "expiresAt": "2026-01-08T12:30:00+00:00",
    "createdAt": "2026-01-08T11:30:00+00:00"
  },
  "meta": {
    "requestId": "req_xyz789ghi012",
    "timestamp": "2026-01-08T11:40:00+00:00"
  }
}

​
Verifying Payments

Always verify payment status server-side before fulfilling orders. Never trust client-side redirects alone.
  1. Webhook: Receive payment notification at your webhookUrl
  2. API Verification: Call this endpoint to confirm the payment
  3. Check Status: Ensure status is COMPLETED
  4. Check Amount: Verify amount matches expected value
  5. Fulfill Order: Only then process the order
<?php
// Webhook handler example
function handleWebhook($payload) {
    $collectionId = $payload['collectionId'];

    // Always verify with API
    $collection = getCollection($collectionId);

    if ($collection['status'] !== 'COMPLETED') {
        return; // Not completed yet
    }

    // Check if already processed
    if (orderAlreadyFulfilled($collection['orderId'])) {
        return; // Duplicate webhook
    }

    // Fulfill the order
    fulfillOrder($collection['orderId'], $collection['netAmount']);
}

​
Error Responses

Error CodeHTTPDescription
RESOURCE_NOT_FOUND404Collection not found or not owned by you
AUTH_TOKEN_INVALID401Invalid or expired token

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
collectionId
string
required

Collection ID, batch ID, or order ID

Response

Collection retrieved successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object
​
meta
object