WebKit - Mini App Integration Guide

This guide explains how to integrate your system with the GoPay Mini App (WebKit) via Midtrans. It provides both frontend and backend implementation steps for obtaining user authorization and accessing GoPay APIs securely.

Quick Start

If you're unsure where to begin with integrating the GoPay Mini App SDK, follow the steps below for a smooth and successful setup:

  1. Onboard as a Merchant and activate GoPay
    Visit Midtrans and complete your merchant registration. (docs)

  2. Contact Midtrans Account Manager
    Provide your Merchant ID (found in the Midtrans dashboard) to receive your PoP ID. (docs)

  3. Complete the Mini App Detail Submission
    Please provide the following details during submission. (You may resubmit the form using the same link if you need to update any information.)

    1. Submit your production URL for domain whitelisting.

    2. List down any APIs or SDKs you plan to add to your Mini App.

    3. Request Consent Approval – Optional: If your website or application required the user information and permission listed below, you must first obtain user consent from GoPay:

      API/SDKDetails
      Get LocationDevice location
      Get System InfoSystem information
      Get CameraDevice camera
      Get ProfileMobile number, email, username

    4. Allowed Deeplink – Optional: If your Mini App redirects to a GoPay page, please provide a screenshot of the destination.

  4. UI/UX Guidelines
    These UI/UX Guidelines to be followed to ensure a secure, consistent, and user-friendly experience within the GoPay App. (docs)

  5. Contact GoPay
    Request Credentials: Before using any GoPay APIs, you must request credentials from GoPay which will be used as the Authorization Header when calling getAuthToken. These credentials will only be shared after the Mini App Deeplink has been provided. (docs)

  6. SDK Setup
    Install and Initialize SDK in Frontend. Note: you can't run this locally, please deploy and test on GoPay MiniApp.

    1. Include SDK Script: (docs)

      <script src="https://gwk.gopayapi.com/sdk/stable/gp-container.min.js"></script>
      
    2. Call Get Auth Code SDK: (docs )

      window.gpContainer.call(  
        "GPMiniAppAuth",  
        "getAuthCode",  
        {},  
        function(response) {  
          console.log('success:', response);  
        },  
        function(error) {  
          console.log('error:', error);  
        }  
      );
      

  7. Technical Specification
    These are the APIs and SDKs available.

    1. Use Auth Token to Call GoPay Backend APIs (docs)

      NameDescriptionMandatoryPrerequisite
      Get Auth TokenRetrieve user's access token for authenticationMAuthCode
      DisbursementSend GoPay coins to user's accountOAuthToken
      Create ReminderSet up a reminder for scheduled actionsOAuthToken
      Remove ReminderCancel a previously created reminderOAuthToken
      Push NotificationSend notifications to userOAuthToken
      Get ProfileRetrieve user's information such as mobile number, email, usernameOAuthToken
      ConsentApproval

    2. GoPay Frontend SDKs (docs)

    3. Integrate GoPay SNAP for Payments (docs)"
      Note: For mini apps, Midtrans payment deeplink is not supported, and a sandbox environment is not available.

      NameDescriptionMandatoryPrerequisite
      Get B2B Access TokenInitiate order with Super App Backend Merchant access token is needed for verification purposesOAuthToken
      Initiate Host to Host PaymentCreate Payment Deeplink with Super App backendOAuthToken
      Launch PaymentUse this SDK to automatically redirect users to the GoPay app to complete the payment, then return them to your Mini App.OAuthToken

Version History

VersionDescriptionGoPay App VersionDate
1.0GoPay APIs now use a public domain instead of requiring mTLS certificate setup.1.53 and below01/05/25
1.1Added Get Consent and Get Profile1.5424/06/25
2.0Replaced miniAppSDK JSBridge with gpContainer for all frontend JSAPI calls. (V4 Webview)
Added UI/UX Guidelines.
1.5702/07/25

Technical Assistant and Support

For any technical queries or clarifications, please contact the GoPay integration team via email: [email protected] or MiniApp Technical Support @Janson


FAQ

CategoryQuestionsAnswer
Most FrequentWhat is the overall E2E flow of the onboarding process. [Merchant side to]

