Ir para o conteúdo

API para lojistas ​

Utilize o endpoint de configuração pública para descobrir as opções de pagamento, criar um pedido no seu servidor e enviar o comprador para a URL de checkout retornada. Verifique a notificação assinada antes de processar o pedido. Exemplo de pedido em Python · Especificação OpenAPI

Assinar um pedido · Criar um pedido GMPay · Status da enquete · Retorno de pagamentos dos comerciantes

Endpoints ​

FinalidadeMétodoCaminhoAutenticação
Criar um pedido GMPayPOST/payments/gmpay/v1/order/create-transactionHMAC-SHA256 do lojista
Consultar configuraçãoGET/payments/gmpay/v1/configPúblico
Abrir o checkoutGET/pay/checkout-counter/{trade_id}Público
Consultar os dados do checkoutGET/pay/checkout-counter-resp/{trade_id}Público
Consultar status do pedidoGET/pay/check-status/{trade_id}Público
Selecionar rede ou provedorPOST/pay/switch-networkPúblico
Enviar o hash da transaçãoPOST/pay/submit-tx-hash/{trade_id}Público
Voltar à lojaGET/pay/return/{trade_id}Redirecionamento de navegador
Criar um pedido EPayGET ou POST/payments/epay/v1/order/create-transaction/submit.phpMD5 do lojista
Receber uma notificação do OKPayPOST/payments/okpay/v1/notifyAssinatura do OKPay

The quick brown fox jumps over the lazy dog. ​

Os endpoints JSON retornam status_code (200 em caso de sucesso), message, data (objeto ou null), e o request_id gerado pelo servidor. Assinaturas inválidas retornam um código HTTP 401. Erros de negócio geralmente retornam um código HTTP 400 com um código de erro da aplicação.

