RECURSOS PARA DESENVOLVEDORES

Desenvolvimento de API

Referência API, exemplos de servidor e mobile, retornos e notificações em um só guia. PHP, Node.js, Python, C#, Java, iOS Swift e Android Kotlin suportam ON_SITE e HPP.

REST API · INTERFACE DE PAGAMENTO

Um pedido. ON_SITE ou HPP.

Crie e vincule o pedido no servidor; depois escolha a apresentação. Os dois modos mantêm order_id.

ConsulteRetornos síncronos HPP e notificações assíncronas ON_SITE/HPP, com código PHP, Node.js, Python, C# e Java.

ON_SITE

Janela de pagamento na loja

Mostre valor, endereço, rede e QR em janela própria. Seu servidor consulta e retorna uma tela segura.

Ver HTML e PHP →
HPP

Redirecionar ao pagamento MochiPay

Redirecione para payment_url e verifique retorno ou notificação com Query Order autenticado.

Ver redirecionamento PHP →

Trechos de checkout.php e auxiliares do PHP Demo 1.1.4 (PHP 7.0–8.4). Crie primeiro com order.php para obter os dois links. Em produção, carregue o pedido autorizado da sessão/banco e conclua com uma transação idempotente.

Redirecionar após verificar no servidor

HPP · PHP

Validate the stored order binding and destination, then send the Location header before any page output.

checkout.php · HPP branch
// checkout.php: after loading the saved attempt and
// verifying its token, order binding and payment URL.
// $payment is the authenticated Query Order response.
if ($mode === 'HPP') {
    header('Location: ' . $payment['payment_url'], true, 303);
    exit; // Send the header before any HTML output.
}
// Verify the notification/return server-side before fulfillment.

The complete file loads the saved attempt and validates its token, authenticated query and expected payment_url before this branch.

Exibir a janela na sua página

ON_SITE · PHP + HTML

Include the local dialog assets in your checkout HTML. The browser talks to your local poll endpoint; it never signs requests or receives API credentials.

checkout.php · local dialog assets
// checkout.php: use the SAME saved reference/token.
$pollUrl = 'order.php?' . http_build_query([
    'view' => $reference, 'token' => $token, 'poll' => 1
], '', '&', PHP_QUERY_RFC3986);
$completeUrl = 'callback.php?' . http_build_query([
    'mode' => 'return', 'merchant_order_id' => $reference
], '', '&', PHP_QUERY_RFC3986);
$config = json_encode([
    'poll' => $pollUrl, 'complete' => $completeUrl
], JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT);
?>
<!-- Inside your own checkout page: -->
<link rel="stylesheet" href="portable/onsite.css">
<button id="reopen" type="button">Open payment dialog</button>
<script>window.MochiPayConfig = <?php echo $config; ?>;</script>
<script src="portable/qrcode.min.js"></script>
<script src="portable/onsite.js"></script>

onsite.js opens the dialog over your existing page. Closing it leaves checkout visible; the Open payment dialog button reopens the same payment.

Seu servidor verifica o pedido

Authorize the saved reference/token, query by the stored MochiPay order_id, and compare the original amount/currency, asset/network, address and exact payable amount. Return only a safe payment view with decimal strings.

order.php · local polling endpoint
// order.php?view=...&token=...&poll=1 (server-side)
// The demo has already authorized the saved attempt/token.
$response = mochipay_query_order(
    'order_id', $record['snapshot']['order_id']
);
if (!$response['ok'] || !mochipay_bound($record, $response['data'])) {
    http_response_code(403);
    exit;
}
// Also check the expected received amount before accepting PAID.
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
echo json_encode([
    'success' => true,
    'data' => MochiPayPortable::view($response['data'])
]); // Safe view: decimal strings; no credentials/customer fields.

The full demo additionally verifies the received amount for PAID. callback.php verifies notifications and browser returns. A screenshot, redirect or browser flag is never proof of payment.

Autenticação

Every API request must include the merchant API key and a Base64-encoded HMAC-SHA256 signature.

CabeçalhoobrigatórioDescrição
X-Mochi-KeySimYour merchant API key.
X-Mochi-SignatureSimBase64-encoded HMAC-SHA256 signature.
Content-TypePOST requestsapplication/json
Keep your API secret on the server. Never expose it in browser JavaScript, mobile applications or public source code.

Assinatura

For Create Order, sign the exact raw JSON body. For Query Order, sign the raw query string without the leading ?.

SIGNATURE FORMULA
Base64(HMAC-SHA256(UTF8(signing_text), UTF8(api_secret)))

Moedas compatíveis

The order currency prices the purchase. The payment method selects the cryptocurrency and blockchain network used to pay.

MOEDAS DOS PEDIDOS

28 supported fiat currencies

Use one of these exact ISO codes in the currency Campo.

USDEURGBPCAD AUDNZDJPYCNY HKDSGDCHFSEK NOKDKKPLNCZK HUFAEDSARINR IDRTHBMYRPHP KRWBRLMXNZAR
CRYPTO ORDER CURRENCIES

Preços em criptomoedas

Orders may also be priced directly in these cryptocurrencies.

USDTUSDCBTCETHSOL
MÉTODOS DE PAGAMENTO

