Create Address Payment Order

Place Order

curl --request POST \
  --url https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create \
  --header 'Content-Type: application/json' \
  --header 'X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>' \
  --header 'X-GatePay-Nonce: <x-gatepay-nonce>' \
  --header 'X-GatePay-On-Behalf-Of: <x-gatepay-on-behalf-of>' \
  --header 'X-GatePay-Signature: <x-gatepay-signature>' \
  --header 'X-GatePay-Timestamp: <x-gatepay-timestamp>' \
  --data '
{
  "merchantTradeNo": "93840202212210025",
  "env": {
    "terminalType": "MINIAPP"
  },
  "goods": {
    "goodsName": "USDT_PAY_BTC_TEST",
    "goodsDetail": "yc"
  },
  "orderExpireTime": 1673410179000,
  "merchantUserId": 1336974,
  "chain": "BSC",
  "fullCurrType": "BTC_BSC"
}
'

import requests

url = "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create"

payload = {
    "merchantTradeNo": "93840202212210025",
    "env": { "terminalType": "MINIAPP" },
    "goods": {
        "goodsName": "USDT_PAY_BTC_TEST",
        "goodsDetail": "yc"
    },
    "orderExpireTime": 1673410179000,
    "merchantUserId": 1336974,
    "chain": "BSC",
    "fullCurrType": "BTC_BSC"
}
headers = {
    "X-GatePay-Certificate-ClientId": "<x-gatepay-certificate-clientid>",
    "X-GatePay-Signature": "<x-gatepay-signature>",
    "X-GatePay-Timestamp": "<x-gatepay-timestamp>",
    "X-GatePay-Nonce": "<x-gatepay-nonce>",
    "X-GatePay-On-Behalf-Of": "<x-gatepay-on-behalf-of>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-GatePay-Certificate-ClientId': '<x-gatepay-certificate-clientid>',
    'X-GatePay-Signature': '<x-gatepay-signature>',
    'X-GatePay-Timestamp': '<x-gatepay-timestamp>',
    'X-GatePay-Nonce': '<x-gatepay-nonce>',
    'X-GatePay-On-Behalf-Of': '<x-gatepay-on-behalf-of>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchantTradeNo: '93840202212210025',
    env: {terminalType: 'MINIAPP'},
    goods: {goodsName: 'USDT_PAY_BTC_TEST', goodsDetail: 'yc'},
    orderExpireTime: 1673410179000,
    merchantUserId: 1336974,
    chain: 'BSC',
    fullCurrType: 'BTC_BSC'
  })
};

