FAQ

Answers to common questions about integrating Moosyl: supported bank apps, API keys, sandbox testing, pricing, refunds and webhooks.

Getting started

How do I get started?

Create an account at moosyl.com, create Sandbox keys in the dashboard, and follow the Quickstart. You can build and test everything in the sandbox before your business is approved for Production.

Which bank apps are supported?

Bankily, Sedad, Masrvi, BimBank, BCI Pay and Amanty. Click is coming soon. One integration covers all of them, and you choose which ones to offer in Settings → Payment methods in the dashboard.

Which currency is supported?

MRU (Mauritanian ouguiya). Amounts are whole MRU.

Which SDKs are there?

Flutter and React Native for taking payments in your app
TypeScript for Node.js servers, including checkout sessions, subscriptions and webhook verification
Dart for Dart servers

From any other language, call the HTTP API directly. See the API reference.

The secret key creates payment requests, checkout sessions and subscriptions, and must stay on your server. The publishable key is safe to ship in your app and is what the Flutter and React Native SDKs use. See API Keys.

Can I test without real payments?

Yes. Keys from the Sandbox environment never move money. Use the test phone numbers to get completed and failed payments.

Payments

How do I know a payment succeeded?

From the webhook. Listen for payment-created and payment-updated and check that data.status is completed. The callbacks in the mobile SDKs are for updating your UI, not for fulfilling orders. See Webhooks.

Can I refund a payment?

Refunds aren't available through the API yet. Contact support@moosyl.com if you need to refund a customer.

How much does Moosyl cost?

1% per successful payment. There are no monthly or setup fees, and failed payments cost nothing. See pricing.

When do I get paid?

Payments are paid out to the bank account in your payout settings. You can follow each payout under Payouts in the dashboard.

Webhooks

Which events are sent?

payment-created: a payment was made. Check data.status: it can already be completed or failed, or still pending.
payment-updated: a payment's status changed, for example from pending to completed.
payment-request-created and payment-request-updated: a payment request was created, or a payment attempt on it failed.
subscription-created and subscription-updated: a subscription was created or changed status.

How do I verify a webhook?

Each webhook has a secret that you set when you create it. Moosyl signs the raw request body with HMAC-SHA256 and sends the signature in the x-webhook-signature header as sha256=<hex>. The TypeScript SDK checks it for you with constructWebhookEvent. See Webhooks.

What happens if my endpoint is down?

Moosyl retries after 1, 2, 4, 8, 16 and 32 minutes, so up to 7 attempts in total. Network errors, timeouts (30 seconds), 408, 429 and 5xx responses are retried. Other 4xx responses are not.

Can I receive the same event twice?

Yes, for example after a retry. Make your handler idempotent: the x-webhook-delivery-id header identifies each delivery, and fulfilling an order only once per transactionId also protects you.

Troubleshooting

The payment view doesn't load in my app

Check that you're using the publishable key from the same environment as the payment request.
Check that a payment request with that transactionId exists in that environment.
Update to the latest SDK version.

A bank app doesn't appear at checkout

Make sure it's turned on in Settings → Payment methods for the environment you're using. If it's on and still missing, contact support@moosyl.com.

Webhooks aren't arriving

The URL must be public and use HTTPS. For local development, use a tunnel such as ngrok.
The webhook must be created in the same environment as your keys and have the events you need selected.
Your endpoint must return a 2xx status. Other responses count as failures.