Create a payment request

Payment requests are references to payments that you can present to your users in order to complete the payment.

The following code generates a new payment request:

const axios = require("axios").default;

const options = {
  method: 'POST',
  url: 'https://cloud.handcash.io/v2/paymentRequests',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'app-secret': 'your-app-secret',
    'app-id': 'your-app-id'
  },
  data: {
    product: {
      name: 'Jump · Micro',
      description: 'Play a game to Jump in the Micro division.',
      imageUrl: 'https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png'
    },
    receivers: [
      {sendAmount: 0.08, currencyCode: 'USD', destination: 'imaWinner'},
      {sendAmount: 0.02, currencyCode: 'USD', destination: 'haste'}
    ],
    requestedUserData: ['paymail'],
    notifications: {
      webhook: {
        customParameters: {gameId: '199491921'},
        webhookUrl: 'https://app.hastearcade.com/wehbooks/handcash'
      },
      email: '[email protected]'
    },
    expirationType: 'never',
    redirectUrl: 'https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

import requests

url = "https://cloud.handcash.io/v2/paymentRequests"

payload = {
    "product": {
        "name": "Jump · Micro",
        "description": "Play a game to Jump in the Micro division.",
        "imageUrl": "https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png"
    },
    "receivers": [
        {
            "sendAmount": 0.08,
            "currencyCode": "USD",
            "destination": "imaWinner"
        },
        {
            "sendAmount": 0.02,
            "currencyCode": "USD",
            "destination": "haste"
        }
    ],
    "requestedUserData": ["paymail"],
    "notifications": {
        "webhook": {
            "customParameters": {
                "gameId": "9ac9182acae19902"
            },
            "webhookUrl": "https://app.hastearcade.com/wehbooks/handcash"
        },
        "email": "[email protected]"
    },
    "expirationType": "never",
    "redirectUrl": "https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "app-secret": "your-app-secret",
    "app-id": "your-app-id"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://cloud.handcash.io/v2/paymentRequests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["app-secret"] = 'your-app-secret'
request["app-id"] = 'your-app-id'
request.body = "{\"product\":{\"name\":\"Jump · Micro\",\"description\":\"Play a game to Jump in the Micro division.\",\"imageUrl\":\"https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png\"},\"receivers\":[{\"sendAmount\":0.08,\"currencyCode\":\"USD\",\"destination\":\"imaWinner\"},{\"sendAmount\":0.02,\"currencyCode\":\"USD\",\"destination\":\"haste\"}],\"requestedUserData\":[\"paymail\"],\"notifications\":{\"webhook\":{\"customParameters\":{\"gameId\":\"9ac9182acae19902\"},\"webhookUrl\":\"https://app.hastearcade.com/wehbooks/handcash\"},\"email\":\"[email protected]\"},\"expirationType\":\"never\",\"redirectUrl\":\"https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9\"}"

response = http.request(request)
puts response.read_body

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://cloud.handcash.io/v2/paymentRequests', [
  'body' => '{"product":{"name":"Jump · Micro","description":"Play a game to Jump in the Micro division.","imageUrl":"https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png"},"receivers":[{"sendAmount":0.08,"currencyCode":"USD","destination":"imaWinner"},{"sendAmount":0.02,"currencyCode":"USD","destination":"haste"}],"requestedUserData":["paymail"],"notifications":{"webhook":{"customParameters":{"gameId":"9ac9182acae19902"},"webhookUrl":"https://app.hastearcade.com/wehbooks/handcash"},"email":"[email protected]"},"expirationType":"never","redirectUrl":"https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9"}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'app-id' => 'your-app-id',
    'app-secret' => 'your-app-secret',
  ],
]);

echo $response->getBody();

curl --request POST \
     --url https://cloud.handcash.io/v2/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": "Jump · Micro",
          "description": "Play a game to Jump in the Micro division.",
          "imageUrl": "https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png"
     },
     "receivers": [
          {
               "sendAmount": 0.08,
               "currencyCode": "USD",
               "destination": "imaWinner"
          },
          {
               "sendAmount": 0.02,
               "currencyCode": "USD",
               "destination": "haste"
          }
     ],
     "requestedUserData": [
          "paymail"
     ],
     "notifications": {
          "webhook": {
               "customParameters": {
                    "gameId": "9ac9182acae19902"
               },
               "webhookUrl": "https://app.hastearcade.com/wehbooks/handcash"
          },
          "email": "[email protected]"
     },
     "expirationType": "never",
     "redirectUrl": "https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9"
}
'

The Haste app would use the payment request created with the code above to create a paywall to play a game (Jump) in a specific category (micro division).

Here are a few interesting aspects to comment on:

The payment has 2 different receivers: imaWinner and haste.
The service will receive the user's paymail in the body of the webhook notification.
The service will receive the custom parameter gameId in the body of the webhook notification.
This payment request never expires as specified by "expirationType": "never" so the same link can be presented to users multiple times.
HandCash will notify the server every time a payment is successfully completed to the URL specified under notifications.webhookUrl (<https://app.hastearcade.com/wehbooks/handcash>).
HandCash will send an email every time a payment is successfully completed to the[email protected].
The user will be redirected to redirectUrl when the payment has been completed (<https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9>). Also, the redirect URL will include the transactionIdas a query parameter referring to the ID of the payment the user just completed.

The request would return the following:

{
  "id": "9ac9182acae19902",
  "paymentRequestUrl": "https://pay.handcash.io/9ac9182acae19902",
  "paymentRequestQrCodeUrl": "https://pay.handcash.io/api/paymentPreview/qr/9ac9182acae19902",
  "isEnabled": true,
  "product": {
  	"name": "Jump · Micro",
    "description": "Play a game to Jump in the Micro division.",
    "imageUrl": "https://haste-developer-portal-production-game-art.s3.amazonaws.com/Jump/gameicon.png"
  },
  "receivers": [
    {
      "sendAmount": 0.08,
      "currencyCode": "USD",
      "destination": "imaWinner"
    },
    {
      "sendAmount": 0.02,
      "currencyCode": "USD",
      "destination": "haste"
    }
  ],
  "requestedUserData": ["paymail"],
  "notifications": {
    "webhook": {
      "webhookUrl": "https://app.hastearcade.com/wehbooks/handcash",
      "customParameters": {
        "gameId": "9ac9182acae19902"
      },
    },
    "email": "[email protected]",
  },
  "redirectUrl": "https://app.hastearcade.com/games/ec04e9ca-71b6-4fb2-abb0-b6a2da072fb9",
  "expirationType": "never",
  "expiresAt": 1650558683
}

There are different ways for users to engage with the payment request:

paymentRequestUrl: URL to open the payment request in the user's device (browser or native app).
paymentRequestQrCodeUrl: QR users can scan to engage with the payment request.

Ultimately, developers decide the most convenient way to present the link to their users.

The image below represents what the payment request looks like in HandCash for the user.

Payment request preview in the HandCash app.

📘
Payment request expiration
Either because the payment was completed or because the expiration time has been reached, isEnabled will be set to false.

Check out the API Endpoint to learn more about creating payment requests.

Next steps

Check out the payment webhooks section to learn how to trigger any custom process when a payment is completed.