Supported cryptocurrency and network combinations

Send one of these exact values in the payment_method Campo.

USDT_TRC20USDT on TRON
USDC_ERC20USDC on Ethereum
BTC_BITCOINNative BTC on Bitcoin
ETH_ERC20Native ETH on Ethereum
SOL_SOLANANative SOL on Solana
Regra de conversão: If the order currency and payment asset are the same, MochiPay uses a rate of 1 without conversion. Otherwise, the stored exchange rate and merchant markup are applied when the order is created. View current reference exchange rates →
Valor do pedidoMétodo de pagamentoResultado
49.90 USDUSDT_TRC20Uses the stored USD → USDT rate and merchant markup.
100 EURBTC_BITCOINUses the stored EUR → BTC rate and merchant markup.
25 USDCUSDC_ERC20No conversion. The exchange rate is 1.

Criar pedido

Create a payment order with a hosted payment URL and the payment instructions needed for an on-site interface.

POST https://mochi.bz/api/v1/orders/create

Parâmetros da solicitação

Order currency and payment method are different concepts. amountecurrency define the merchant's original order value. payment_method defines the cryptocurrency and blockchain network used by the customer to pay. For example, 49.90 USD com USDT_TRC20 means that a USD-denominated order is paid with the calculated amount of USDT on the TRON network.
ParâmetroobrigatórioTipo / tamanhoDescrição
merchant_order_idSimstring · 1–100Your order reference. Without request_id, each successful creation receives a new globally unique MochiPay order_id. With request_id, a retry reuses its original order.
amountSimdecimal(28,8)Positive original order amount. Fiat normally uses 2 decimal places; supported cryptocurrencies may use up to 8.
currencySimstring · 1–20Original order currency code. It may be fiat, such as USD ou EUR, or cryptocurrency, such as USDT ou USDC.
payment_methodSimasset ≤20 + network ≤30Payment cryptocurrency and blockchain network in ASSET_NETWORK format, such as USDT_TRC20 ou USDC_ERC20.
unique_amount_directionNãoUP ou DOWNDirection used for the small unique amount adjustment. Defaults to UP.
product_typeNãoPHYSICAL ou DIGITAL_SERVICEOrder type displayed at checkout. Defaults to DIGITAL_SERVICE. Shipping fields remain optional for both types.
descriptionNãostring · 0–500Human-readable order description.
product_infoNãoJSON/string · nvarchar(max)Product, cart or custom metadata. The complete HTTP request body must not exceed 65,536 bytes.
customer_emailNãostring · 0–255Customer email address. When supplied, it must be a valid email address.
customer_phoneNãostring · 0–50Customer telephone number.
first_nameNãostring · 0–100Customer first name.
last_nameNãostring · 0–100Customer last name.
companyNãostring · 0–200Customer company or organization name.
countryNãostring · 0–100Customer country or region.
stateNãostring · 0–100Customer state, province or region.
cityNãostring · 0–100Customer city.
address1Nãostring · 0–500Primary customer address line.
address2Nãostring · 0–500Additional customer address line.
postal_codeNãostring · 0–30Customer postal or ZIP code.
request_idNãostring · 1–64Optional retry key, scoped to your merchant. Sign it with the JSON body. Reuse the same key and payload after a timeout. See request deduplication.
notify_urlNãostring · 0–1000Absoluto http:// ou https:// asynchronous server notification URL. Only public destinations are allowed; localhost, private/reserved IPs and redirects are blocked.
redirect_urlNãostring · 0–1000Absolute customer return URL used after a successful payment.
customer_ipNãoIPv4/IPv6 · 0–45Customer IP supplied by the merchant. MochiPay also records the API request IP separately.

Exemplo de solicitação

JSON
{
  "merchant_order_id": "ORDER-20260919-001",
  "amount": 49.90,
  "currency": "USD",
  "payment_method": "USDT_TRC20",
  "unique_amount_direction": "UP",
  "product_type": "DIGITAL_SERVICE",
  "description": "MochiPay order",
  "customer_email": "customer@example.com",
  "redirect_url": "https://merchant.example.com/payment/return"
}
C# · CREATE ORDER
string baseUrl = "https://mochi.bz";
string body = @"{
  ""merchant_order_id"": ""ORDER-20260920-001"",
  ""amount"": 49.90,
  ""currency"": ""USD"",
  ""payment_method"": ""USDT_TRC20"",
  ""unique_amount_direction"": ""UP"",
  ""product_type"": ""DIGITAL_SERVICE"",
  ""description"": ""Example order"",
  ""notify_url"": ""https://merchant.example.com/mochipay/notify"",
  ""redirect_url"": ""https://merchant.example.com/payment/return""
}";

string signature;
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
{
    signature = Convert.ToBase64String(
        hmac.ComputeHash(Encoding.UTF8.GetBytes(body)));
}

