Documentation

Merchant API

This documentation is intended exclusively for integrating with the Pay2Crypto Payment Gateway API.

If you have any questions that are beyond the scope of this help file, Please feel free to message via Telegram 

Quick Start

Welcome to Pay2Crypto Payment Gateway API! 🙌

Introducing the Merchant API - the game-changing tool that supercharges your platform! With it, you can seamlessly offer your customers the ability to pay with crypto, all through a simple, programmatic integration. It's time to level up your payment options! 🚀💥

Prerequisite

Getting started with the Merchant API is quick and easy!

First, you'll need to grab your access token from the Pay2Crypto platform, which you can generate once you connect your wallet. Don't worry - connecting your wallet is only for profile creation and not for making transactions. It's that simple!

Get an Access Token

Once your wallet is connected, you'll be all set to generate your access token directly within the platform. This token will unlock the full potential of our API, giving you seamless access to integrate and interact with our services. It's all designed to be smooth and hassle-free!

IMPORTANT: Please do not share your Access Token with anyone.

Integration

All Merchant API's are built using REST conventions and designed to have a predictable URL structure. They use many standard HTTP features, including methods (POST, GET, PUT, DELETE) and error response codes. All Merchant API calls are made under https://api.pay2crypto.com/v1/ and all responses return standard JSON.

Generate a New Customer Invoice

POST https://api.pay2crypto.com/v1/invoices/create

Headers:

X-Api-Key: _YOUR_ACCESS_TOKEN_
Content-Type: application/json

Request Payload:

{
    "unique_id": "UNI001",
    "order_id": "ORD001",
    "customer_id": "CUS001",
    "custom_data": [
        {
            "product": "Package 1",     
            "name": "Demo User",
            "email": "demo@domain.com",
            "phone": "+971 50 123 4567"
        }
    ],
    "payment_ref": "REF001",
    "payment_type": 1,
    "payment_network": 2,
    "payment_amount": 5
}

Successful Response Payload:

{
    "success": true,
    "message": "Invoice created successfully",
    "unique_id": "UNI001",
    "txid": "99a8fe40234348d49e56843c774dcae9",
    "payment_type": 1,
    "payment_amount": 5,
    "payment_currency": "TRC20",
    "payment_network": "Tron",
    "payment_network_id": 2,
    "payment_url": "https://checkout.pay2crypto.com/?txid=99a8fe40234348d49e56843c774dcae9",
    "expired": false
}

Parameters

Request payload parameters explanation:

  1. unique_id (required):

    A unique identifier for this specific data submission or transaction, typically generated by the merchant. It ensures the record can be uniquely referenced or de-duplicated. Please note that the unique_id can only be used once per invoice.

  2. order_id:

    The merchant's internal identifier for the order. This ties the transaction back to a specific purchase or checkout session in the merchant's system.

  3. customer_id (required):

    A unique identifier for the customer in the merchant's records. Helps associate this order with the correct customer profile or history.

  4. custom_data[]:

    A flexible field that allows the merchant to include additional metadata or structured information. This could represent custom tags, internal notes, campaign references, or any merchant-defined data. It is passed as an array containing a single object, and the object can include any fields the merchant needs.

    Example: 

    "custom_data": [
    {
        "campaign": "SpringSale2025",
        "referrer": "email_newsletter"
    }
]

  5. payment_ref (required):

    A reference string related to the payment, such as a transaction ID or confirmation code. Used for reconciling payments, tracking, or customer support follow-up.

  6. payment_type (required):

    At this time, only cryptocurrency payments are supported. Therefore, the default value should be set to 1.

  7. payment_network (required):

    Currently, we only accept payments made on the Tron blockchain. Please set the default value to 1.

  8. payment_amount (required): The payment amount the merchant is requesting from the customer.

