Payment Gateway

This document describes how to connect the BityclePay cryptocurrency payment gateway to e-commerce platforms. It includes a general explanation of the requirements for requesting payments from the BityclePay payment gateway by the merchant. This service uses the standard web service method over the secure https protocol to perform electronic payments.

Terminology

• Merchant: An individual, organization, or company that offers a product or service over the internet.
• Buyer: An individual who intends to purchase goods or services online using cryptocurrency.
• Transaction: A financial operation, which in this document refers to an online purchase.

Technical Information

• Payment Gateway Code (merchant): A unique code that BityclePay assigns to the merchant for registering each payment gateway. This code is provided to the user when they want to use our service on their e-commerce platform.
• Merchant's IP Address: The IP address of the main server of the merchant's website, which the merchant must provide to the BityclePay website via the dashboard.
• Terminal ID (terminalId): A unique identifier that BityclePay sends to the merchant for each purchase request.
• Transaction Reference Number (trxRefId): A unique identifier provided by BityclePay to the merchant after a successful deposit transaction. This identifier is used for financial tracking.
• Transaction Description (description): A brief text written by the merchant to describe the goods or services they intend to sell.
• Buyer's Email (email): Determined by the merchant in the web service, it is used to facilitate post-payment tracking; this parameter is optional.

Security Requirements

• It is recommended that an SSL certificate be activated on the merchant's website.
• Neither the merchant nor BityclePay should be aware of any financial information of the buyer. Therefore, BityclePay does not request any financial information from the buyer.

BityclePay Connection Guide

To use BityclePay's web service, you must use the provided web service addresses, methods, and parameters.

Get Available Tokens

This section is for retrieving the tokens supported by BityclePay for payments.

BASE_URL: 'https://api.ramzpay.org/pg/v1'

URL: /availableTokens

Method: GET

Auth required: NO

Permissions required: None

Response

Condition: If the request is successful

Code: 200

Content example

{
    "tokens": [
        "usdt"
    ]
}

RequestPay

This section is used to send a payment request to BityclePay.

Send Information

BASE_URL: 'https://api.ramzpay.org/pg/v1'

URL: /requestPay

Method: POST

Auth required: NO

Permissions required: None

Data constraints

{
  "merchant": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "description": "this is test",
  "callback_url":"https://merchantwebsite.com/ramzpay/callback/",
  "email": "mycustomeremail@email.com"
}

Response

Condition: If the request is successful

Code: 200

Content example

{
    "terminalId": "100000000000000044634",
    "token": "usdt",
    "addresses": [
        {
            "address": "0xEdfdff9c294Fc431898F4edb0Da6C48e3DE20fc9",
            "displayName": "BSC(BEP20) - Tether",
            "chainId": "1056",
            "chainName": "BSC"
        },
        {
            "address": "0xEdfdff9c294Fc431898F4edb0Da6C48e3DE20fc9",
            "displayName": "Polygon - Tether",
            "chainId": "1137",
            "chainName": "Polygon"
        },
        {
            "address": "TP2MCDnv59qAEhZZr4TxRgRK7cnXsiZdFB",
            "displayName": "Tron(TRC20) - Tether",
            "chainId": "1000",
            "chainName": "Tron"
        },
        {
            "address": "0xEdfdff9c294Fc431898F4edb0Da6C48e3DE20fc9",
            "displayName": "Ethereum(ERC20) - Tether",
            "chainId": "1001",
            "chainName": "Ethereum"
        }
    ]
}

Sending Payment Status to Merchant

• After a successful payment, BityclePay notifies the merchant using the callback provided by the merchant.

Method: POST

• The following parameters are sent in the callback:

InquiryPay

This section is used to inquire about a transaction.

Send Information

BASE_URL: 'https://api.ramzpay.org/pg/v1'

URL: /inquiryPay

Method: POST

Auth required: NO

Permissions required: None

Data constraints without trxRefId

If trxRefId is not sent, all successful transactions for the terminal will be returned in a paginated response.

{
  "merchant": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "terminalId": "100000000000000044634",
  "page": 1,
  "perPage": 15
}

Response

Condition: If the request is successful

Code: 200

Content example without trxRefId

