Skip to main content
POST
/
collections
Create Collection
curl --request POST \
  --url https://api.fyatu.com/api/v3/collections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25,
  "currency": "USD",
  "orderId": "INV-001",
  "description": "Premium Subscription",
  "callbackUrl": "https://yoursite.com/payment/complete",
  "webhookUrl": "https://yoursite.com/webhook/fyatu",
  "metadata": {
    "userId": "12345",
    "plan": "premium"
  }
}
'
{
  "success": true,
  "status": 201,
  "message": "Checkout session created successfully",
  "data": {
    "collectionId": "SCI679A1B2C3D4E5",
    "reference": "A2B4C6D8E0F2",
    "orderId": "INV-001",
    "amount": 25,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "status": "PENDING",
    "checkoutUrl": "https://checkout.fyatu.com/sci/checkout?batch=SCI679A1B2C3D4E5",
    "expiresAt": "2026-01-08T12:30:00+00:00"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-08T11:30:00+00:00"
  }
}

​
Overview

Create a checkout session to collect payment from a customer. Returns a checkout URL where the customer completes payment.

​
Request Body

FieldTypeRequiredDescription
amountnumberYesPayment amount in USD
currencystringNoCurrency code (default: USD). Only USD supported, other values are ignored
orderIdstringYesYour unique order/invoice ID (max 100 chars)
descriptionstringYesPayment description (max 100 chars)
callbackUrlstringNoReturn URL after payment (overrides dashboard setting)
webhookUrlstringNoIPN URL for server-to-server notifications (overrides dashboard setting)
metadataobjectNoCustom data to attach to the payment
callbackUrl and webhookUrl are optional overrides. If not provided, the URLs configured in your app dashboard will be used.

​
Response

FieldTypeDescription
collectionIdstringUnique collection identifier
referencestringHuman-readable reference (shown to payer)
orderIdstringYour order ID (if provided)
amountnumberPayment amount
feenumberProcessing fee (deducted from amount)
netAmountnumberAmount you receive (amount - fee)
currencystringCurrency code
statusstringPENDING
checkoutUrlstringURL to redirect customer for payment
expiresAtstringSession expiry time (60 minutes)

​
Integration Examples

<?php
// Create checkout session via API

$appId = 'DD123FR45446CECES';
$secretKey = 'YOUR_SECRET_KEY';

// Step 1: Get access token
$tokenResponse = file_get_contents('https://api.fyatu.com/api/v3/auth/token', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => json_encode([
            'appId' => $appId,
            'secretKey' => $secretKey,
            'grantType' => 'client_credentials'
        ])
    ]
]));

$token = json_decode($tokenResponse, true)['data']['accessToken'];

// Step 2: Create checkout session
$response = file_get_contents('https://api.fyatu.com/api/v3/collections', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $token
        ],
        'content' => json_encode([
            'amount' => 25.00,
            'orderId' => 'INV-' . time(),
            'description' => 'Premium Subscription',
            'callbackUrl' => 'https://yoursite.com/payment/complete',  // Optional override
            'webhookUrl' => 'https://yoursite.com/webhook/fyatu',      // Optional override
            'metadata' => [
                'userId' => '12345',
                'plan' => 'premium'
            ]
        ])
    ]
]));

$result = json_decode($response, true);

if ($result['success']) {
    // Redirect customer to checkout
    header('Location: ' . $result['data']['checkoutUrl']);
    exit;
} else {
    echo 'Error: ' . $result['message'];
}

​
Example Response

{
  "success": true,
  "status": 201,
  "message": "Checkout session created successfully",
  "data": {
    "collectionId": "SCI679A1B2C3D4E5",
    "reference": "A2B4C6D8E0F2",
    "orderId": "INV-001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "status": "PENDING",
    "checkoutUrl": "https://checkout.fyatu.com/sci/checkout?batch=SCI679A1B2C3D4E5",
    "expiresAt": "2026-01-08T12:30:00+00:00"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2026-01-08T11:30:00+00:00"
  }
}

​
Checkout Flow

  1. Create Session: Call this endpoint to create a checkout session
  2. Redirect Customer: Send customer to the checkoutUrl
  3. Customer Pays: Customer logs in and completes payment on Fyatu
  4. Webhook Notification: Receive IPN at your webhookUrl (server-to-server)
  5. Customer Returns: Customer is redirected to callbackUrl with status

​
Callback URL

After payment (success or failure), the customer is redirected to your callbackUrl with query parameters: 
https://yoursite.com/payment/complete?batch=SCI679A1B2C3D4E5&status=COMPLETED
ParameterDescription
batchThe collection ID
statusPayment status (COMPLETED, FAILED, CANCELLED)
Never trust callback parameters alone. Always verify payment status server-side using the webhook or by calling the Get Collection endpoint.

​
Webhook (IPN)

Your webhookUrl receives a POST request with the payment details: 
{
  "event": "collection.completed",
  "collectionId": "SCI679A1B2C3D4E5",
  "orderId": "INV-001",
  "reference": "A2B4C6D8E0F2",
  "status": "COMPLETED",
  "amount": 25.00,
  "fee": 0.75,
  "netAmount": 24.25,
  "currency": "USD",
  "payer": {
    "clientId": "F12345678",
    "name": "John Doe"
  },
  "metadata": {
    "userId": "12345",
    "plan": "premium"
  },
  "completedAt": "2026-01-08T11:35:00+00:00"
}

​
Session Expiration

  • Checkout sessions expire after 60 minutes
  • Expired sessions are automatically updated to status EXPIRED
  • Create a new session if the customer returns after expiration

​
Duplicate Prevention

  • The orderId must be unique per app
  • Attempting to create a collection with a duplicate orderId returns 409 Conflict
  • Use orderId to link payments to your order/invoice system
Store the collectionId to later verify the payment status or issue refunds.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Body

application/json
​
amount
number
required

Payment amount in USD

Required range: x >= 1
​
orderId
string
required

Your unique order/invoice ID (required)

Maximum string length: 100
​
description
string
required

Payment description (max 100 chars)

Maximum string length: 100
​
currency
string
default:USD

Currency code (only USD supported, other values ignored)

​
callbackUrl
string<uri>

Return URL after payment (overrides dashboard setting)

​
webhookUrl
string<uri>

IPN URL for server-to-server notifications (overrides dashboard setting)

​
metadata
object

Custom data to attach

Response

Checkout session created successfully

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
​
data
object
​
meta
object