json
{
  "status_code": 200,
  "message": "success",
  "data": {},
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

Assinar uma requisição ​

Utilize a chave de comerciante associada ao pid da solicitação. Uma nova instalação inicializa um comerciante padrão com PID 1000. Mantenha o segredo no servidor do comerciante.

O GMPay usa HMAC-SHA256. Exclua o campo signature, as strings vazias e os valores nulos. Ordene os nomes dos campos restantes em ordem ASCII crescente, respeitando maiúsculas e minúsculas. Una os pares key=value sem escape com &. Use secret_key como chave HMAC e codifique o resultado em 64 caracteres hexadecimais minúsculos. Inclua pid e qualquer payment_type não vazio. Em JSON, o servidor interpreta um número como 100.00 como 100. A codificação de formulário permite enviar a representação original como string.

Exemplos de campos, string canônica e assinatura utilizando a chave de demonstração epusdt_secret_key:

text
pid=1000
order_id=ORD202605230001
currency=cny
token=usdt
network=tron
amount=100
notify_url=https://merchant.example/notify
redirect_url=https://merchant.example/return
name=VIP
text
amount=100&currency=cny&name=VIP&network=tron&notify_url=https://merchant.example/notify&order_id=ORD202605230001&pid=1000&redirect_url=https://merchant.example/return&token=usdt
text
signature=6f874b1919d95081835e2809b620e354a5866f5a6dbb2e432d1627f1eb10059d

Exemplos em PHP ​

GMPay:

php
function gmpaySign(array $params, string $secretKey): string
{
    unset($params['signature']);
    ksort($params, SORT_STRING);

    $pairs = [];
    foreach ($params as $key => $value) {
        if ($value === '' || $value === null) {
            continue;
        }
        $pairs[] = $key . '=' . $value;
    }

    return hash_hmac('sha256', implode('&', $pairs), $secretKey);
}

EPay exclui sign e sign_type, adiciona o segredo do comerciante à string canônica e utiliza MD5.

php
function epaySign(array $params, string $secretKey): string
{
    unset($params['sign'], $params['sign_type']);
    ksort($params, SORT_STRING);

    $pairs = [];
    foreach ($params as $key => $value) {
        if ($value === '' || $value === null) {
            continue;
        }
        $pairs[] = $key . '=' . $value;
    }

    return strtolower(md5(implode('&', $pairs) . $secretKey));
}

Criar um pedido no GMPay ​

POST /payments/gmpay/v1/order/create-transaction aceita JSON e application/x-www-form-urlencoded.

json
{
  "pid": "1000",
  "order_id": "ORD202605230001",
  "currency": "cny",
  "token": "usdt",
  "network": "tron",
  "amount": 100,
  "notify_url": "https://merchant.example/notify",
  "redirect_url": "https://merchant.example/return",
  "name": "VIP",
  "signature": "6f874b1919d95081835e2809b620e354a5866f5a6dbb2e432d1627f1eb10059d"
}
CampoTipoObrigatórioDescrição
pidStringSimO PID do comerciante era usado para consultar a chave de assinatura.
order_idStringSimIdentificador único de pedido de comerciante, até 32 caracteres.
currencyStringSimMoeda fiduciária, por exemplo usd ou cny.
tokenStringCondicionalAtivo recebido. Combinar com a rede ou omitir ambos.
networkStringCondicionalID da rede a partir da configuração pública, por exemplo, binance.
amountNúmeroSimValor do Fiat superior a 0,01.
notify_urlStringSimURL de callback de sucesso assíncrono.
redirect_urlStringNãoURL de retorno do navegador.
nameStringNãoNome do produto ou pedido.
payment_typeStringNãoUtiliza GMPay por padrão. EPay (em qualquer formato de letra) seleciona o formato de callback de EPay e requer um PID numérico. Inclua qualquer valor não vazio na assinatura.
signatureStringSimAssinatura HMAC-SHA256 de 64 caracteres em minúsculas.

Forneça tanto o token quanto a network para alocar um endereço imediatamente. Omita ambos para criar um marcador (status 4) contendo o valor fiat e a moeda. Fornecer apenas um é inválido. Verifique data.supported_assets na configuração pública antes de selecionar um par.

Resposta ​

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "order_id": "ORD202605230001",
    "amount": 100,
    "currency": "CNY",
    "actual_amount": 14.29,
    "receive_address": "TTestTronAddress001",
    "token": "USDT",
    "status": 1,
    "expiration_time": 1779530812,
    "payment_url": "https://pay.example.com/pay/checkout-counter/20260523171652123456001"
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}
CampoTipoSignificado
trade_idStringID da transação EPUSDT.
order_idStringID do pedido no sistema do lojista.
amountNúmeroValor do Fiat apresentado.
currencyStringMoeda fiduciária.
actual_amountNúmeroValor a pagar em criptomoeda.
receive_addressStringEndereço de entrega.
tokenStringSímbolo de ativo.
statusInteiroEstado do pedido. Um valor de 4 significa "aguardando seleção".
expiration_timeInteiroValidade como timestamp Unix em segundos.
payment_urlStringURL para abrir no navegador.

Um marcador não possui endereço ou token e um actual_amount de zero. A expiração ou o fechamento manual o move para o status 3, sem liberar uma reserva de pagamento. A seleção de checkout determina o endereço ou a URL hospedada.

Configuração de checkout público ​

GET /payments/gmpay/v1/config retorna as marcações de checkout, os ativos disponíveis na cadeia, as configurações padrão do EPay e as configurações públicas dos provedores okpay e xlayer. Cada entrada em supported_assets requer uma cadeia habilitada, um endereço de recebimento disponível e um token configurado para pagamento. Os métodos hospedados expõem sua própria flag enabled e a lista allow_tokens.

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "supported_assets": [
      {
        "network": "tron",
        "display_name": "TRON",
        "tokens": ["TRX", "USDT"]
      },
      {
        "network": "solana",
        "display_name": "Solana",
        "tokens": ["SOL", "USDC", "USDT"]
      }
    ],
    "site": {
      "cashier_name": "Acme Cashier",
      "logo_url": "https://cdn.example.com/logo.png",
      "website_title": "Acme Payments",
      "support_link": "https://example.com/support",
      "background_color": "#0f172a",
      "background_image_url": "https://cdn.example.com/background.png",
      "withdrawal_reminder_enabled": true
    },
    "epay": {
      "default_token": "",
      "default_currency": "cny",
      "default_network": ""
    },
    "okpay": {
      "enabled": false,
      "allow_tokens": ["USDT", "TRX"]
    },
    "xlayer": {
      "enabled": false,
      "allow_tokens": ["USDC", "USDT0", "USDG"]
    },
    "version": "v2.1.0"
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