using (var client = new HttpClient())
using (var request = new HttpRequestMessage(
    HttpMethod.Post, baseUrl + "/api/v1/orders/create"))
{
    request.Headers.Add("X-Mochi-Key", apiKey);
    request.Headers.Add("X-Mochi-Signature", signature);
    request.Content = new StringContent(body, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await client.SendAsync(request);
    string json = await response.Content.ReadAsStringAsync();
}
PHP 7.0–8.4 · CREATE ORDER
<?php
$baseUrl = 'https://mochi.bz';
$apiKey = 'YOUR_API_KEY';
$apiSecret = 'YOUR_API_SECRET';

$payload = [
    'merchant_order_id' => 'ORDER-20260920-001',
    'amount' => '49.90',
    'currency' => 'USD',
    'payment_method' => 'USDT_TRC20',
    'unique_amount_direction' => 'UP',
    'product_type' => 'DIGITAL_SERVICE',
    'description' => 'Example order',
    'notify_url' => 'https://merchant.example.com/mochipay/notify',
    'redirect_url' => 'https://merchant.example.com/payment/return'
];

$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$signature = base64_encode(
    hash_hmac('sha256', $body, $apiSecret, true)
);

$ch = curl_init($baseUrl . '/api/v1/orders/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Mochi-Key: ' . $apiKey,
        'X-Mochi-Signature: ' . $signature
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_TIMEOUT => 30
]);

$json = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);

if ($json === false) {
    throw new RuntimeException($error);
}

// Preserve decimal JSON numbers as text before decoding.
$json = preg_replace(
    '/("(?:amount|base_pay_amount|pay_amount|received_amount|exchange_rate|rate_markup_percent|unique_amount_delta)"\s*:\s*)(-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)(?=\s*[,}])/',
    '$1"$2"', $json
);
$result = json_decode($json, true);
if ($httpCode < 200 || $httpCode >= 300 || empty($result['success'])) {
    throw new RuntimeException('MochiPay request failed. Review before retrying creation.');
}
?>

Resposta de sucesso

CampoTipo / tamanhoDescrição
successbooleanTrue when creation succeeds.
order_idstring · 32MochiPay system identifier. Store it with your local order.
merchant_order_idstring · ≤100Your original merchant reference.
product_typestring · ≤20PHYSICAL or DIGITAL_SERVICE.
statusstring · ≤20Current payment status.
amountdecimal(28,8)Original order amount; preserve decimal precision.
currencystring · ≤20Original pricing currency.
base_pay_amountdecimal(28,8)Converted amount before the unique adjustment.
unique_amount_deltadecimal(28,8)Signed matching adjustment.
unique_amount_directionstring · ≤10UP or DOWN.
pay_amountdecimal(28,8)Exact chain amount to display and send. Do not round.
payment_methodstringSelected asset/network, e.g. USDT_TRC20.
payment_addressstring · ≤255Receiving address for this payment and network.
payment_urlstring · URLHPP URL. On-site uses the same order instructions.
expires_atdatetimeExpiration in yyyy-MM-dd HH:mm:ss format.
HTTP 200 · JSON
{
  "success": true,
  "order_id": "41ad45477bd444f3bd89f0bab7f571bb",
  "merchant_order_id": "ORDER-20261003-001",
  "product_type": "DIGITAL_SERVICE",
  "status": "WAITING_PAYMENT",
  "amount": 49.90,
  "currency": "USD",
  "base_pay_amount": 49.90,
  "unique_amount_delta": 0.001,
  "unique_amount_direction": "UP",
  "pay_amount": 49.901,
  "payment_method": "USDT_TRC20",
  "payment_address": "TExampleReceivingAddressForIllustrationOnly",
  "payment_url": "https://mochi.bz/pay/41ad45477bd444f3bd89f0bab7f571bb",
  "expires_at": "2026-10-03 15:30:00"
}

Consultar pedido

Retrieve an order owned by the authenticated merchant using exactly one order identifier.

GET https://mochi.bz/api/v1/orders/query
Parâmetro de consultaobrigatórioTipo / tamanhoDescrição
order_idOne of twostring · 32MochiPay order identifier.
merchant_order_idOne of twostring · 1–100Your merchant order identifier. If it was reused, the newest matching order is returned.
Usar order_id once stored. After an uncertain Create response, query the same unique merchant reference before deciding what happened; repeated Create requests are not guaranteed to be idempotent. Send only one identifier. Sign the exact raw query string, for example merchant_order_id=ORDER-20260919-001.

Exemplos de consulta

C# · QUERY ORDER
string baseUrl = "https://mochi.bz";
string query = "merchant_order_id=ORDER-20260919-001";

using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
{
    string signature = Convert.ToBase64String(
        hmac.ComputeHash(Encoding.UTF8.GetBytes(query)));

    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-Mochi-Key", apiKey);
        client.DefaultRequestHeaders.Add("X-Mochi-Signature", signature);
        string json = await client.GetStringAsync(
            baseUrl + "/api/v1/orders/query?" + query);
    }
}
PHP 7.0–8.4 · QUERY ORDER
<?php
$baseUrl = 'https://mochi.bz';
$apiKey = 'YOUR_API_KEY';
$apiSecret = 'YOUR_API_SECRET';
$query = http_build_query(
    ['merchant_order_id' => 'ORDER-20260919-001'],
    '',
    '&',
    PHP_QUERY_RFC3986
);
$signature = base64_encode(
    hash_hmac('sha256', $query, $apiSecret, true)
);

$ch = curl_init($baseUrl . '/api/v1/orders/query?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Mochi-Key: ' . $apiKey,
        'X-Mochi-Signature: ' . $signature
    ],
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_TIMEOUT => 30
]);

