MobilePay Gateway

Let clients pay BAMCS invoices with MobilePay, the Nordic mobile wallet (Vipps MobilePay).

The client is sent to MobilePay, approves the payment in the app and comes back to the invoice. BAMCS captures the payment and marks the invoice paid automatically.

Features

Pay an invoice

• MobilePay is offered at checkout and on the invoice payment page for invoices in DKK, EUR or NOK.
• The amount is always the invoice's outstanding balance, so a tampered request can't underpay.
• The invoice lines are sent along, so the client sees what they are paying for.
• After approving, the client returns to a page that waits for the payment to be confirmed and then shows the paid invoice.

Capture and settlement

• When MobilePay reports a payment as authorized, BAMCS captures it right away and records the transaction.
• Safety checks before capturing:
  • An invoice that is already paid, cancelled or refunded is never captured.
  • A capture is only recorded if MobilePay captured exactly the amount and currency that were requested. Otherwise staff are alerted to check it by hand.
  • A repeated callback is recognised and never recorded twice.
• Expired or cancelled payments are recorded as failed, and the invoice stays open.
• Fees: the transaction fee is calculated from your percentage and fixed fee settings, so your reports show the gross amount, the fee and the net amount.

Refunds

• Full and partial refunds are made from the invoice in the BAMCS admin area and sent to MobilePay.
• If the payment was taken in another currency than the invoice's, the refund returns the same share of the original charge. A full refund returns exactly what the client paid, whatever the exchange rate does in between.

Security

• Every callback must carry a valid X-MobilePay-Signature, an HMAC-SHA256 signature made with your API secret. Unsigned or wrongly signed callbacks are rejected.
• The callback URL is rate limited.
• The API key and API secret are stored encrypted.

Requirements

• API credentials (an API key and an API secret) for the MobilePay payment API the module connects to. By default that is https://mobilepay.insertname.dk/api/v1.
• The API provider must send its callbacks to your BAMCS callback URL (see Step 2 below). The module doesn't pass this URL along with each payment.
• Your BAMCS installation reachable over public HTTPS, so callbacks can reach it.
• The BAMCS queue worker running. Invoices are marked paid by a background job.
• Exchange rates set up in BAMCS whenever an invoice currency differs from the module's default currency.

Installation

1. In BAMCS, go to Modules → Marketplace and install MobilePay Gateway. Alternatively, upload the module .zip under Upload a module package.
2. Under Installed Modules, click Activate. This creates the module's database table and its default settings.
3. Open Modules → MobilePay → Settings.

Configuration

Settings

Secret fields are never shown again after saving. Leave a secret field blank to keep its current value.

Step 1: Credentials

Enter your API Key and API Key Secret. If your provider gave you a different API address, change API Base URL too. Keep Sandbox Mode on until a test payment has gone through.

Step 2: Callback URL

Ask your MobilePay API provider to send payment status callbacks to:

https://<your-domain>/modules/mobilepay/callback

The callbacks must be signed with your API secret in the X-MobilePay-Signature header. BAMCS acts on these statuses:

Other statuses are acknowledged and ignored.

Step 3: Fees and currency

1. Set Transaction Fee (%) and Transaction Fee (fixed) to match your MobilePay agreement. They only affect the fee BAMCS records on each payment.
2. Choose the Default currency that payments should be taken in.

Step 4: Go live

1. With Sandbox Mode on, pay an invoice end to end.
2. Check that the invoice turns Paid.
3. Turn Sandbox Mode off.

Limitations

• No automatic charging or saved payment methods. MobilePay is a pay-by-link method. Invoices are paid by following the payment link, and clients whose invoices should be charged automatically need a card gateway.
• Payments are always taken in the default currency. An invoice in another supported currency is converted at the BAMCS exchange rate before the client pays.
• Recorded fees are estimates. They come from your settings, not from MobilePay's statement.
• Refunds made outside BAMCS are not synced. Refund from the invoice in BAMCS so both sides match.
• No connection check. BAMCS's hourly integration check doesn't cover MobilePay, so wrong credentials only show up when a client tries to pay.
• The Enable MobilePay setting currently has no effect. MobilePay is offered while the module is active. Deactivate the module under Modules to hide it.