- Register on Midtrans Portal
- Fill in the MiniApp submission form
- Send an email for credentials
[GoPay side to]
- Sales team to configure PoP ID
- MiniApp tech support to generate MiniApp using submission form
- MiniApp tech support to send credentials via Email
- MiniApp tech support to send MiniApp Deeplink
[Merchant side to]
- Setup FE getAuthCode
- Setup BE getAuthToken using the credentials as Authorization
- Call GoPay APIs using getAuthToken as Authorization (optional)
- Integrate Payments using b2b access token, host to host, and launchpayment (optional)
[GoPay side to]
- Rollout MiniApp once ready from business team
Why i'm getting errors when calling getAuthCodeMake sure you're calling getAuthCode correctly and call getAuthCode only after deploying the mini app, not when running locally. The SDK works as a bridge between the mini app and GoPay. If you run locally, there’s no mini app container for the SDK to connect to, so getAuthCode won’t work. You may use the MiniApp Deeplink provided by GoPay to test this.
What i must call getAuthTokengetAuthToken gives you token that will be used to call other GoPay BE APIs and user's account id. Make sure you get the credentials via Email to be used as the Authorization header.
What is the difference between pre-launch and post-launch consentsSome features require user consent.

- Pre-launch consent: Shown as a popup when the mini app is first opened; can be either mandatory or optional.
- Post-launch consent: Shown as a popup only when the getConsent SDK is called; must always be optional.
Do we have a sandbox or staging environment for testing?We don't at this moment, currently all testing is pointing at GoPay production. What we can do is update the redirectURL to point MiniApp staging or production environments.
How payments work inside GoPay MiniAppPayments in a GoPay MiniApp work through a one-time checkout flow. Your backend needs to call the BI-SNAP Core API to create a Payment Deeplink, then from the MiniApp you launch that deeplink using the launchPayment SDK. This will take the user to the GoPay payment page to complete the transaction, and once done, the user is automatically redirected back to your MiniApp. To confirm the result, you should always verify the payment status from your backend or via BI-SNAP notification.
Payment E2E Flow1. Integrate Payments on Sandbox

