ForumPay

Global cryptocurrency payment gateway. Supports Pay-In and Pay-Out in BTC, ETH, USDT, and other cryptocurrencies configured in your ForumPay account.

Operations: Pay-In ✓ | Pay-Out ✓ | Webhook ✓
Processing: Asynchronous - redirect user to hosted page; final status via webhook

Fields marked with * are required.

Configuration (Mozarto back office)

Field	Description
`username` *	ForumPay API username
`password` *	ForumPay API password
`forumpayUserId` *	Your ForumPay user/payer identifier - omitting this field causes ForumPay to reject all requests with "Payer ID is required"
`webhookUrl` *	Your HTTPS endpoint for transaction status updates
`isWebhookSecured`	Adds `Authorization` header to outbound webhook calls

Pay-In

POST /v1/api/mozarto/cashier

Required header: x-user-token: Bearer <user-jwt> must be sent with every Pay-In request. The value must be a valid decodable JWT - passing a plain string causes a timeout. See Authentication.

Request body

Field	Type	Description
`pspType` *	string	Always `"FORUMPAY"`
`type` *	string	Always `"PAYIN"`
`baseamount` *	number	Amount as a number (e.g. `100.00`)
`currency` *	string	Fiat currency (e.g. `"EUR"`, `"USD"`)
`userId` *	string	Your internal user/player identifier
`email` *	string	User's email address
`country` *	string	User's country code (e.g. `"DE"`)
`brandId`	string	Brand identifier for multi-brand setups

Example request

{
  "pspType": "FORUMPAY",
  "type": "PAYIN",
  "baseamount": 100.00,
  "currency": "EUR",
  "userId": "user_123",
  "email": "player@example.com",
  "country": "DE"
}

Response

{
  "status": "success",
  "isSuccess": true,
  "data": {
    "status": "PENDING",
    "url": "https://pay.forumpay.com/invoice/abc123xyz",
    "sessionId": "60a74038-5b94-427e-8cff-abc123"
  }
}

Open data.url in the user's browser. The user selects their cryptocurrency and completes payment on ForumPay's hosted page.

Pay-Out

POST /v1/api/mozarto/cashier

Required header: x-user-token: Bearer <user-jwt> must be sent with every Pay-Out request. The value must be a valid decodable JWT. See Authentication.

Request body

Field	Type	Description
`pspType` *	string	Always `"FORUMPAY"`
`type` *	string	Always `"PAYOUT"`
`baseamount` *	number	Pay-Out amount as a number (e.g. `200.00`)
`currency` *	string	Fiat currency the amount is denominated in
`userId` *	string	Your internal user/player identifier
`email` *	string	User's email address
`country` *	string	User's country code
`preferredCrypto` *	string	Cryptocurrency to send - e.g. `"BTC"`, `"ETH"`, `"USDT"`, `"LTC"`
`walletAddress` *	string	Destination wallet address for the chosen cryptocurrency
`brandId`	string	Brand identifier

Example request

