WebSDK query parameters
You can use these parameters to customize the payment flow, pre-fill user information, configure callback URLs, and ensure transaction security and compliance.
- Passing method: All parameters are passed through the URL Query String.
- Encoding requirement: Certain parameter values must be URL-encoded to avoid parsing errors caused by special characters.
| Parameter | Description | Required | Notes |
|---|---|---|---|
| appId | Your unique identifier. You will receive an appId after signing the contract. | Yes | |
| merchantOrder | Your order number to track OSL Pay orders. Used for idempotency checks. | No | |
| crypto | The cryptocurrency the user wants to purchase. See supported crypto list. Contact us if your desired crypto is not supported. | No | |
| network | The blockchain network corresponding to the selected crypto. See supported crypto and network list. The crypto and network must match; otherwise, the values will be ignored. | No | |
| fiatCurrency | The fiat currency the user will pay with. See supported fiat currencies. | No | |
| amount | The fiat amount to be paid. See fiat limits. | No | |
| payWayCode | Supported payment method: Credit/debit card: CARDGoogle Pay: GOOGLE_PAY Apply Pay: APPLE_PAYDefaults to the CARD payment method | No | Amounts are strictly validated against limits; otherwise, users will be redirected to the Buy Crypto page to enter the amount again. |
| User’s email. Pre-filled on the login page. The user must still enter the email verification code unless the accessToken is also provided. | No | Specified payment method: If both the order and the user’s device support it, the user can only pay with the specified method. Unsupported or not specified: The system defaults to CARD payment, and the user can choose from other supported methods on their device. | |
| accessToken | To enhance user experience, you may pass the accessToken obtained through OpenAPI (valid for 2 hours). The system will automatically log the user in, skipping the manual login step and significantly shortening the purchase process. | No | Note: Do not use this parameter unless the user’s email is confirmed. |
| address | Specified address with validation: When the user provides a crypto address, the system will verify whether it matches the crypto and network of the order. If the validation passes, the user will skip the address confirmation page, and the crypto will be sent directly to the specified address. Validation fails or no address specified: The parameter will be discarded, and the user will need to enter the receiving address manually on the address input page. | No | |
| merchantUser | Off-chain mode required: This is the user’s unique identifier on the merchant side. When this parameter is passed, the user will skip the address confirmation page. On-chain mode required for wallet-type merchants: merchantUser must be bound to the user’s email. Once the binding is established, the user cannot log in with a different email. | Required when checkType is DEFI_AUTH or DEFI_BIND | |
| successUrl | The URL to which the user is redirected after successful payment. If this parameter is not provided, the user will be redirected to the address you specified during onboarding. | No | Before passing the query parameter value, use encodeURIComponent to encode it to avoid issues with special characters. |
| failUrl | The URL to which the user is redirected after payment failure. If this parameter is not provided, the user will be redirected to the address you specified during onboarding. | No | Before passing the query parameter value, use encodeURIComponent to encode it to avoid issues with special characters. |
| callbackUrl | The webhook push URL. If this parameter is not provided, OSL Pay will push notifications to the address you specified during onboarding. | No | Before passing the query parameter value, use encodeURIComponent to encode it to avoid issues with special characters. |
| checkType | For wallet merchants, this parameter specifies the function to be completed by WebSDK.DEFI_AUTH enables the authorization process.DEFI_BIND enables the user binding process. | No | |
| redirectUrl | The URL to which the user is redirected after wallet merchant authorization is completed. | Required when checkType is DEFI_AUTH | Before passing the query parameter value, use encodeURIComponent to encode it to avoid issues with special characters. |
| useBorder | True/False, default is 'True' Desktop (width ≥ 480px): A fixed card layout is always used, regardless of the useBorder setting.Mobile (width < 480px): When useBorder is 'True', borders and fixed dimensions are retained. When useBorder is 'False', the layout automatically adapts to full screen, removing borders and rounded corners. | No | |
| locale | Default language parameter. See supported languages. | No | |
| sign | Required when address, merchantUser, or redirectUrl is not empty. These values take effect only after verification. See how to generate sign. | Required when address, merchantUser, or redirectUrl is not empty |
Updated 8 months ago