Merchant callback

After interaction with payment consent in the Bank customer is navigated to the callback URL. It has the information about the payment basic attributes like: amount, currency, reference and current payment status.

Payment can be in three states at this point:

• PENDING - payment request is being processed by the bank
• COMPLETED - payment request has been processed by the bank
• FAILED - payment request failed

Payload

• For success

<callback-url-configured-in-merchant-portal>?paymentId=<payment-id>
&status=<PENDING|COMPLETED>
&amount=<amount>
&currency=<currency>
&merchantPaymentId=<value passed to CreatePayment request>

• For failure

<callback-url-configured-in-merchant-portal>?paymentId=<payment-id>
&status=FAILED
&errorDescription=<base64 encoded error message>
&amount=<amount>
&currency=<currency>
&merchantPaymentId=<value passed to CreatePayment request>

Web and mobile callbacks work exactly the same way, they just use a different url.

Implementing the after payment screen (Callback) in mobile app

Upon completion of the payment process, users are directed back from the banking app to your app using a callback via an app link or universal link. Volume accepts only https links, which means traditional deep links like myapp://callback are not supported. Instead, we recommend using App Links and Universal Links, such as https://myDomain.com/callback (opens in a new tab), for their superior security, user experience, seamless integration, and web fallback capabilities.

Callback implementation guide per platform

Flutter:

• Set up app links for Android on Flutter (opens in a new tab)
• Set up universal links for iOS on Flutter (opens in a new tab)

React Native:

• React Native linking documentation (opens in a new tab)
• React Native app links tutorial (opens in a new tab)

Android:

• About app links (opens in a new tab)
• Create Deep Links to App Content (opens in a new tab)

iOS:

• Supporting universal links in your iOS app (opens in a new tab)
• Supporting associated domains on iOS (opens in a new tab)

Important: Well-Known Files Configuration

iOS - Apple App Site Association (AASA)

Place the following file at https://subdomain.yourdomain.com/.well-known/apple-app-site-association:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.yourcompany.yourapp",
        "paths": ["/mobile-web", "/callback", "/*"]
      }
    ]
  }
}

Android - Digital Asset Links

Place the following file at https://subdomain.yourdomain.com/.well-known/assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourcompany.yourapp",
      "sha256_cert_fingerprints": ["YOUR_APP_SHA256_FINGERPRINT"]
    }
  }
]

Testing Your Implementation

Note that well-known files needs to be available in the same subdomain. Example callback url: https://sandbox.web.volumepay.io/mobile-web (opens in a new tab) well-known files like this:

• https://sandbox.web.volumepay.io/.well-known/assetlinks.json (opens in a new tab)
• https://sandbox.web.volumepay.io/.well-known/apple-app-site-association (opens in a new tab)

Use these commands example to test your callback implementation. Replace io.volumepay.flutter.plantstore with your actual Android package name and update the callback URL to match your domain on Merchant portal.

Android Testing

adb -e shell 'am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "https://sandbox.web.volumepay.io/mobile-web?paymentId=ece761ff-3454-40d8-8feb-11366e7b3e40&merchantPaymentId=mobile-web-0.6497495146959015&amount=0.01&currency=GBP&status=FAILED&errorDescription=UGF5bWVudCBhdXRob3JpemF0aW9uIHJlamVjdGVkLiBQbGVhc2UgdHJ5IGFnYWluLg&errorCode=PAYMENT_AUTHORIZATION_REJECTED_OR_FAILED_FROM_PROVIDER_CALLBACK"' \
    io.volumepay.flutter.plantstore

iOS Testing

xcrun simctl openurl booted "https://sandbox.web.volumepay.io/mobile-web?paymentId=ece761ff-3454-40d8-8feb-11366e7b3e40&merchantPaymentId=mobile-web-0.6497495146959015&amount=0.01&currency=GBP&status=FAILED&errorDescription=UGF5bWVudCBhdXRob3JpemF0aW9uIHJlamVjdGVkLiBQbGVhc2UgdHJ5IGFnYWluLg&errorCode=PAYMENT_AUTHORIZATION_REJECTED_OR_FAILED_FROM_PROVIDER_CALLBACK"

Common Issues Checklist