fetch('https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'merchantTradeNo' => '93840202212210025',
    'env' => [
        'terminalType' => 'MINIAPP'
    ],
    'goods' => [
        'goodsName' => 'USDT_PAY_BTC_TEST',
        'goodsDetail' => 'yc'
    ],
    'orderExpireTime' => 1673410179000,
    'merchantUserId' => 1336974,
    'chain' => 'BSC',
    'fullCurrType' => 'BTC_BSC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>",
    "X-GatePay-Nonce: <x-gatepay-nonce>",
    "X-GatePay-On-Behalf-Of: <x-gatepay-on-behalf-of>",
    "X-GatePay-Signature: <x-gatepay-signature>",
    "X-GatePay-Timestamp: <x-gatepay-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create")
  .header("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
  .header("X-GatePay-Signature", "<x-gatepay-signature>")
  .header("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
  .header("X-GatePay-Nonce", "<x-gatepay-nonce>")
  .header("X-GatePay-On-Behalf-Of", "<x-gatepay-on-behalf-of>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}")
  .asString();

package main

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

func main() {

	url := "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create"

	payload := strings.NewReader("{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
	req.Header.Add("X-GatePay-Signature", "<x-gatepay-signature>")
	req.Header.Add("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
	req.Header.Add("X-GatePay-Nonce", "<x-gatepay-nonce>")
	req.Header.Add("X-GatePay-On-Behalf-Of", "<x-gatepay-on-behalf-of>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create")

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

request = Net::HTTP::Post.new(url)
request["X-GatePay-Certificate-ClientId"] = '<x-gatepay-certificate-clientid>'
request["X-GatePay-Signature"] = '<x-gatepay-signature>'
request["X-GatePay-Timestamp"] = '<x-gatepay-timestamp>'
request["X-GatePay-Nonce"] = '<x-gatepay-nonce>'
request["X-GatePay-On-Behalf-Of"] = '<x-gatepay-on-behalf-of>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}"

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

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "prepayId": "47656656276819968",
    "terminalType": "MINIAPP",
    "expireTime": 1673410179000,
    "chain": {
      "chain_type": "BSC",
      "fullCurrType": "USDT_BSC",
      "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
    }
  }
}

POST

payment

open

institution

pay

address

create

Place Order

curl --request POST \
  --url https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create \
  --header 'Content-Type: application/json' \
  --header 'X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>' \
  --header 'X-GatePay-Nonce: <x-gatepay-nonce>' \
  --header 'X-GatePay-On-Behalf-Of: <x-gatepay-on-behalf-of>' \
  --header 'X-GatePay-Signature: <x-gatepay-signature>' \
  --header 'X-GatePay-Timestamp: <x-gatepay-timestamp>' \
  --data '
{
  "merchantTradeNo": "93840202212210025",
  "env": {
    "terminalType": "MINIAPP"
  },
  "goods": {
    "goodsName": "USDT_PAY_BTC_TEST",
    "goodsDetail": "yc"
  },
  "orderExpireTime": 1673410179000,
  "merchantUserId": 1336974,
  "chain": "BSC",
  "fullCurrType": "BTC_BSC"
}
'

import requests

url = "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create"

payload = {
    "merchantTradeNo": "93840202212210025",
    "env": { "terminalType": "MINIAPP" },
    "goods": {
        "goodsName": "USDT_PAY_BTC_TEST",
        "goodsDetail": "yc"
    },
    "orderExpireTime": 1673410179000,
    "merchantUserId": 1336974,
    "chain": "BSC",
    "fullCurrType": "BTC_BSC"
}
headers = {
    "X-GatePay-Certificate-ClientId": "<x-gatepay-certificate-clientid>",
    "X-GatePay-Signature": "<x-gatepay-signature>",
    "X-GatePay-Timestamp": "<x-gatepay-timestamp>",
    "X-GatePay-Nonce": "<x-gatepay-nonce>",
    "X-GatePay-On-Behalf-Of": "<x-gatepay-on-behalf-of>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-GatePay-Certificate-ClientId': '<x-gatepay-certificate-clientid>',
    'X-GatePay-Signature': '<x-gatepay-signature>',
    'X-GatePay-Timestamp': '<x-gatepay-timestamp>',
    'X-GatePay-Nonce': '<x-gatepay-nonce>',
    'X-GatePay-On-Behalf-Of': '<x-gatepay-on-behalf-of>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchantTradeNo: '93840202212210025',
    env: {terminalType: 'MINIAPP'},
    goods: {goodsName: 'USDT_PAY_BTC_TEST', goodsDetail: 'yc'},
    orderExpireTime: 1673410179000,
    merchantUserId: 1336974,
    chain: 'BSC',
    fullCurrType: 'BTC_BSC'
  })
};

fetch('https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'merchantTradeNo' => '93840202212210025',
    'env' => [
        'terminalType' => 'MINIAPP'
    ],
    'goods' => [
        'goodsName' => 'USDT_PAY_BTC_TEST',
        'goodsDetail' => 'yc'
    ],
    'orderExpireTime' => 1673410179000,
    'merchantUserId' => 1336974,
    'chain' => 'BSC',
    'fullCurrType' => 'BTC_BSC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-GatePay-Certificate-ClientId: <x-gatepay-certificate-clientid>",
    "X-GatePay-Nonce: <x-gatepay-nonce>",
    "X-GatePay-On-Behalf-Of: <x-gatepay-on-behalf-of>",
    "X-GatePay-Signature: <x-gatepay-signature>",
    "X-GatePay-Timestamp: <x-gatepay-timestamp>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create")
  .header("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
  .header("X-GatePay-Signature", "<x-gatepay-signature>")
  .header("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
  .header("X-GatePay-Nonce", "<x-gatepay-nonce>")
  .header("X-GatePay-On-Behalf-Of", "<x-gatepay-on-behalf-of>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}")
  .asString();

package main

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

func main() {

	url := "https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create"

	payload := strings.NewReader("{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-GatePay-Certificate-ClientId", "<x-gatepay-certificate-clientid>")
	req.Header.Add("X-GatePay-Signature", "<x-gatepay-signature>")
	req.Header.Add("X-GatePay-Timestamp", "<x-gatepay-timestamp>")
	req.Header.Add("X-GatePay-Nonce", "<x-gatepay-nonce>")
	req.Header.Add("X-GatePay-On-Behalf-Of", "<x-gatepay-on-behalf-of>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://openplatform.gateapi.io/payment/open/institution/v1/pay/address/create")

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

request = Net::HTTP::Post.new(url)
request["X-GatePay-Certificate-ClientId"] = '<x-gatepay-certificate-clientid>'
request["X-GatePay-Signature"] = '<x-gatepay-signature>'
request["X-GatePay-Timestamp"] = '<x-gatepay-timestamp>'
request["X-GatePay-Nonce"] = '<x-gatepay-nonce>'
request["X-GatePay-On-Behalf-Of"] = '<x-gatepay-on-behalf-of>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantTradeNo\": \"93840202212210025\",\n  \"env\": {\n    \"terminalType\": \"MINIAPP\"\n  },\n  \"goods\": {\n    \"goodsName\": \"USDT_PAY_BTC_TEST\",\n    \"goodsDetail\": \"yc\"\n  },\n  \"orderExpireTime\": 1673410179000,\n  \"merchantUserId\": 1336974,\n  \"chain\": \"BSC\",\n  \"fullCurrType\": \"BTC_BSC\"\n}"

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

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "prepayId": "47656656276819968",
    "terminalType": "MINIAPP",
    "expireTime": 1673410179000,
    "chain": {
      "chain_type": "BSC",
      "fullCurrType": "USDT_BSC",
      "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
    }
  }
}

Overview

This page documents the POST /payment/open/institution/v1/pay/address/create endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Create an order. When the order currency and payment currency are consistent, create a direct address payment order; if the order currency and payment currency are inconsistent, create a convert address payment order.

Notes

Authentication uses the standard GatePay signed headers.
This page documents the institution-path variant of the same API.
Institution requests must include X-GatePay-On-Behalf-Of to indicate the delegated account context; for institution merchant APIs, this is typically the target sub-account ID.
For shared signing rules, see /api-reference/version/100/en/common/securityAndSignature.

Headers

X-GatePay-Certificate-ClientId

string

required

Merchant client ID, obtained from GatePay platform

X-GatePay-Signature

string

required

HMAC-SHA256 signature for request validation

X-GatePay-Timestamp

string

required

Millisecond timestamp; the difference from server time must not exceed 30 seconds.

X-GatePay-Nonce

string

required

Random nonce for replay attack prevention

X-GatePay-On-Behalf-Of

string

required

Required delegated-subject header. Provide the initiating account ID for this request. For institution merchant APIs, this is typically the target sub-account ID; for institution charge and transfer APIs, it can be either an institution account ID or a sub-account ID.

Body

application/json

Request for creating a payment order.

merchantTradeNo

string

required

Merchant transaction ID in the merchant's system.

env

object

required

Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS.

Show child attributes

goods

object

required

Goods.

Show child attributes

orderExpireTime

integer<int64>

required

Merchant-specified expiration time of the order, in milliseconds.

merchantUserId

integer<int64>

required

Unique consumer ID from the merchant’s platform.

chain

string

required

Selected chain name.

fullCurrType

string

required

Currency field that includes the chain name and corresponds to the specific currency on the specific chain.

currency

string

Crypto currency in uppercase. Required for crypto orders together with orderAmount. Omit when creating a pure fiat order with fiatCurrency and fiatAmount (system converts to USDT). Must equal payCurrency (or payCurrency is backfilled from this).

orderAmount

string

Crypto order amount. Required together with currency for crypto orders. Omit for pure fiat orders that use fiatCurrency and fiatAmount.

toleranceAmount

string

Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required.

fiatCurrency

string

Fiat currency in uppercase, such as EUR, GBP, USD, CNY, JPY, AUD, CAD, CHF. For pure fiat orders, provide together with fiatAmount and omit currency/orderAmount.

fiatAmount

string

Fiat order amount, with a maximum precision of 2 digits. For pure fiat orders, provide together with fiatCurrency and omit currency/orderAmount.

surchargeAmount

string

Surcharge, a fee borne by the consumer.

payCurrency

string

Payment currency. Optional; if omitted, it is backfilled from currency. If provided, it must equal currency.

returnUrl

string

Callback URL for payment completion.

cancelUrl

string

Callback URL for payment cancellation.

channelId

string

Client Name.

Response

200 - application/json

SUCCESS

Response parameters

status

string

code

string

errorMessage

string

data

object

Show child attributes

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Create Address Payment Order

Overview

Notes

Headers

Body

Response

​Overview

​Notes

Headers

Body

Response

Overview

Notes