Aviso sobre saques de corretoras ​

Após carregar a configuração, exibir o lembrete somente quando site.withdrawal_reminder_enabled for verdadeiro, se o pedido on-chain estiver aguardando pagamento, um endereço de recebimento estiver disponível e actual_amount > 0. Tratar a ausência da flag em versões mais antigas como verdadeiro. Exibir o valor líquido total recebido após as taxas de troca, utilizando a mesma precisão e token do pedido. Prévia clara · Prévia escura

Administradores acessam GET /admin/api/v1/settings?group=brand. O valor armazenado de brand.withdrawal_reminder_enabled é a string "true" ou "false". Para alterá-lo, envie a seguinte requisição PUT /admin/api/v1/settings autenticada. Verifique a flag ok do item retornado e reabra o processo de checkout.

json
{"items":[{"group":"brand","key":"brand.withdrawal_reminder_enabled","type":"bool","value":false}]}

Abra a área de checkout e revise o pedido. ​

A payment_url retornada na criação aponta para GET /pay/checkout-counter/{trade_id}. Ao abri-la em um navegador, retorna um redirecionamento 301 para:

text
/cashier/{trade_id}

Obtenha GET /pay/checkout-counter-resp/{trade_id} para exibir os detalhes. Esta resposta utiliza milissegundos para created_at e expiration_time. Verifique o endpoint de status para alterações subsequentes.

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "amount": 100,
    "actual_amount": 14.29,
    "token": "USDT",
    "currency": "CNY",
    "receive_address": "TTestTronAddress001",
    "network": "tron",
    "status": 1,
    "payment_type": "gmpay",
    "expiration_time": 1779530812000,
    "redirect_url": "https://merchant.example/return",
    "payment_url": "",
    "created_at": 1779530212000,
    "is_selected": false
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

Para um marcador, o mesmo ID do pai é retornado com campos on-chain vazios. Tanto GMPay quanto EPay podem criar este estado.

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "amount": 100,
    "actual_amount": 0,
    "token": "",
    "currency": "CNY",
    "receive_address": "",
    "network": "",
    "status": 4,
    "payment_type": "gmpay",
    "expiration_time": 1779530812000,
    "redirect_url": "https://merchant.example/return",
    "payment_url": "",
    "created_at": 1779530212000,
    "is_selected": false
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

O processo de checkout retorna payment_type em letras minúsculas (gmpay ou epay), o que seleciona o formato de callback do comerciante. Para o OKX OnchainOS na Camada X, abra a URL hospedada retornada pelo servidor. O EPUSDT verifica a ordem de negociação do provedor antes de creditar.

Consultar o status periodicamente ​

GET /pay/check-status/{trade_id}

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "status": 1
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}
StatusSignificado
1Aguardando pagamento
2Pago
3Expirado
4Aguardando a seleção de uma rede, ativo ou fornecedor.
5Foi observada uma transferência correspondente, e está sendo confirmada.
6Duas rodadas de verificação rigorosa não foram suficientes. É necessária uma revisão manual.

No nível 5, continue monitorando e exibir "Confirmando" para que o comprador saiba que a transferência foi visualizada. Por padrão, EPUSDT verifica a profundidade de confirmação necessária e verifica a transação com dois nós independentes antes de creditá-la. Aguardar a profundidade não consome nenhuma tentativa. Os tentos de verificação e os primeiros IDs de nós persistem após reinicializações. No nível 6, a verificação automática e as chamadas de retorno de sucesso são pausadas. Um administrador pode inspecionar review_transaction_hash e rever a transação após investigar.

Para um hash fornecido pelo comprador, envie block_transaction_id para POST /pay/submit-tx-hash/{trade_id}. O servidor verifica a transferência. A rota de retorno do navegador, GET /pay/return/{trade_id}, envia um redirecionamento HTTP 302.

Envie Hash da Transação do Caixa ​

POST /pay/submit-tx-hash/{trade_id}

Este endpoint permite que o caixa hospedado envie um hash de transação on-chain para verificação manual. Ele é intencionalmente mais limitado do que a ação "marcar como pago" do administrador.

  • A ordem deve ser uma ordem on-chain.
  • A ordem ainda deve ter status=1, aguardando pagamento.
  • Pedidos expirados são rejeitados antes da verificação da cadeia.
  • As ordens do OkPay/provedor não são suportadas.