{
    "transactions": {
        "data": [
            {
                "terminalId": "100000000000000044634",
                "token": "usdt",
                "trxRefId": "1137100639448111",
                "status": "SUCCESS",
                "amount": 0.2,
                "fee": 0.1,
                "trx_hash": "0x6ff28fed7308706a22f002c86f7d0d4c3573794f953821cf87a69c82637a0988",
                "network": "POLYGON_MUMBAI",
                "to": "0xA9D85351d5DE0c921F7c7f5AD39896dbE86C8969"
            },
            {
                "terminalId": "100000000000000044623",
                "token": "usdt",
                "trxRefId": "1137100639438801",
                "status": "SUCCESS",
                "amount": 0.3,
                "fee": 0.1,
                "trx_hash": "0x8cca1aca4cf6f8b1dc7343066577ba29f2d5b068b7322911b68a3cf467871f5c",
                "network": "POLYGON_MUMBAI",
                "to": "0xA9D85351d5DE0c921F7c7f5AD39896dbE86C8969"
            }
        ],
        "total": 2,
        "page": 1,
        "perPage": 15
    }
}

Data constraints with trxRefId

If trxRefId is specified in the request body, only the details of the transaction corresponding to the specified trxRefId will be returned.

{
  "merchant": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "terminalId":"100000000000000044634",
  "trxRefId":"113746090220182"
}

Response

Condition: If the request is successful

Code: 200

Content example with trxRefId

{
    "transaction": {
        "terminalId": "100000000000000044634",
        "token": "usdt",
        "trxRefId": "1137100639448111",
        "status": "SUCCESS",
        "amount": 0.2,
        "fee": 0.1,
        "trx_hash": "0x6ff28fed7308706a22f002c86f7d0d4c3573794f953821cf87a69c82637a0988",
        "to": "0xA9D85351d5DE0c921F7c7f5AD39896dbE86C8969",
        "network": "POLYGON_MUMBAI"
    }
}

BityclePay Integration Guide

You can view sample PHP and Laravel code in this section.

Warning: You need to obtain the merchant code from the BityclePay dashboard and then use its web services.

Laravel-requestPay

In this code, a deposit transaction request is created. The sample code below is for the requestPay section in Laravel.

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Http;

class TestController extends Controller
{
    public function requestPay()
    {
        $baseUrl = 'https://api.ramzpay.org/pg/v1';
        $merchant = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

        $response = Http::post($baseUrl . '/requestPay', [
            'merchant' => $merchant,
            'token' => 'usdt',
            'description' => 'order #100',
            'callback_url' => "https://mysite.ir/callback/",
            'email' => 'myclientemail@email.com',
        ]);

        return $response->json();
    }
}

Laravel-inquiryPay

In this code, a transaction verification request is made. The sample code below is for the inquiryPay section in Laravel.

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Http;

class TestController extends Controller
{
    public function inquiryPay()
    {
        $baseUrl = 'https://api.ramzpay.org/pg/v1';
        $merchant = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

        $response = Http::post($baseUrl . '/inquiryPay', [
            'merchant' => $merchant,
            'terminalId' => '100000000000000044623',
            'trxRefId' => '1801100639448111'
        ]);

        return $response->json();
    }
}

PHP-requestPay

In this code, a deposit transaction request is created. The sample code below is for the requestPay section in PHP.

<?php

namespace App\Http\Controllers;

class TestController
{
    private $baseUrl = 'https://api.ramzpay.org/pg/v1';
    private $merchant = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

    public function requestPay()
    {
        $url = $this->baseUrl . '/requestPay';
        $data = [
            'merchant' => $merchant,
            'token' => 'usdt',
            'description' => 'order #100',
            'callback_url' => "https://mysite.ir/callback/",
            'email' => 'myclientemail@email.com',
        ];

        $response = $this->makePostRequest($url, $data);

        return json_decode($response, true);
    }

    private function makePostRequest($url, $data)
    {
        $ch = curl_init($url);

        // Set cURL options
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        // Execute cURL session and get the result
        $result = curl_exec($ch);

        // Close cURL session
        curl_close($ch);

        return $result;
    }
}

PHP-inquiryPay

In this code, a transaction verification request is made. The sample code below is for the inquiryPay section in PHP.

<?php

namespace App\Http\Controllers;

class TestController
{
    private $baseUrl = 'https://api.ramzpay.org/pg/v1';
    private $merchant = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

    public function inquiryPay()
    {
        $url = $this->baseUrl . '/inquiryPay';

        $data = [
            'merchant' => $merchant,
            'terminalId' => '100000000000000044623',
            'trxRefId' => '1801100639448111'
        ];

        $response = $this->makePostRequest($url, $data);

        return json_decode($response, true);
    }

    private function makePostRequest($url, $data)
    {
        $ch = curl_init($url);

        // Set cURL options
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        // Execute cURL session and get the result
        $result = curl_exec($ch);

        // Close cURL session
        curl_close($ch);

        return $result;
    }
}