Payment Flow Guide

Step-by-step guide to processing payments using the Aurion REST API

OverviewStep 1: InitializeStep 2: Assign TokenStep 3: Process Payment

Overview

This guide walks you through the complete payment processing flow using Aurion's REST API. The process consists of three main steps:

1. Initialize Payment
→
2. Assign Token
→
3. Verify & Process

Prerequisites

💡 Tip: All API requests require authentication using a Bearer token in the Authorization header. Use your secret key (sk_...) for authentication.

Step 1 Initialize Payment

Create a new payment transaction with specified recipients and USD amount.

Endpoint

POST /v1/payments/initialize

Headers

Content-Type: application/json
Authorization: Bearer sk_your-secret-key

Request Body

FieldTypeRequiredDescription
amountUSDnumberRequiredPayment amount in USD (must be positive)
recipientsarrayRequiredArray of recipient objects with userId and percentage
recipients[].userIdstringRequiredUser ID from Create User response
recipients[].percentagenumberRequiredPercentage allocation (total must equal 100)
metadataobjectOptionalCustom metadata for the transaction
callbackUrlstringOptionalWebhook URL for payment notifications

Example Request

curl -X POST https://api.aurion.finance/v1/payments/initialize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your-secret-key" \
  -d '{
    "amountUSD": 100,
    "recipients": [
      {
        "userId": "user-uuid-1",
        "percentage": 60
      },
      {
        "userId": "user-uuid-2",
        "percentage": 40
      }
    ],
    "metadata": {
      "orderId": "order-123",
      "description": "Payment for services"
    },
    "callbackUrl": "https://yourapp.com/webhooks/payment"
  }'

Success Response (201 Created)

{
  "success": true,
  "message": "Payment initialized successfully",
  "data": {
    "transactionId": "5b0cb826-0bcc-483f-984f-268a0e0a757c",
    "paymentLink": "https://pay.aurion.finance/5b0cb826-0bcc-483f-984f-268a0e0a757c",
    "expiresAt": null,
    "status": "PENDING"
  }
}
Important: Save the transactionId from the response. You'll need it for the next steps.
Validation Rules:
  • Total recipient percentages must equal exactly 100%
  • Amount must be a positive number
  • All user IDs must exist in your platform

Step 2 Assign Token

Select the cryptocurrency token for payment and get payment details including wallet address.

Endpoint

POST /v1/payments/update-token

Headers

Content-Type: application/json
Authorization: Bearer sk_your-secret-key

Request Body

FieldTypeRequiredDescription
transactionIdstringRequiredTransaction ID from Step 1 (Initialize Payment)
tokenIdstringRequiredToken ID (get from /v1/tokens endpoint)
💡 Getting Token IDs: Call GET /v1/tokens to get a list of available tokens and their IDs. Common tokens include:
  • So11111111111111111111111111111111111111112 - SOL (Solana)
  • EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v - USDC
  • Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB - USDT

Example Request

curl -X POST https://api.aurion.finance/v1/payments/update-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your-secret-key" \
  -d '{
    "transactionId": "5b0cb826-0bcc-483f-984f-268a0e0a757c",
    "tokenId": "So11111111111111111111111111111111111111112"
  }'

Success Response (200 OK)

{
  "success": true,
  "data": {
    "transaction": {
      "id": "5b0cb826-0bcc-483f-984f-268a0e0a757c",
      "tokenId": "So11111111111111111111111111111111111111112",
      "expectedAmount": 0.5,
      "status": "PENDING",
      "expiresAt": "2024-01-15T11:30:00.000Z"
    },
    "paymentDetails": {
      "recipientAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "expectedAmount": 0.5,
      "token": {
        "symbol": "SOL",
        "decimals": 9
      }
    }
  }
}
✅ What happens here:
  • A unique wallet address is assigned for this transaction
  • The USD amount is converted to the selected token based on current exchange rates
  • Transaction expiration is set to 30 minutes from now
  • You receive the recipientAddress where the customer should send payment
⚠️ Important Notes:
  • Transaction must be in PENDING state
  • Transaction expires in 30 minutes from token selection
  • Use the recipientAddress to provide payment instructions to your customer
  • The expectedAmount is calculated based on current exchange rates

Step 3 Verify & Process Payment

Verify that payment has been received on-chain and trigger the distribution process.

Endpoint

POST /v1/payments/verify

Headers

Content-Type: application/json
Authorization: Bearer sk_your-secret-key

Request Body

FieldTypeRequiredDescription
transactionIdstringRequiredTransaction ID from Step 1

Example Request

curl -X POST https://api.aurion.finance/v1/payments/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your-secret-key" \
  -d '{
    "transactionId": "5b0cb826-0bcc-483f-984f-268a0e0a757c"
  }'

Success Response (200 OK)

{
  "success": true,
  "message": "Transaction verified successfully",
  "data": {
    "transactionId": "5b0cb826-0bcc-483f-984f-268a0e0a757c",
    "transactionHash": "5KKsW8Y9n8rTBrDHvdxJ6YQZfJ2rxxvChaZZoGKk8RKFc3xs4TSK1kSv7NgZy6jm478",
    "status": "PLATFORM_RECEIVED",
    "amountReceived": 0.5,
    "expectedAmount": 0.5,
    "tokenSymbol": "SOL",
    "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  }
}
✅ What happens here:
  • The system verifies the latest transaction to the assigned wallet
  • Validates that the received amount matches the expected amount (with 0.1% tolerance)
  • Transaction status changes to PLATFORM_RECEIVED
  • Distribution process automatically starts to send funds to recipients
💡 Polling Strategy: If you receive a pending response, wait a few seconds and retry. Blockchain transactions can take a moment to propagate. You can poll this endpoint every 5-10 seconds until you receive a success response.

Next Steps