Creating Payments

Learn how to create and manage payments with Coinskro Pay.

Basic Payment
Payment with Customer Info
Payment with Redirect URLs
Payment with Items (E-commerce)
Custom Payment Reference
Add Metadata
Fee Options
Response
Check Payment Status
Payment Statuses
Supported Currencies
Complete Example
Fund a User’s Wallet (Business → Coinskro User)

Basic Payment

Create a simple payment request:

curl -X PUT https://api.coinskro.com/payment/create \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "PI",
    "payment_type": "deposit"
  }'

Required Fields:

Field	Type	Description
`amount`	number	Amount to charge
`currency`	string	Currency code (`PI`, `USDC`, `CSK`, `USDT`)
`payment_type`	string	Use `deposit` for customer payments

Payment with Customer Info

Track which customer made the payment:

{
  "amount": 100.00,
  "currency": "PI",
  "payment_type": "deposit",
  "customer_email": "john@example.com",
  "customer_reference": "CUST_12345"
}

Payment with Redirect URLs

Redirect customers after payment:

{
  "amount": 100.00,
  "currency": "PI",
  "payment_type": "deposit",
  "success_url": "https://yoursite.com/order/success?order_id=123",
  "failure_url": "https://yoursite.com/order/failed?order_id=123"
}

Include your order ID in the URL to identify the order when the customer returns.

Payment with Items (E-commerce)

For e-commerce, include product details:

{
  "amount": 150.00,
  "currency": "PI",
  "payment_type": "deposit",
  "customer_email": "customer@example.com",
  "item_list": {
    "items": [
      {
        "name": "Premium Plan",
        "price": 100.00,
        "quantity": 1
      },
      {
        "name": "Setup Fee",
        "price": 50.00,
        "quantity": 1
      }
    ]
  }
}

Custom Payment Reference

Use your own order ID as the payment reference:

{
  "amount": 100.00,
  "currency": "PI",
  "payment_type": "deposit",
  "payment_reference": "ORDER_2026_00123"
}

Payment references must be unique. If you don’t provide one, we’ll generate it automatically.

Add Metadata

Store custom data with the payment:

{
  "amount": 100.00,
  "currency": "PI",
  "payment_type": "deposit",
  "meta_data": "{\"order_id\": \"123\", \"product_type\": \"subscription\", \"plan\": \"pro\"}"
}

Fee Options

Choose who pays the transaction fee:

{
  "amount": 100.00,
  "currency": "PI",
  "payment_type": "deposit",
  "fee_payer": "customer"
}

Option	Description
`merchant`	You pay the fee (default). Customer pays $100, you receive $99
`customer`	Customer pays the fee. Customer pays $101, you receive $100

Response

{
  "message": "Payment created",
  "data": {
    "PaymentData": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "payment_reference": "PAY_abc123xyz",
      "amount": 100.00,
      "currency": "PI",
      "payment_status": "unlinked",
      "payment_type": "deposit",
      "created_at": "2026-02-06T10:30:00Z"
    },
    "PaymentURL": "https://pay.coinskro.com?reference=PAY_abc123xyz&app=123..."
  }
}

What to do with the response:

Save the payment_reference in your database
Redirect your customer to PaymentURL
Wait for the webhook to confirm payment

Check Payment Status

Verify a payment’s status anytime:

curl https://api.coinskro.com/payment/info/PAY_abc123xyz

Response:

{
  "message": "Payment information",
  "data": {
    "payment_reference": "PAY_abc123xyz",
    "amount": 100.00,
    "currency": "PI",
    "payment_status": "completed",
    "created_at": "2026-02-06T10:30:00Z",
    "updated_at": "2026-02-06T10:35:00Z"
  }
}

Payment Statuses

Status	Meaning	Action
`unlinked`	Payment created, waiting for customer	Customer should complete payment
`linked`	Customer started the payment	Payment in progress
`pending`	Payment being processed	Wait for completion
`completed`	Payment successful ✅	Fulfill the order
`failed`	Payment failed	Ask customer to retry
`cancelled`	Payment cancelled	No action needed
`in-appeal`	Payment disputed	Check appeals dashboard

Supported Currencies

Code	Currency	Min Amount
`PI`	PI Coin	$1.00
`USDC`	USD Coin	$1.00
`USDT`	Tether	$5.00
`CSK`	Coinskro Token	$5.00

Complete Example

Here’s a full example creating a payment for an e-commerce order:

{
  "amount": 299.99,
  "currency": "PI",
  "payment_type": "deposit",
  "payment_reference": "ORD_20260206_001",
  "customer_email": "buyer@example.com",
  "customer_reference": "USER_789",
  "success_url": "https://mystore.com/checkout/success?order=ORD_20260206_001",
  "failure_url": "https://mystore.com/checkout/failed?order=ORD_20260206_001",
  "payment_note": "Order #ORD_20260206_001",
  "fee_payer": "merchant",
  "item_list": {
    "items": [
      {
        "name": "Wireless Headphones",
        "price": 249.99,
        "quantity": 1
      },
      {
        "name": "Shipping",
        "price": 50.00,
        "quantity": 1
      }
    ]
  },
  "meta_data": "{\"shipping_address\": \"123 Main St\", \"coupon\": \"SAVE10\"}"
}

Fund a User’s Wallet (Business → Coinskro User)

Credit a Coinskro user’s wallet directly from your business (integration) balance. This is useful for payouts, rewards, cashback, or any scenario where your business needs to push funds to a specific user.

Your integration balance must have sufficient funds for the selected currency. The debit happens instantly and atomically.

curl -X POST https://api.coinskro.com/payment/fund-user \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "amount": 25.00,
    "currency": "usdt-bep20"
  }'

Request Fields:

Field	Type	Required	Description
`username`	string	✅	The Coinskro username of the recipient
`amount`	number	✅	Positive amount to send
`currency`	string	✅	Currency code (e.g. `pi`, `usdt-bep20`)

Success Response 200:

{
  "message": "User wallet funded successfully",
  "data": null
}

Error Responses:

Status	Message	Cause
`400`	`username is required` / `amount must be a positive number`	Missing or invalid fields
`401`	`Missing or invalid Authorization header`	Bad / missing Bearer token
`403`	`Insufficient business balance`	Integration wallet has insufficient funds
`404`	`User not found`	No Coinskro account for the given username
`502`	`Failed to reach Coinskro backend`	Upstream connectivity error

This endpoint debits your integration wallet balance, not a per-payment escrow. Ensure your balance is topped up before calling it.