- Log in to Midtrans and open Sandbox Dashboard
- Request GoPay team to activate generation key- Generate Public and Private Key
- Use Sandbox base URL:
merchants.sbx.midtrans.com
- Integrate Access token b2b API
- Integrate payment host to host API
- Test payment deeplink on web only
Note: Sandbox only supports payment testing via web (not MiniApp)**
2. Migrate to Production
- Log in to Midtrans Sandbox Dashboard
- Request GoPay team to activate generation key
- Generate Public and Private Key
- Change base URL from:
merchants.sbx.midtrans.com to merchants.midtrans.com
- Use launchPayment SDK to open the payment deeplink
- Test payment deeplink on MiniApp
Note: In Production, payments will redirect to GoPay App and then back to the MiniApp
GeneralHow do I register as a merchant?If you're not yet integrated with GoPay via Midtrans, please register through the official guide .
Where do I find my Merchant ID?You can find your Merchant ID on your Midtrans dashboard or by contacting your Account Manager. (docs)
What is a PoP ID?A Point of Purchase ID (PoP ID) is provided by GoPay for payment tracking. You can request this from your business or partnership contact at GoPay.
When will I receive my PoP ID?You will receive your PoP ID after tokenization is completed and the Partnership team generates it. Reach out to your GoPay contact if it hasn’t been shared yet.
Can I onboard multiple mini apps under one Merchant ID?Yes, it's possible to register multiple mini apps under the same Merchant ID. Each mini app will have a unique GoPay_mini_app_id and PoP ID.
What value needs to be inputted into the authorization header in the request?The authorization header should include either Bearer or Basic, depending on the API and credentials required for the specific request. More details are available in the backend API documentation.
How long does onboarding take?Onboarding typically takes around 5–7 working days.
Where will my mini app be shown in the GoPay app?You can reach out to the Midtrans sales team or GoPay business counterpart for the details
SDK & FrontendWhere do I get the Mini App SDK?The GoPay Mini App SDK is available Here
Can I use my existing SNAP Checkout Midtrans integration?Yes, you can. However, merchants must include the PoP ID in the existing Snap Checkout API so that GoPay can identify mini app channels and charge MDR (Merchant Deduction Rate) accordingly. (docs )
Can I use my existing tokenization integration?No, at the moment, tokenized payments are not supported in the mini app payment integration
Are recurring payments supported?No, at the moment, recurring payments or subscriptions are not supported in the mini app payment integration.
What is the incremental work in the payment if I have integrated previously with Midtrans?Merchants should share the PoP ID in the header for non-BI SNAP API or body for BI SNAP API for payment API and should trigger the API through payment SDK
How to integrate with the payment API?Please use the BI-SNAP Core API Redirection Deeplink
What’s the flow for payments?The user experience will be: FE(MiniApp) → BE → Get redirect URL→ Open payment (GoPay) → Redirect back(MiniApp).
How do I get an auth code?To retrieve the auth code, you might call getAuthCode() in SDK.
Why auth code is needed?The authCode can only be generated when the user opens the Mini App because it serves as real-time proof that the request is from an active, authenticated GoPay session. Since it’s tied to the user’s current login state and expires quickly, it’s not possible or secure to provide it in advance. If we were to provide it in advance, there would be no real validation of the user’s session.
How long is it valid?The auth code is valid for 6 minutes.
How do I get access token?Please use the auth code in backend API /v1/mini-apps/authorizations/token.
Can I reuse the token?Yes, the token can be reused. Tokens do not expire and can be safely cached per user.
DisbursementCan I send GoPay Coins or balance?Yes, via /v1/mini-apps/cashback. Currently, only GoPay Coins are available for disbursement.
Do I need a wallet balance?Yes, you need to top up the wallet balance before sending GoPay Coins. Please reach out to the Midtrans sales team or GoPay business counterpart to get the VA to top up.
PermissionsHow to get user location?Please use getLocation() in SDK.
How to get system info?Please use getSystemInfo() in SDK.
How to get user consent?Please use getConsent() in SDK.
Reminder & NotificationCan I send reminders?Yes, you can send a reminder via /v1/mini-apps/reminder. But please discuss with your Midtrans sales team or GoPay business counterpart before using it.
Can I delete a reminder?Yes, you can delete the reminder via /v1/mini-apps/reminder/<id>.
Can I send push notifications?Yes, you can send PN in GoPay app via /v1/mini-apps/notifications/push.
TroubleshootingWhat if auth code fails?If the auth code fails, retry within 6 minutes. Make sure the user has given consent.
SupportWho do I contact for help?For any technical support, you can send out an email to [email protected] or reach out to your Midtrans sales team or GoPay business counterpart.
Additional DetailsCan I use the GoPay sandbox app for testing?GoPay does not provide a separate sandbox app. However, once your GoPay mini app ID is generated, your merchant account will be granted direct access to the mini app for testing purposes.
Is there any limit request per second for the Push Notification API?There is no limit for sending the PN as of now
How do I check if a user is on the latest supported version of the GoPay app?For any technical support, you can send out an email to [email protected]
What happens if the user closes the app before completing payment?The transaction will remain in an incomplete state. You can monitor status on the midtrans dashboard.
How can I validate that a payment has been completed?Please use the /v1.0/debit/notify webhook from the GoPay backend. It confirms payment success and provides reference details.
Can I personalize push notifications per user behavior?Yes, as long as you manage targeting and parameters from your backend. The API supports custom fields through template_parameters.
What do I do if the final URL doesn't load?Make sure the domain is whitelisted and matches with the one submitted. Please also check if your Mini App ID is active and all dependencies (client ID, tokens, SDK) are properly integrated.
How can I check if my domain is whitelisted?If your mini app isn't loading or returns an unauthorized error, your mini-app domain may not be whitelisted yet by GoPay team. Please reach out to [email protected] to ensure it's been reviewed and whitelisted.
What should I do if I need to update my domain or URL after onboarding?You must contact the GoPay Mini App team via email: [email protected] to review and re-whitelist the new domain. Updating domains without whitelisting will result in connection failures.
Can I update my Mini App logo, name, or metadata after launch?Yes, please reach out to your Midtrans sales team or GoPay business counterpart to submit updated assets. Changes will be reflected after approval and deployment.
Why am I getting a 401 Unauthorized error?This usually means your auth token is missing, expired, or incorrect. Double-check if you are sending the token in the Authorization header and that it’s valid.
My payment is stuck in "pending", what should I do?Check the Midtrans dashboard for transaction status. Make sure PoP ID is included in the payment call and that redirect/callback URLs are configured correctly.
Is there a staging environment?Currently, there's no public GoPay Mini App staging environment. All testing need to be completed using production credentials with limited access to the app through whitelisted accounts.
How to configure redirection after payment has been completed?You dont need to configure redirection, it happens automatically after using Launch Payment
How do we test the payment process to the GoPay app?Currently, there’s no public GoPay Mini App staging environment. For testing purposes, we typically support merchants by funding a small amount to their account so they can test the flow in the production environment. This setup works as a semi-production test.
How do we test the redirection to the GoPay app?We’ll provide a staging deeplink to open the Mini App in the GoPay app. To test redirection, merchants must implement the payment API, which redirects users to GoPay for payment. After a successful payment, it will automatically redirect back to the Mini App, but only if launch payment used to open the payment deeplink.
What to fill inside channel-id during payments?It's a 5 digit numeric