Merchant API reference

MoneyPaga endpoint documentation.

Stable reference for merchant integrations using scoped rm_test_ or rm_live_ API keys.

Download OpenAPI JSON

API rules

Idempotency, pagination, and errors

Use Idempotency-Key on write requests to safely retry network failures. List endpoints accept limit and offset. Merchant-facing API errors use {"error":{"type","code","message","param","request_id"}}.

MethodPathPurposeScope
GET/v1/payment-links/{id}Get payment linkcharges:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/entitlements/checkCheck entitlement balancecustomers:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/customers/{id}Get customercustomers:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/orders/{id}/invoiceCreate invoice for orderinvoices:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/invoices/{id}Get invoiceinvoices:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/payments/{id}/refund-requestRequest payment refundrefunds:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/subscriptions/{id}Get subscriptionsubscriptions:read. Errors use {error:{type,code,message,param,request_id}}.
PATCH/v1/subscriptions/{id}Update subscriptionsubscriptions:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/productsList productsorders:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/checkout/sessions/{id}Get hosted checkout sessioncharges:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/payment-linksCreate payment linkcharges:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/payment-linksList payment linkscharges:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/products/{id}Get productorders:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/pricesList pricesorders:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/paymentsList paymentscharges:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/entitlements/consumeConsume entitlement unitscustomers:write. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/payment-links/{id}/cancelCancel payment linkcharges:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/invoicesList invoicesinvoices:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/chargesList chargescharges:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/charges/{id}Get chargecharges:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/portal/sessionsCreate customer portal sessioncustomers:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/invoices/{id}/pdfDownload invoice PDFinvoices:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/customersCreate customercustomers:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/customersList customerscustomers:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/checkout/sessionsCreate hosted checkout sessioncharges:write. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/subscriptionsCreate subscriptionsubscriptions:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/subscriptionsList subscriptionssubscriptions:read. Errors use {error:{type,code,message,param,request_id}}.
GET/merchant/dashboardManage webhook URL, event subscriptions, delivery history, and retrywebhooks:write. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/ordersCreate orderorders:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/ordersList ordersorders:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/orders/{id}Get orderorders:read. Errors use {error:{type,code,message,param,request_id}}.
POST/v1/invoices/{id}/chargeCreate or reuse invoice chargecharges:write. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/invoices/{id}/chargeGet invoice payment instructionscharges:read. Errors use {error:{type,code,message,param,request_id}}.
GET/v1/entitlementsList entitlementscustomers:read. Errors use {error:{type,code,message,param,request_id}}.

Webhooks

Events, subscriptions, and verification.

Configure an HTTPS URL, choose events in the merchant dashboard, and validate the HMAC signature before processing any event.

charge.paid

Payment provider confirmed a charge. Use this to unlock paid orders or subscriptions.

{"id":"evt_123","type":"charge.paid","livemode":false,"data":{"charge_id":"<uuid>","invoice_id":"<uuid>","amount_cents":55000,"currency":"BRL"}}

invoice.paid

Invoice is paid. Use this for receipt, access, or accounting updates.

{"id":"evt_124","type":"invoice.paid","livemode":false,"data":{"invoice_id":"<uuid>","status":"paid","paid_at":"2026-07-02T10:00:00Z"}}

subscription.active

Subscription is active after successful payment.

{"id":"evt_125","type":"subscription.active","livemode":false,"data":{"subscription_id":"<uuid>","customer_id":"<uuid>","status":"active"}}

refund_request.created

Customer requested a refund and it is waiting for merchant/admin review.

{"id":"evt_126","type":"refund_request.created","livemode":false,"data":{"refund_request_id":"<uuid>","payment_id":"<uuid>","status":"requested"}}

refund_request.approved

Refund request was approved for processing.

{"id":"evt_127","type":"refund_request.approved","livemode":false,"data":{"refund_request_id":"<uuid>","status":"approved"}}

refund_request.rejected

Refund request was rejected with an admin reason.

{"id":"evt_128","type":"refund_request.rejected","livemode":false,"data":{"refund_request_id":"<uuid>","status":"rejected","reason":"Not eligible"}}

refund_request.processed

Refund was processed and payment/refund state changed.

{"id":"evt_129","type":"refund_request.processed","livemode":false,"data":{"refund_request_id":"<uuid>","payment_id":"<uuid>","status":"processed","amount_cents":55000}}

merchant.webhook.test

Sandbox/test event sent from the merchant dashboard.

{"id":"evt_test","type":"merchant.webhook.test","livemode":false,"data":{"message":"MoneyPaga signed webhook test event."}}

Signature

Verify X-RM-Signature.

MoneyPaga sends X-RM-Signature: sha256=<hmac_sha256>. Compute HMAC-SHA256 over the raw request body using your webhook signing secret and compare it in constant time.

Node.js

const crypto = require("crypto");

function verifyMoneyPagaWebhook(rawBody, header, secret) {
  const received = String(header || "").replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Go

func verifyMoneyPagaWebhook(rawBody []byte, header, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	received := strings.TrimPrefix(header, "sha256=")
	return hmac.Equal([]byte(received), []byte(expected))
}

If signature verification fails, return 401/403 and do not change local state.