$json = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);

if ($json === false) {
    throw new RuntimeException($error);
}

// Preserve decimal JSON numbers as text before decoding.
$json = preg_replace(
    '/("(?:amount|base_pay_amount|pay_amount|received_amount|exchange_rate|rate_markup_percent|unique_amount_delta)"\s*:\s*)(-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)(?=\s*[,}])/',
    '$1"$2"', $json
);
$result = json_decode($json, true);
if ($httpCode < 200 || $httpCode >= 300 || empty($result['success'])) {
    throw new RuntimeException('MochiPay request failed. Review before retrying creation.');
}
?>

Campos da resposta de sucesso

The query returns wallet_typeenetwork separately; Create Order returns their combined payment_method. Compare them with the method saved on your local order. Return only necessary payment fields to the customer browser.

CampoTipo / tamanhoDescrição
order_idstring · 32MochiPay order identifier.
merchant_order_idstring · ≤100Your merchant order identifier.
sourcestring · ≤20Order source, such as API.
descriptionstring · ≤500Order description.
product_typestring · ≤20PHYSICAL ou DIGITAL_SERVICE.
product_infoJSON/string/nullProduct or cart information supplied when the order was created.
statusstring · ≤20Overall order payment status.
merchant_statusstring · ≤50Merchant-facing order status.
amountdecimal(28,8)Original order amount.
currencystring · ≤20Original order currency, such as USD, EUR, USDT ou USDC.
base_pay_amountdecimal(28,8)Converted payment amount before the unique matching adjustment.
unique_amount_deltadecimal(28,8)Small signed amount added to or subtracted from the base amount.
unique_amount_directionstring · ≤10UP ou DOWN.
pay_amountdecimal(28,8)Exact cryptocurrency amount the customer must pay.
received_amountdecimal(28,8)Cryptocurrency amount received so far.
exchange_ratedecimal(38,18)Exchange-rate snapshot used when the order was created.
rate_markup_percentdecimal(9,4)Merchant rate markup snapshot used for the order.
wallet_typestring · ≤20Ativo de pagamento: USDT, USDC, BTC, ETH ou SOL.
networkstring · ≤30Blockchain network, such as TRC20 ou ERC20.
payment_addressstring · ≤255Merchant receiving address selected for this order.
tx_hashstring/null · ≤255Detected customer payment transaction hash.
confirmationsintegerCurrent blockchain confirmation count.
customer_email … postal_codestring/nullOptional customer and shipping fields supplied at order creation.
payment_urlstring · URLHPP checkout URL; on-site integrations query the same order for status and payment instructions.
expires_atdatetimeOrder expiration time.
paid_atdatetime/nullPayment completion time.
created_atdatetimeOrder creation time.
updated_atdatetimeLast order update time.

Exemplos de código

PHP, Node.js, Python, C# / .NET Framework, Java, iOS Swift e Android Kotlin. Um pagamento salvo suporta ON_SITE e HPP.

Escolha o código-fonte para seu aplicativo

Um ZIP atual por linguagem ou plataforma mobile, com instruções em inglês. Os plugins de loja continuam separados e as integrações existentes funcionam.

DEMO DE SERVIDOR · ON_SITE + HPP

PHP

7.0–8.4

Rotas PHP originais: order.php, checkout.php e callback.php

Baixar ZIP
DEMO DE SERVIDOR · ON_SITE + HPP

Node.js

22+

Rotas comuns de servidor e mobile

Baixar ZIP
DEMO DE SERVIDOR · ON_SITE + HPP

Python

3.10+

Rotas comuns de servidor e mobile

Baixar ZIP
DEMO DE SERVIDOR · ON_SITE + HPP

C# / .NET Framework

4.6.1 / VS2019

Rotas comuns de servidor e mobile

Baixar ZIP
DEMO DE SERVIDOR · ON_SITE + HPP

Java

JDK17+

Rotas comuns de servidor e mobile

Baixar ZIP
CÓDIGO MOBILE · ON_SITE + HPP

iOS Swift

iOS15+ / Xcode14+

Use um servidor comum; somente projeto-fonte

Baixar ZIP
CÓDIGO MOBILE · ON_SITE + HPP

Android Kotlin

API26+ / SDK35 / JDK17

Use um servidor comum; somente projeto-fonte

Baixar ZIP

Execute o fluxo completo do servidor

  1. Configure privadamente credenciais MochiPay, carteiras ativas, origem HTTPS pública do callback e token de testes independente. O servidor define o preço; o navegador não pode alterá-lo.
  2. Crie ou recupere com o mesmo request_id salvo e conteúdo original. Assine os bytes UTF-8 exatos e consultas codificadas com HMAC-SHA256.
  3. Abra o popup ON_SITE salvo ou o redirect HPP; ambos usam o mesmo pedido. ON_SITE inclui QR, cópia e seletor de dez idiomas.
  4. Processe notify_url no servidor e consulte o ID salvo. Retorno síncrono e sondagem usam a mesma verificação de vínculo e valor exato.
  5. Registre o pagamento verificado uma vez. Antes da produção, substitua arquivos e marcadores de testes por autorização do usuário e atualização atômica no banco.