Response parameters explanation:

  1. success:

    This property contains the status of the invoice creation.

  2. message:

    A status message indicating that the system has successfully generated a new invoice.

  3. unique_id:

    The unique identifier provided by the merchant when generating the invoice.

  4. txid:

    Transaction ID: a unique identifier assigned to this particular invoice or payment transaction. It's typically used for tracking and referencing the payment in the platform.

  5. payment_type:

    The type of cryptocurrency expected for payment.

  6. payment_amount:

    The payment amount the merchant is requesting from the customer.

  7. payment_currency:

    The payment currency the merchant is requesting from the customer.

  8. payment_network:

    The blockchain network name on which the payment will be processed.

  9. payment_network_id:

    Internal platform blockchain network ID

  10. payment_url:

    A URL where the user can go to complete the payment process. It includes the transaction ID as a query parameter to load the correct payment.

  11. expired:

    A boolean value indicating whether the invoice is still valid (false means it hasn't expired yet and is still payable).

NOTE: It's recommended to log the responses in your system for future tracking and troubleshooting.

API Errors

Some of the errors you may encounter and reasoning.

Error Message:

  "Invoice with reference 'UNI001' found in the system."

Explanation:

This error message occurs when the unique_id has already been used for a previous invoice and is being reused. Please note that the unique_id can only be used once per invoice.

Fix:

Use a new unique_id value 😊

Example Response:

{
    "success": false,
    "message": "Invoice with reference 'UNI001' found in the system.",
    "unique_id": "UNI001",
    "txid": "99a8fe40234348d49e56843c774dcae9",
    "payment_type": 1,
    "payment_amount": 5,
    "payment_currency": "TRC20",
    "payment_network": "Tron",
    "payment_network_id": 2,
    "payment_url": "https://checkout.pay2crypto.com/?txid=99a8fe40234348d49e56843c774dcae9",
    "expired": false
}

Error Message:

  "Unable to assign a wallet address to your customer..."

Explanation:

This error message occurs when the platform has no available blockchain wallets to assign to customers at the moment.

Fix:

You'll need to reach out to Pay2Crypto support to resolve this issue.

Example Response:


{
    "error": "Unfortunately, we were unable to assign a wallet address to your customer. Please reach out to platform support for assistance."
}

Error Message:

  "No wallet address configured for..."

Explanation:

This error message occurs when the merchant has not specified a blockchain wallet address to receive funds.

Fix:

You'll need to connect in to Pay2Crypto, navigate to the Wallets section of the platform, and add the specified network's crypto wallet to your profile.

Example Response:

{
    "error": "No wallet address configured for Tron. Please configure a wallet address to receive payments in this currency."
}

Error Message:

  "The x-api-key header is required for authorization..."

Explanation:

This error occurs when the API is called without including the x-api-key in the request headers.

Fix:

Just add the x-api-key to the headers and set your access token as its value.

Example Response:

{
    "error": "Unauthorized",
    "message": "The x-api-key header is required for authorization. Please include it in your request headers."
}

Code Examples

Choose your coding language below to view example code.

cURL

Using cURL to make the request:

curl --location 'https://api.pay2crypto.com/v1/invoices/create' \
--header 'X-Api-Key: _YOUR_ACCESS_TOKEN_' \
--header 'Content-Type: application/json' \
--data-raw '{
    "unique_id": "UNI001",
    "order_id": "ORD001",
    "customer_id": "CUS001",
    "custom_data": [
        {
            "product": "Package 1",
            "name": "Demo User",
            "email": "demo@domain.com",
            "phone": "+971 50 123 4567"
        }
    ],
    "payment_ref": "REF001",
    "payment_type": 1,
    "payment_network": 2,
    "payment_amount": 5
}'

PHP

Using PHP and cURL to make the request:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.pay2crypto.com/v1/invoices/create',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "unique_id": "UNI001",
    "order_id": "ORD001",
    "customer_id": "CUS001",
    "custom_data": [
        {
            "product": "Package 1",
            "name": "Demo User",
            "email": "demo@domain.com",
            "phone": "+971 50 123 4567"
        }
    ],
    "payment_ref": "REF001",
    "payment_type": 1,
    "payment_network": 2,
    "payment_amount": 5
}',
  CURLOPT_HTTPHEADER => array(
    'X-Api-Key: _YOUR_ACCESS_TOKEN_',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);

print_r($response);

    ?>

NodeJs - Request

