Create Payment via API

Learn how to create cryptocurrency payments using the HexPay REST API with flexible pricing options

Before creating payments via API, ensure you have:

API Endpoint

POST https://api.hexpay.io/v1/payments/create

Payment Creation Scenarios

Choose the scenario that best fits your use case:

1. Fiat Amount with Automatic Crypto Selection (Recommended)

Best for: Most e-commerce stores with stable pricing in traditional currencies.

The simplest approach - specify an amount in fiat currency (USD, EUR, etc.) and let HexPay handle crypto conversion and customer payment method selection.

curl -X POST "https://api.hexpay.io/v1/payments/create" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..." \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "FIAT",
    "fiatAmount": "100.50",
    "fiatCurrency": "USD"
  }'

const body = JSON.stringify({
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD"
})

fetch("https://api.hexpay.io/v1/payments/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
  },
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.hexpay.io/v1/payments/create"
  body := strings.NewReader(`{
    "invoiceType": "FIAT",
    "fiatAmount": "100.50",
    "fiatCurrency": "USD"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "https://api.hexpay.io/v1/payments/create"
body = {
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD"
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://api.hexpay.io/v1/payments/create"))
  .header("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD"
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...");
var response = await client.PostAsync("https://api.hexpay.io/v1/payments/create", body);
var responseBody = await response.Content.ReadAsStringAsync();

How it works:

You specify invoiceType: "FIAT" with fiat amount and currency (e.g., 100.50 USD)
Customer sees the fiat price and chooses their preferred cryptocurrency from your available payment methods
HexPay calculates the crypto amount based on real-time exchange rates
Customer completes payment in their chosen cryptocurrency

2. Fiat Amount with Pre-selected Crypto Method

Best for: When you want to offer specific cryptocurrency options or create a streamlined checkout experience.

Specify both the fiat amount and the exact cryptocurrency/network combination you want to use.

curl -X POST "https://api.hexpay.io/v1/payments/create" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..." \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "FIAT",
    "fiatAmount": "100.50",
    "fiatCurrency": "USD",
    "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
  }'

const body = JSON.stringify({
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
})

fetch("https://api.hexpay.io/v1/payments/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
  },
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.hexpay.io/v1/payments/create"
  body := strings.NewReader(`{
    "invoiceType": "FIAT",
    "fiatAmount": "100.50",
    "fiatCurrency": "USD",
    "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "https://api.hexpay.io/v1/payments/create"
body = {
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://api.hexpay.io/v1/payments/create"))
  .header("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "invoiceType": "FIAT",
  "fiatAmount": "100.50",
  "fiatCurrency": "USD",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2"
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...");
var response = await client.PostAsync("https://api.hexpay.io/v1/payments/create", body);
var responseBody = await response.Content.ReadAsStringAsync();

How it works:

You specify invoiceType: "FIAT" with both fiat amount/currency and a specific paymentMethodID
HexPay calculates the exact crypto amount needed based on current exchange rates
Customer sees both the fiat price (100.50 USD) and the calculated crypto amount (e.g., 0.00235 BTC)
Customer pays the calculated crypto amount using the pre-selected cryptocurrency/network
Payment is locked to that specific crypto method - no customer choice involved

3. Fixed Crypto Amount

Best for: Crypto-native businesses, DeFi applications, or when you want to charge exact crypto amounts.

Specify the exact cryptocurrency amount the customer should pay. The fiat equivalent will fluctuate with market rates.

curl -X POST "https://api.hexpay.io/v1/payments/create" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..." \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "CRYPTO",
    "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
    "cryptoAmount": "0.00235"
  }'

const body = JSON.stringify({
  "invoiceType": "CRYPTO",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
  "cryptoAmount": "0.00235"
})

fetch("https://api.hexpay.io/v1/payments/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
  },
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.hexpay.io/v1/payments/create"
  body := strings.NewReader(`{
    "invoiceType": "CRYPTO",
    "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
    "cryptoAmount": "0.00235"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "https://api.hexpay.io/v1/payments/create"
body = {
  "invoiceType": "CRYPTO",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
  "cryptoAmount": "0.00235"
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..."
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "invoiceType": "CRYPTO",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
  "cryptoAmount": "0.00235"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://api.hexpay.io/v1/payments/create"))
  .header("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "invoiceType": "CRYPTO",
  "paymentMethodID": "0197ef69-98b6-72d4-81a6-6b884fb674c2",
  "cryptoAmount": "0.00235"
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...");
var response = await client.PostAsync("https://api.hexpay.io/v1/payments/create", body);
var responseBody = await response.Content.ReadAsStringAsync();

How it works:

You specify invoiceType: "CRYPTO" with exact cryptoAmount and paymentMethodID
Customer sees the fixed crypto amount (0.00235 BTC) as the primary price
Fiat equivalent is displayed but fluctuates with market rates for reference only
Customer pays the exact crypto amount specified - no conversion calculations needed

Getting Payment Method UUIDs

To use scenarios 2 and 3, you'll need the UUIDs of your payment methods. Retrieve them by calling the GET /v1/payments/methods endpoint:

📋 Get Store Payment Methods API

Full API reference for retrieving all enabled payment methods for your store

Parameter	Type	Required	Description
`invoiceType`	String	Yes	Invoice type. Values: `CRYPTO`, `FIAT`
`fiatAmount`	String	Conditional	Fiat amount as string (e.g., "100.50")
`fiatCurrency`	String	Conditional	Fiat currency symbol. Values: `USD`, `EUR`, `RUB`
`cryptoAmount`	String	Conditional	Crypto amount as string (e.g., "0.00235")
`paymentMethodID`	String	Conditional	Payment method UUID

For FIAT invoice type, provide fiatAmount and fiatCurrency. For CRYPTO invoice type, provide cryptoAmount, paymentMethodID, and optionally fiatCurrency to display the equivalent amount in your store's preferred currency. Don't mix fiatAmount with cryptoAmount parameters.

Response Handling

{
  "paymentID": "0199ea7a-0e5f-7545-9885-a0c22e99060f"
}

The API returns a JSON response with a payment ID that you can use to:

Track payment status
Generate payment links
Query payment details

To complete the payment process, provide the customer with the payment link: d

https://payment.hexpay.io/0199ea7a-0e5f-7545-9885-a0c22e99060f

Simply append the payment ID to the base payment URL https://payment.hexpay.io/ to create the customer's payment link.

Create Payment via API

API Endpoint

Payment Creation Scenarios

1. Fiat Amount with Automatic Crypto Selection (Recommended)

2. Fiat Amount with Pre-selected Crypto Method

3. Fixed Crypto Amount

Getting Payment Method UUIDs

📋 Get Store Payment Methods API

Request Parameters

Response Handling

Next Steps

📊 Monitor Payment Status

❌ Handle Payment Cancellation

On this page