PHP mantém order.php / checkout.php / callback.php. Os outros quatro servidores expõem as rotas comuns abaixo para navegador e mobile.

RotaResponsabilidade
POST /paymentsCria ou recupera item com preço do servidor; request_id, payment_method e token bearer de testes.
GET /checkout?r=…&t=…&mode=ON_SITEPopup local do lojista para o pedido salvo.
GET /checkout?…&mode=HPPRedirect 303 após validar vínculo e destino.
GET /status?r=…&t=…Consulta assinada ao MochiPay; DTO mínimo com valores em strings decimais.
POST /callback?r=…&t=…Verificação assíncrona e marcador único de pagamento.
GET /complete?r=…&t=…Página de retorno síncrono com resultado verificado.

Pagamento mobile sem segredos API no celular

Swift e Kotlin usam qualquer um dos quatro servidores comuns. Configure apenas a origem HTTPS do lojista no app. ON_SITE exibe checkout local em WKWebView ou Android WebView; HPP abre a rota de redirect em navegador externo. O app consulta ao voltar à atividade; fechá-lo não interrompe notificações do servidor.

O ID salvo persiste em novas tentativas/reinícios. Mudanças de interface e idioma reutilizam o pedido. O token de testes é separado das credenciais MochiPay; substitua pela sessão autenticada do seu app.

São exemplos de integração, não SDKs nativos ou aprovações de lojas de apps. Consulte as atuaisregras de cobrança da Appleepolíticas de pagamentos do Google Playpara seu produto e região.

Verifique antes de publicar

Siga README e TESTING.md de cada pacote. Testes locais assinados cobrem novas tentativas, vínculos incorretos, estados não pagos e notificações duplicadas. Valide em staging com Xcode/Android Studio, dispositivos e um pequeno pagamento real. Não exige novas tabelas MochiPay nem reinstalação de plugins.

Implementar retornos síncronos e notificações assíncronas →

Retornos e notificações

Um mesmo verificador no servidor trata retornos síncronos HPP, notificações assíncronas HPP e atualizações ON_SITE.

Entradas diferentes. Uma atualização de pedido verificada.

FluxoCampo API / entradaFinalidade
Retorno síncrono HPPredirect_url · GET do navegadorExibe resultado após consulta assinada no servidor. O cliente pode não retornar.
Notificação assíncrona HPPnotify_url · POST do servidorVerifica e atualiza o pedido local sem depender do navegador.
Notificação assíncrona ON_SITEO mesmo notify_url · POST do servidorAtualiza o pedido mesmo com popup ou app fechado.
Estado ON_SITENavegador/app consulta /status do lojistaExibe somente o resultado mínimo da mesma verificação do servidor.

HPP: retorno síncrono do navegador

Ao criar, salve redirect_url com o token do pedido local. O exemplo usa HTTPS /complete?r=…&t=…. Após checkout hospedado, carregue o pedido, valide proprietário/token e assine Query Order com o order_id MochiPay salvo.

Mostre PAID somente após validar vínculo e valor recebido exato; caso contrário, aguarde ou revise. URL, mensagem do navegador ou captura não comprovam pagamento. O callback pode chegar antes ou depois do retorno.

HPP e ON_SITE: notificação assíncrona ao servidor

Salve notify_url na criação; exemplos usam /callback?r=…&t=…. MochiPay envia POST independentemente do navegador. Os dados recebidos são apenas pistas de busca. Consulte a API autenticada e compare ID, referência, valor/moeda original, ativo/rede, endereço e valor exato salvos.

Exija PAID e received_amount exatamente igual a pay_amount. Registre atomicamente uma vez; notificações válidas repetidas retornam OK sem atualizar ou entregar duas vezes. Estados não confirmados, vínculos inválidos e falhas de consulta/armazenamento não devem ser reconhecidos como pagamento concluído.

Os exemplos salvam marcador único paid_verified. Substitua por transação no banco de pedidos; não entrega produtos. Somente o corpo do callback nunca atualiza um pedido.

ON_SITE: atualizações assíncronas e sondagem do popup

ON_SITE usa o mesmo notify_url e continua verificando com popup fechado ou app offline. Enquanto visível, consulta apenas seu servidor autorizado a cada 15 segundos. O servidor consulta MochiPay e retorna campos mínimos com valores decimais em texto. PAID usa o mesmo verificador do callback; segredos API e dados completos do cliente não chegam ao navegador.

Fechar, reabrir ou mudar ON_SITE/HPP reutiliza o pagamento salvo. Mantenha request_id e conteúdo exato após timeout; mudar a referência pode criar outro pedido.

Código executável em cada pacote de servidor

Cada exemplo inclui ambos os modos, notificação, retorno, status seguro e tentativa persistida. notify_url e redirect_url são campos API; o modo é escolhido localmente, não em Create Order.

Node.js · verificação, retorno e notificação

Trechos do pacote executável. Variáveis de rotas e auxiliares de armazenamento estão no código completo; use a integração completa.

async function verify(r,t){const a=load(r);if(!equal(a.token,t)||!a.snapshot)throw Error('Invalid payment capability');const d=await api('/api/v1/orders/query','order_id='+encodeURIComponent(a.snapshot.order_id));bind(a,d);if(d.status==='PAID'&&!a.paid_verified){a.paid_verified=true;save(r,a)}return d}