Solicitar Hash de Transação ​

json
{
  "block_transaction_id": "0xabc123..."
}

Resposta de Sucesso: Transação Enviada ​

json
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "block_transaction_id": "0xabc123...",
    "status": 2
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

O TON aceita referências canônicas no formato ton:<receive_raw>:<lt>:<hash>, referências lt:hash ou uma referência exclusiva e recente, apenas com hash, para o endereço de recebimento da ordem. O Aptos aceita um hash de transação.

Mudar a rede ou provedor de pagamento. ​

POST /pay/switch-network aceita um trade_id pai, um token de destino e a network. Para checkout hospedado, selecione okpay ou xlayer com um token autorizado por esses provedores.

json
{
  "trade_id": "20260523171652123456001",
  "token": "USDT",
  "network": "solana"
}
json
{
  "trade_id": "20260523171652123456001",
  "token": "USDT",
  "network": "okpay"
}
  • Apenas um pedido de um cliente em aberto (status 1 ou 4) pode ser transferido. Um pedido de criança não pode ser transferido novamente.
  • A primeira seleção em um marcador completa o mesmo pedido original e o move para o status 1. O checkout na blockchain agora aloca um endereço e um valor. O checkout hospedado retorna a URL de pagamento do provedor. Para o OKPay, o campo do endereço de recebimento contém "OKPAY".
  • O espaço reservado (placeholder) permanece inicialmente com is_selected=false. Ao selecionar o mesmo alvo novamente, retorna a ordem existente e marca-o como selecionado. Mudar para um alvo diferente pode criar no máximo um filho por pai.
  • A resposta tem a estrutura "checkout-detail". Os pedidos on-chain possuem um payment_url vazio.

Checkout compatível com EPay ​

Envie uma consulta GET ou um formulário POST para /payments/epay/v1/order/create-transaction/submit.php. O sucesso retorna um código HTTP 302 para:

text
/pay/checkout-counter/{trade_id}
CampoLocalizaçãoTipoObrigatórioDescrição
pidConsulta ou formulárioStringSimID do comerciante PID. Utilize um PID numérico para as chamadas de retorno.
moneyConsulta ou formulárioNúmeroSimValor do Fiat.
out_trade_noConsulta ou formulárioStringSimID do pedido no sistema do lojista.
notify_urlConsulta ou formulárioStringSimURL de callback do lojista.
return_urlConsulta ou formulárioStringNãoURL de retorno do navegador.
nameConsulta ou formulárioStringNãoNome do produto ou pedido.
typeConsulta ou formulárioStringNãoVazio, alipay, ou um seletor token.network habilitado.
tokenConsulta ou formulárioStringNãoSolicitado token quando nenhum seletor foi encontrado.
networkConsulta ou formulárioStringNãoSolicitando rede quando nenhum seletor corresponde.
currencyConsulta ou formulárioStringNãoSubstitui a moeda padrão do EPay.
signConsulta ou formulárioStringSimAssinatura EPay MD5.
sign_typeConsulta ou formulárioStringNãoNormalmente, MD5.

Inclua no cálculo MD5 todos os parâmetros recebidos que tenham valor, inclusive campos de plugins como sitename. Exclua apenas sign e sign_type. O exemplo abaixo mostra a entrada canônica com a chave secreta de demonstração, seguida da assinatura.

text
money=100&name=VIP&notify_url=https://merchant.example/notify&out_trade_no=ORD202605230001&pid=1000&return_url=https://merchant.example/return&type=alipayepusdt_secret_key
text
sign=b865b0acbb2b01554c35a1bd33351452

Seleção de ativo. Um seletor token.network aceito no campo type tem precedência sobre o token e a rede explícitos e sobre os valores padrão. Um tipo desconhecido e não vazio, como usdt-tron, retorna 10009. Se o tipo estiver vazio ou for alipay, cada campo ausente recebe o respectivo padrão do EPay. Se ambos continuarem vazios, o servidor cria um pedido provisório. Se faltar apenas um, a requisição é rejeitada. Para a moeda, a ordem é o valor enviado, o padrão configurado e, por fim, cny.