{
  "pspType": "FORUMPAY",
  "type": "PAYOUT",
  "baseamount": 200.00,
  "currency": "EUR",
  "userId": "user_123",
  "email": "player@example.com",
  "country": "DE",
  "preferredCrypto": "BTC",
  "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}

Response

{
  "status": "success",
  "message": "Transaction is on hold",
  "isSuccess": true,
  "data": {
    "invoice_currency": "EUR",
    "invoice_amount": "10.00",
    "currency": "BTC",
    "payment_source": "cash",
    "wait_time": "20 minutes",
    "network_processing_fee": "0.00000966",
    "rate": "65419.3380",
    "amount_exchange": "0.00015286",
    "amount": 10,
    "fast_transaction_fee": "0.00002066",
    "fast_transaction_fee_currency": "BTC/kB",
    "payment_id": "badd0b52-110f-4be2-af64-59d7645796af",
    "reference_no": "69f332c3f6abfbeab46f98db",
    "address": "btc-1eda64a85da94d71a2ac5ed84e929553",
    "access_token": "<forumpay-access-token>",
    "transactionId": "69f332c3f6abfbeab46f98db",
    "merchantReference": ""
  }
}

Field	Description
`data.transactionId`	Mozarto transaction ID - use for status queries
`data.payment_id`	ForumPay internal payment identifier
`data.reference_no`	ForumPay reference number - matches `transactionId`
`data.invoice_currency`	The fiat currency of the original request
`data.invoice_amount`	The fiat amount as a string
`data.currency`	The cryptocurrency being sent (e.g. `"BTC"`)
`data.rate`	Exchange rate at time of transaction creation
`data.amount_exchange`	Equivalent crypto amount to be transferred
`data.network_processing_fee`	Blockchain network fee in crypto
`data.fast_transaction_fee`	Optional fast transaction fee
`data.wait_time`	Estimated processing time
`data.address`	ForumPay internal payout address reference
`data.access_token`	ForumPay session token - do not expose to end users
`data.transaction_status`	Always `"Pending"` on creation

"Transaction is on hold": A message of "Transaction is on hold" with isSuccess: true means the payout was created successfully but requires manual approval in the Mozarto back office before ForumPay processes the transfer. Do not treat this as a failure. Show the user a "pending approval" message and wait for the webhook to deliver the final outcome (SUCCESS or REJECTED).

Webhook

Mozarto calls your webhookUrl when the transaction state becomes confirmed or cancelled.

The method field in the webhook payload will be FORUMPAY_PAYIN or FORUMPAY_PAYOUT.

Note on duplicates: ForumPay may deliver multiple webhook callbacks for the same transaction. Implement idempotency on your side - check the current state of the transaction before applying any changes. See Webhook Setup.

Error codes

ForumPay transport failures are mapped to normalized Mozarto errorCode values. Use errorCode for programmatic handling rather than parsing raw data.err strings.

Mozarto `errorCode`	PSP raw signal	When
`PSP_NOT_CONFIGURED`	Missing credentials in Mozarto back office	`username`, `password`, or `forumpayUserId` not set for this company
`INVALID_PSP_CREDENTIALS`	HTTP 401 / 403, or body contains `"Unauthorized"` or `"Invalid credentials"`	API credentials are wrong or expired
`PSP_NOT_CONFIGURED`	Body contains `"Payer ID is required"`	`forumpayUserId` is missing from the ForumPay configuration
`PSP_TIMEOUT`	HTTP 408, or response body contains `"timeout"`	ForumPay did not respond in time - safe to retry
`PSP_UNAVAILABLE`	HTTP 5xx	ForumPay service error - safe to retry with backoff
`PSP_RATE_LIMITED`	HTTP 429	Too many requests - retry after a delay
`UNKNOWN_PSP_ERROR`	HTTP 200 with `data.err` or `data.err_code` set	ForumPay returned a business-level rejection (e.g. invalid wallet address, unsupported currency pair) - check `data.err` and `data.err_code` for the raw ForumPay reason
`UNKNOWN_PSP_ERROR`	Any other unrecognised response	Fallback - check `data` for the raw ForumPay response and contact support if it persists

Business rejections: ForumPay may return HTTP 200 with data.err and data.err_code fields set when a transaction is rejected at the application layer (for example, an unsupported cryptocurrency or an invalid wallet address). These produce UNKNOWN_PSP_ERROR because the HTTP status is not available at that boundary. Inspect data.err_code for the ForumPay-specific reason.

For the full list of errorCode values and retryability guidance, see Errors.

Configuration (Mozarto back office)#

Pay-In#

Request body#

Example request#

Response#

Pay-Out#

Request body#

Example request#

Response#

Webhook#

Error codes#

Configuration (Mozarto back office)

Pay-In

Request body

Example request

Response

Pay-Out

Request body

Example request

Response

Webhook

Error codes