// HPP redirect_url -> GET /complete: verify before displaying result.
await verify(r,t);
// notify_url -> POST /callback: same verification and atomic once-only marker.
const d=await verify(r,t);
output(res,d.status==='PAID'?200:409,'text/plain',d.status==='PAID'?'OK':'Payment not confirmed');
// ON_SITE polling -> GET /status: only the safe DTO reaches the browser.
json(res,200,{success:true,data:safe(await verify(r,t))});
Python · verificação, retorno e notificação

Trechos do pacote executável. Variáveis de rotas e auxiliares de armazenamento estão no código completo; use a integração completa.

def verify(r, t):
    a = load(r)
    if not isinstance(t,str) or not hmac.compare_digest(a['token'],t) or not a.get('snapshot'): raise ValueError('Invalid capability')
    d = api('/api/v1/orders/query',urlencode({'order_id':a['snapshot']['order_id']})); bind(a,d)
    if d.get('status') == 'PAID' and not a['paid_verified']: a['paid_verified'] = True; save(r,a)
    return d

# HPP browser return
verify(r,t)
# HPP and ON_SITE server notification (inside the handler lock)
d = verify(r,t)
self.out(200 if d['status']=='PAID' else 409,'text/plain','OK' if d['status']=='PAID' else 'Payment not confirmed')
# ON_SITE display only
self.jout(200,dict(success=True,data=safe(verify(r,t))))
C# / .NET Framework · verificação, retorno e notificação

Trechos do pacote executável. Variáveis de rotas e auxiliares de armazenamento estão no código completo; use a integração completa.

        static JObject Verify(string r,string t)
        {
            var a=Load(r);if(!Equal(S(a,"token"),t)||a["snapshot"]==null)throw new Exception("Invalid capability");var d=Api("/api/v1/orders/query",null,"order_id="+Uri.EscapeDataString(S(a["snapshot"],"order_id")));Bind(a,d);
            if(S(d,"status")=="PAID"&&!(bool)a["paid_verified"]){a["paid_verified"]=true;Save(r,a);}return d;
        }

// GET /complete: verified HPP return.
Verify(r,t);
// POST /callback: asynchronous notification for both modes.
var d=Verify(r,t);
Out(res,S(d,"status")=="PAID"?200:409,"text/plain",S(d,"status")=="PAID"?"OK":"Payment not confirmed");
// GET /status: display only the minimal DTO.
JOut(res,200,new JObject {{"success",true},{"data",Safe(Verify(r,t))}});
Java · verificação, retorno e notificação

Trechos do pacote executável. Variáveis de rotas e auxiliares de armazenamento estão no código completo; use a integração completa.

    static JsonObject verify(String r,String t)throws Exception{JsonObject a=load(r);if(!equal(s(a,"token"),t)||!a.has("snapshot"))throw new IllegalArgumentException("Invalid capability");JsonObject d=api("/api/v1/orders/query",null,"order_id="+enc(s(a.getAsJsonObject("snapshot"),"order_id")));bind(a,d);if(s(d,"status").equals("PAID")&&!a.get("paid_verified").getAsBoolean()){a.addProperty("paid_verified",true);save(r,a);}return d;}

// GET /complete: verified HPP return.
verify(r,t);
// POST /callback: both presentation modes use this route.
boolean paid=s(verify(r,t),"status").equals("PAID");
out(x,paid?200:409,"text/plain",paid?"OK":"Payment not confirmed");
// GET /status: minimal safe display DTO.
jout(x,200,object("success",true,"data",safe(verify(r,t))));
PHP · verificação, retorno e notificação

Trechos do pacote executável. Variáveis de rotas e auxiliares de armazenamento estão no código completo; use a integração completa.

    // Authenticate the result by querying MochiPay server-to-server.
    $verified = mochipay_query_order('order_id', $orderId);
    if (!$verified['ok'] || !is_array($verified['data'])) {
        callback_text(503, 'VERIFICATION_FAILED');
    }

    $order = $verified['data'];
    if (!isset($order['order_id']) || !hash_equals((string) $order['order_id'], $orderId)) {
        callback_text(409, 'ORDER_MISMATCH');
    }

    $verifiedMerchantId = isset($order['merchant_order_id']) ? (string)$order['merchant_order_id'] : '';
    try { $record = mochipay_load($verifiedMerchantId); }
    catch (Exception $e) { callback_text(503, 'LOCAL_STORAGE_UNAVAILABLE'); }
    if (!mochipay_bound($record, $order) || (isset($callback['merchant_order_id']) && !hash_equals($verifiedMerchantId, (string)$callback['merchant_order_id']))) callback_text(409, 'LOCAL_ORDER_MISMATCH');
    if (!isset($order['received_amount']) || MochiPayPortable::decimal($order['received_amount']) !== MochiPayPortable::decimal($order['pay_amount'])) callback_text(409, 'PAYMENT_AMOUNT_REQUIRES_REVIEW');

    if (!isset($order['status']) || strtoupper((string) $order['status']) !== 'PAID') {
        callback_text(409, 'ORDER_NOT_PAID');
    }

    /*
     * TODO: In your production database, atomically fulfill the bound local order.
     * This demo acknowledges verification only; it does not deliver goods.
     * Make the operation idempotent: repeated callbacks must not deliver goods
     * or credit the customer more than once.
     */
    try { mochipay_record_verified($record, $order); }
    catch (Exception $e) { callback_text(503, 'LOCAL_UPDATE_FAILED'); }
    callback_text(200, 'OK');
}