Instalações novas inicializam cny e deixam o token e a rede padrão vazios. As configurações existentes são preservadas durante as atualizações. O servidor define payment_type=Epay após a verificação da assinatura. Assine qualquer type, token, network e currency que você realmente envie.

Callbacks para o lojista ​

EPUSDT notifica a URL notify_url da ordem após o pagamento bem-sucedido. Verifique a assinatura, compare a ordem e o valor, e processe as notificações repetidas de forma idempotente. Responda com HTTP 200 e um corpo contendo ok ou success (insensível a maiúsculas/minúsculas). Se a entrega falhar, tente novamente de acordo com order_notice_max_retry e callback_retry_base_seconds, com retrocesso exponencial limitado a cinco minutos.

GMPay ​

O GMPay envia JSON via POST. Consulte a chave do comerciante local usando o pid e verifique o HMAC utilizando a mesma canonização utilizada na criação do pedido. O corpo omite o payment_type.

json
{
  "pid": "1000",
  "trade_id": "20260523171652123456001",
  "order_id": "ORD202605230001",
  "amount": 100,
  "actual_amount": 14.29,
  "receive_address": "TTestTronAddress001",
  "token": "USDT",
  "block_transaction_id": "0xabc123...",
  "signature": "498975a97bc34563bdb14df53fc18054645df9684d6c67d9b9dd90ec62be1018",
  "status": 2
}
CampoTipoSignificado
pidStringIdentificador de chave de comerciante.
trade_idStringID da transação EPUSDT.
order_idStringID do pedido no sistema do lojista.
amountNúmeroValor do Fiat.
actual_amountNúmeroValor recebido em criptomoeda.
receive_addressStringEndereço de entrega.
tokenStringBem recebido.
block_transaction_idStringReferência de hash ou provedor na cadeia.
signatureStringHash HMAC-SHA256.
statusInteiroPago (2).

EPay ​

O EPay envia uma solicitação GET com um type numérico. Utilize um pid de comerciante numérico para os pedidos do EPay e do GMPay, selecionando payment_type=Epay. A chamada de retorno utiliza o tipo salvo no pedido ou retorna para alipay. Verifique a assinatura MD5 como para um pedido de EPay de entrada.

text
pid=1000
trade_no=20260523171652123456001
out_trade_no=ORD202605230001
type=alipay
name=VIP
money=100.0000
trade_status=TRADE_SUCCESS
sign=cc44fab3f264615d859f8a1fd36d2f08
sign_type=MD5

Callback do provedor OKPay ​

Configure POST /payments/okpay/v1/notify no OKPay. Ele aceita JSON, formulário codificado em URL, formulário de partes múltiplas ou um corpo de string de consulta. O EPUSDT verifica a assinatura do provedor com o token da loja, processa o pedido correspondente e aciona a chamada de retorno do comerciante. Isso cobre um pedido de substituição concluído ou um pedido filho hospedado.

Resposta bem-sucedida.

text
success

Erro (HTTP 400):

text
fail

Códigos de erro de aplicação ​

CódigoHTTPSignificado
200200Sucesso
400400Erro no sistema ou de validação.
401401Assinatura inválida
10001400O endereço da carteira já existe.
10002400O pedido já existe
10003400Sem endereço de entrega disponível.
10004400Valor abaixo da precisão do pagamento
10005400Nenhuma combinação de endereço/valor disponível.
10006400Cálculo da taxa de câmbio não foi possível.
10007400Bloco já processado.
10008400Pedido não encontrado
10009400Parâmetros inválidos
10010400Estado do pedido alterado
10011400Limite de pedidos infantil atingido.
10012400Não é possível alternar entre redes em um pedido infantil.
10013400O pedido não está pendente
10014400Rede desativada
10016400Recurso não encontrado
10017400O provedor de pagamento foi desativado.
10018400Configuração do provedor de pagamento incompleta.
10019400Token ou rede do provedor não suportada.
10038400Verificação do hash da transação falhou.
10039400A verificação manual requer um pedido na blockchain.
10041400URL de notificação inválida.
10042400A criação do pedido do fornecedor falhou.
10044400URL de redirecionamento inválida.
10045400Chave do comerciante indisponível.
10046400Impossibilidade de definir os parâmetros de retorno do EPay.

Lista completa de erros da aplicação

Para listas e precedência de métodos EPay, consulte o guia de integração EPay.