Create a payment request
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
andhaste
. - 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 thetransactionId
as 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 tofalse
.
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.
Updated 8 months ago