// GET browser return verifies the saved capability, then queries the saved ID.
$authorized = $record && $returnToken !== '' && hash_equals($record['token'], $returnToken);
if ($authorized) {
    $verified = mochipay_query_order('order_id', $record['snapshot']['order_id']);
    $paid = $verified['ok'] && mochipay_record_verified($record, $verified['data']);
}
Baixar exemplos completos

Respostas de erro

Errors return an HTTP status code and a stable machine-readable message.

JSON
{ "success": false, "message": "INVALID_SIGNATURE" }
HTTPMensagemDescrição
400INVALID_JSON / INVALID_AMOUNTRequest data is invalid.
400INVALID_CURRENCY / INVALID_PAYMENT_METHODCurrency or payment method is unsupported.
400INVALID_UNIQUE_AMOUNT_DIRECTION / INVALID_PRODUCT_TYPEThe direction or product-type value is unsupported.
400FIELD_TOO_LONG / INVALID_REDIRECT_URL / INVALID_NOTIFY_URLAn optional field exceeds its limit or a supplied URL is invalid.
400ORDER_ID_REQUIRED / ORDER_IDENTIFIER_CONFLICTQuery identifier is missing or conflicting.
401INVALID_API_KEY / INVALID_SIGNATUREFalha na autenticação.
403SUBSCRIPTION_REQUIRED / SUBSCRIPTION_EXPIREDMerchant subscription is unavailable.
403MERCHANT_DISABLEDMerchant account is disabled.
404ORDER_NOT_FOUNDNo matching merchant-owned order was found.
500SYSTEM_ERRORThe request could not be completed.

Integração de lojas SaaS clássicas

HPP-only compatibility for Shopyy / Shopoem, Shoplus, Wooshoppaas and Fecify. No plugin download or SaaS source-code change is required.

POST https://mochi.bz/api/v/orders/legacy_create/{MerchantApiKey}/{PaymentMethod}
Use the API key, never the API secret, in this URL. The URL identifies the merchant and payment method. The SaaS platform continues to send its existing application/x-www-form-urlencoded order fields.

Plataformas aceitas

Shopyy / ShopoemSame company and compatible gateway format
ShoplusConfigure the payment interface URL
WooshoppaasConfigure the payment interface URL
FecifyConfigure the payment interface URL

Configuração

  1. Copy the merchant API key from the MochiPay merchant dashboard.
  2. Choose one supported payment method for this SaaS payment option.
  3. Substituir {MerchantApiKey}e{PaymentMethod} in the endpoint URL.
  4. Paste the completed URL into the SaaS payment gateway's interface or submit URL setting.
  5. Keep the SaaS platform's existing POST parameters, return URL and notify URL unchanged.

Exemplos de URL

LEGACY PAYMENT INTERFACE URL
https://mochi.bz/api/v/orders/legacy_create/YOUR_MERCHANT_API_KEY/USDT_TRC20

https://mochi.bz/api/v/orders/legacy_create/YOUR_MERCHANT_API_KEY/USDC_ERC20

https://mochi.bz/api/v/orders/legacy_create/YOUR_MERCHANT_API_KEY/SOL_SOLANA

MÉTODOS DE PAGAMENTO

USDT_TRC20USDT on TRON
USDC_ERC20USDC on Ethereum
BTC_BITCOINNative BTC on Bitcoin
ETH_ERC20Native ETH on Ethereum
SOL_SOLANANative SOL on Solana

Campos obrigatórios do formato legado

ParâmetroFinalidade
merchant_urlOriginal SaaS store value, retained in the complete request record for diagnostics.
system_nameExisting SaaS platform identifier, retained in the complete request record.
account_type / payment_modeKeep the platform's existing values, normally liveesale.
orders_idOriginal SaaS order identifier.
amount / currencyOriginal order amount and currency.
return_urlCustomer return URL after confirmed payment.
notify_urlServer notification URL for the completed payment.
securityTokenOptional passthrough token returned unchanged.
productsOptional product or cart data.
customer_*Existing customer, address, IP and user-agent fields.

Resposta de criação do pedido

The existing SaaS integration extracts the hosted checkout URL from the three-part plain-text response.

TEXT
_____https://mochi.bz/pay/ORDER_ID_____

Successful return and notification fields

CampoValor
securityTokenThe original passthrough value.
paymentMethodonlinepay
paymentStatusCompleted
paymentTransactionThe confirmed blockchain transaction hash.
paymentCommentsMochiPay payment confirmed
orderIDThe original SaaS orders_id.

Downloads de plugins de comércio

Escolha um dos 19 ZIPs independentes conforme loja, versão e PHP. Cada ZIP inclui instruções em inglês e requisitos PHP. Use o ambiente permitido pela loja.

ON-SITE + HPP

WooCommerce

Classic Checkout, Checkout Blocks e HPOS.

