1. Payment requests that do not expire on payment (e.g., a link or QR code for donations)
  2. Payment requests that expire on payment (e.g., a digital item or a unique physical product)
  3. Limit orders that expire after a set number of purchases (e.g., a limited edition card drop)

​
API Endpoint

  • Method: POST
  • URL: https://cloud.handcash.io/v3/paymentRequests

​
Headers

Accept: application/json
Content-Type: application/json
App-Id: your-app-id
App-Secret: your-app-secret

​
Request Parameters

interface CreatePaymentRequestParams {
  product: {
    name: string;
    description?: string;
    imageUrl?: string;
  };
  instrumentCurrencyCode: string;
  denominationCurrencyCode?: string;
  receivers: {
    sendAmount: number;
    destination: string;
  }[];
  requestedUserData?: string[];
  redirectUrl?: string;
  notifications?: {
    webhook?: {
      webhookUrl: string;
      customParameters?: Record<string, any>;
    };
    email?: string;
  };
  expirationType: 'limit' | 'never' | 'onPaymentCompleted';
  totalUnits?: number;
  expirationInSeconds?: number;
  enabledAt?: string; // ISO date string
}

​
Parameter Details

  • product: Details of the product or service being paid for.
  • instrumentCurrencyCode: The currency code for the payment (e.g., ‘BSV’).
  • denominationCurrencyCode: Optional. The currency for price denomination if different from instrumentCurrencyCode.
  • receivers: Array of payment recipients, including amount and destination.
  • requestedUserData: Optional. Array of user data fields to request.
  • redirectUrl: Optional. URL to redirect the user after payment.
  • notifications: Optional. Webhook and email notification settings.
  • expirationType: Type of expiration for the payment request.
  • totalUnits: Required if expirationType is ‘limit’. The total number of times the payment can be made.
  • expirationInSeconds: Optional. Time in seconds until the request expires.
  • enabledAt: Optional. ISO date string for when the request becomes active.

​
Example Request

curl --request POST \
     --url https://cloud.handcash.io/v3/paymentRequests \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'App-Id: your-app-id' \
     --header 'App-Secret: your-app-secret' \
     --data '{
          "product": {
               "name": "Legendary Sword",
               "description": "A sword made of lighting",
               "imageUrl": "https://example.com/sword-image.jpg"
          },
          "receivers": [
               {
                    "sendAmount": 0.01,
                    "destination": "myBusinessWalletId"
               }
          ],
         "requestedUserData": ["paymail"],
          "notifications": {
               "webhook": {
                    "customParameters": {
                         "gameId": "199491921"
                    },
                    "webhookUrl": "https://myappdomain.com/handcash/webhook"
               },
               "email": "payments@handcash.io"
          },
          "currencyCode": "BSV",
          "denominatedIn": "USD",
          "expirationType": "limit",
          "totalUnits": 5,
          "expirationInSeconds": 604800,
          "redirectUrl": "https://market.handcash.io/my-account/items/inventory/647a2e8e84940994f6aeb634?collectionId=659ddbeef30153e01217307e&sortBy=price&order=asc&page=1"
     }'

​
Response Type

interface PaymentRequestResponse {
  id: string;
  paymentRequestUrl: string;
  paymentRequestQrCodeUrl: string;
  isEnabled: boolean;
  product: {
    name: string;
    description: string;
    imageUrl: string;
  };
  receivers: {
    sendAmount: number;
    destination: string;
  }[];
  notifications: {
    webhook: {
      webhookUrl: string;
      customParameters?: Record<string, any>;
    };
    email?: string;
  };
  requestedUserData: [string],
  redirectUrl: string;
  expirationType: string;
  totalUnits: number;
  remainingUnits: number;
  expiresAt: string;
  createdAt: string;
}

​
Important Notes

  • The payment request in this example has a single receiver.
  • It will expire in 604800 seconds (one week).
  • The service will receive the user’s paymail in the body of the webhook notification.
  • Custom parameters (e.g., gameId) will be included in the webhook notification.
  • This payment request expires after 5 payments due to "expirationType": "limit" and "totalUnits": 5.
  • HandCash will notify the server for each successful payment via the specified webhook URL.
  • Email notifications will be sent for each successful payment.
  • Users will be redirected to the redirectUrl after completing the payment.
  • The redirect URL will include the transactionId as a query parameter.
  • Developers can use the redirect URL pattern to send users to specific collections of digital items.