Using NodeJs and Request to make the request:

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.pay2crypto.com/v1/invoices/create',
  'headers': {
    'X-Api-Key': '_YOUR_ACCESS_TOKEN_',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "unique_id": "UNI001",
    "order_id": "ORD001",
    "customer_id": "CUS001",
    "custom_data": [
      {
        "product": "Package 1",
        "name": "Demo User",
        "email": "demo@domain.com",
        "phone": "+971 50 123 4567"
      }
    ],
    "payment_ref": "REF001",
    "payment_type": 1,
    "payment_network": 2,
    "payment_amount": 5
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

JavaScript - Fetch

Using JavaScript to make the request:

const myHeaders = new Headers();
myHeaders.append("X-Api-Key", "_YOUR_ACCESS_TOKEN_");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
  "unique_id": "UNI001",
  "order_id": "ORD001",
  "customer_id": "CUS001",
  "custom_data": [
    {
      "product": "Package 1",
      "name": "Demo User",
      "email": "demo@domain.com",
      "phone": "+971 50 123 4567"
    }
  ],
  "payment_ref": "REF001",
  "payment_type": 1,
  "payment_network": 2,
  "payment_amount": 5
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.pay2crypto.com/v1/invoices/create", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Python - Requests

Using Python to make the request:

import requests
import json

url = "https://api.pay2crypto.com/v1/invoices/create"

payload = json.dumps({
  "unique_id": "UNI001",
  "order_id": "ORD001",
  "customer_id": "CUS001",
  "custom_data": [
    {
      "product": "Package 1",
      "name": "Demo User",
      "email": "demo@domain.com",
      "phone": "+971 50 123 4567"
    }
  ],
  "payment_ref": "REF001",
  "payment_type": 1,
  "payment_network": 2,
  "payment_amount": 5
})
headers = {
  'X-Api-Key': '_YOUR_ACCESS_TOKEN_',
  'Content-Type': 'application/json',
  'Cookie': 'PHPSESSID=7hnfknbqvl1gue9uj0h7qod72l'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

C#

Using C# and HttpClient to make the request:

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.pay2crypto.com/v1/invoices/create");
request.Headers.Add("X-Api-Key", "_YOUR_ACCESS_TOKEN_");
request.Headers.Add("Cookie", "PHPSESSID=7hnfknbqvl1gue9uj0h7qod72l");

var content = new StringContent("{\n    \"unique_id\": \"UNI001\",\n    \"order_id\": \"ORD001\",\n    \"customer_id\": \"CUS001\",\n    \"custom_data\": [\n        {\n            \"product\": \"Package 1\",\n            \"name\": \"Demo User\",\n            \"email\": \"demo@domain.com\",\n            \"phone\": \"+971 50 123 4567\"\n        }\n    ],\n    \"payment_ref\": \"REF001\",\n    \"payment_type\": 1,\n    \"payment_network\": 2,\n    \"payment_amount\": 5\n}", null, "application/json");
request.Content = content;

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

Console.WriteLine(await response.Content.ReadAsStringAsync());

FAQ

A FAQ is a list of frequently asked questions (FAQs) and answers on a particular topic.

We currently only support TRON (USDT TRC20), but we're actively developing support for a variety of popular cryptocurrencies, including Bitcoin (BTC), Ethereum (ETH), Binance Coin (BNB), and Solana (SOL).

Once your customer's payment is processed, you will receive callbacks to the webhooks you specified in the Pay2Crypto dashboard for different statuses (e.g., completed or cancelled), as well as updates within your Pay2Crypto dashboard.

You have the ability to manually complete transactions within your Pay2Crypto dashboard by specifying the transaction hash and the amount. Please note, this process is between you and your customer.

IMPORTANT: Pay2Crypto will not be liable for any errors, as it is your responsibility as the merchant to verify payments before finalizing them.

Yes, all transactions are secured using blockchain technology, ensuring that your payment is processed safely and transparently.

Support

If this documentation doesn't answer your questions, Please send us a message via Telegram  

We respond to all inquiries within 12-24 hours on weekdays. In rare cases, the response time may extend up to 48 hours. Please note that during holiday seasons, it may take longer.

Note: While we aim to provide the best support possible, please keep in mind that it only extends to verified merchants and only to issues related to our API and Platform like bugs and errors. Custom modifications, integrations or third party module implementations are not included.

Changelog

See what's new added, changed, fixed, improved or updated in the latest versions.

Keep checking up for regular updates.

Version 1.1 (In-Progress)

  • Info To be added

Version 1.0 (01 July, 2024)

  • Launched Initial Release