PlataformaWooCommerce 5.8 ou posterior com API nativa de gateway
PHPPHP 7.4–8.4

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

OpenCart 2.0–2.2

Rotas de pagamento antigas e modelos específicos por versão.

PlataformaOpenCart 2.0.x-2.2.x
PHPPHP 5.6–7.4; versões posteriores exigem patches do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

OpenCart 2.3

Estrutura extension/payment separada do 2.3.

PlataformaOpenCart 2.3.x
PHPPHP 5.6–7.4; versões posteriores exigem patches do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

OpenCart 3

Views Twig e gateway nativo OpenCart 3.

PlataformaOpenCart 3.0.x
PHPPHP 5.6–8.4; cumpra os requisitos exatos do núcleo e dependências

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

OpenCart 4

Namespaces, rotas e pacotes nativos do 4.x.

PlataformaOpenCart 4.0.2.x-4.1.x
PHPPHP 8.0.2–8.4; 4.1.0.4 exige 8.1+

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Zen Cart 1.5.3–1.5.7

Arquivos de idioma legados baseados em define e estados nativos.

PlataformaZen Cart 1.5.3-1.5.7
PHPPHP 5.6–8.0, conforme a versão do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Zen Cart 1.5.8–2.2

Arquivos de idioma modernos baseados em arrays e estados nativos.

PlataformaZen Cart 1.5.8 / 2.0.x / 2.1.x / 2.2.x
PHPPHP 7.3–8.4, conforme a versão do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Magento 1 / OpenMage

Magento CE 1.9.3.0–1.9.4.5 e OpenMage 19/20 compatível.

PlataformaMagento CE 1.9.3.0-1.9.4.5; API M1 nativa do OpenMage 19/20
PHPPHP 5.6–8.4; PHP 8 exige OpenMage compatível

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Magento 2

Magento Open Source 2.3.7–2.4.8 com checkout nativo.

PlataformaMagento Open Source 2.3.7-2.4.8 com checkout nativo
PHPPHP 7.3–8.4, conforme a versão do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

PrestaShop 1.6

Hook de pagamento e formulário do PrestaShop 1.6.1.

PlataformaPrestaShop 1.6.1.x
PHPPHP 5.6–7.1

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

PrestaShop 1.7 / 8 / 9

PrestaShop 1.7.6–1.7.8, 8.x e 9.0.x com paymentOptions.

PlataformaPrestaShop 1.7.6-1.7.8 / 8.x / 9.0.x
PHPPHP 5.6–8.4, conforme a versão do núcleo

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Shopware 6.6

Controladores nativos separados para Shopware 6.6 e 6.7.

PlataformaShopware >=6.6.10.0 <6.7.0.0
PHPPHP 8.2.x / 8.3.x / 8.4.x

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Shopware 6.7

Controladores nativos separados para Shopware 6.6 e 6.7.

PlataformaShopware >=6.7.0.0 <6.8.0.0
PHPPHP 8.2.x / 8.3.x / 8.4.x

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Drupal Commerce

Gateway Commerce nativo para as versões compatíveis de Drupal e Commerce.

PlataformaCommerce 2.40.x with Drupal 9.3–10.x; or Commerce 3.3.10+ <3.4 with Drupal 10.3–11.x
PHPDrupal 9.3–9.5: PHP 7.4–8.1; Drupal 10: PHP 8.1–8.3; Drupal 11: PHP 8.3–8.4, somente se permitido pela versão exata do Drupal

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

EC-CUBE 4.3

Checkout JPY nativo com o fluxo de compra EC-CUBE.

PlataformaEC-CUBE >=4.3.0 <4.4.0
PHPPHP 8.1.x / 8.2.x / 8.3.x

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Bagisto 2.3

Pacote Laravel com pedidos e faturas nativos.

PlataformaBagisto >=2.3.0 <2.4.0
PHPPHP 8.2.x / 8.3.x / 8.4.x (cumpra também as dependências travadas da loja)

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

Sylius 2.0

Checkout Payum nativo e estados de pagamento Sylius.

PlataformaSylius >=2.0.0 <2.1.0 with PayumBundle 2.6+ / Payum 1.7-compatible core
PHPPHP 8.2.x / 8.3.x / 8.4.x (cumpra também as dependências travadas da loja)

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

osCommerce 4.14

Módulo nativo V4; separado do osCommerce legado 2.x e 3.x.

PlataformaosCommerce 4.14.x; API nativa do módulo orderPayment V4
PHPPHP 7.4.x–8.3.x, conforme o osCommerce instalado e suas dependências travadas

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →
ON-SITE + HPP

thirty bees 1.6

Módulo de pagamento e histórico nativos do thirty bees 1.6.

Plataformathirty bees >=1.6.0 <1.7.0
PHPPHP 7.4.x / 8.0.x / 8.1.x / 8.2.x / 8.3.x; use a distribuição correspondente do thirty bees

Instruções em inglês e tabela PHP detalhada dentro do ZIP.

Baixar ZIPGuia de configuração →

Novos adaptadores são versões iniciais. Teste instalação e pagamentos reais em staging antes de usar em produção.

Comece a desenvolver com MochiPay

Crie uma conta e escolha a integração adequada.

Começar