Notes

API version

Implementation notes

The payment window in websites and apps

The payment window is a page of its own, which the payer reaches by a redirect and leaves by one. Most problems come from trying to keep it inside something else.

Websites

Create the link on your server when the payer clicks Pay, never in the browser, as your API key must not reach it. Then redirect:

HTTP/1.1 303 See Other
Location: https://pay.gjold.com/q3z3amhrkmyrgk6i

or set window.location to the "url" in your page's script.

The window can't be put in an iframe: it sends Content-Security-Policy: frame-ancestors 'none' and X-Frame-Options: DENY, so browsers refuse to show it in one. A popup works, but browsers block popups that a click did not open, and Apple Pay and banking apps work best in a full tab.

When the payer has paid, the window redirects to your "successurl", as a plain GET with nothing added. Put the order in the URL, and treat the page as the place to say thank you, not as the proof of payment: see Orders and payment links.

Apps

Create the link on your server, as for a website, and open it in the system's browser view: SFSafariViewController on iOS, or a Custom Tab on Android. Both are the system browser, so Apple Pay, 3-D Secure, and the switch to a banking app or to MobilePay work without code of yours.

Avoid a WebView if you can. If you must use one:

  • Allow navigation to other domains, as 3-D Secure runs on the bank's site.
  • Open links to banking apps and to MobilePay yourself, with the system, as a WebView won't.
  • Don't inject JavaScript into it. Apple Pay is turned off in a WKWebView that runs scripts of yours through WKUserScript or evaluateJavaScript.

Back to the app

The payer leaves your app for the browser view, and perhaps for a banking app or MobilePay, and may not come back on their own:

  • Make your "successurl" a universal link on iOS, or an App Link on Android, so that it opens your app when it is installed, and a web page when it is not.
  • Ask your server for the order's state whenever your app comes back to the foreground, as the payer may have paid and closed the browser view, or finished in their default browser after a banking app sent them there.

Your server knows that the order is paid from seq, not from the app, so the app only has to ask it.

Language

The window takes its language from the link's "language", or else from the browser's Accept-Language. In an app whose language the user chose apart from the system's, send it as "language".