WebSDK query parameters
The OSL Pay WebSDK supports passing query parameters via the URL Query String
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.
Integration modes
OSL Pay supports the following two user integration modes. The mode determines whether certain parameters are required:
- Platform self-service mode: Users register and complete KYC on OSL Pay themselves before transacting.
- Merchant direct-connect mode: User KYC is already complete; the merchant passes the user’s identity in and the user goes straight to the payment page.
| 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 (required in merchant direct-connect mode) | |
| crypto | The cryptocurrency the user wants to purchase. See supported crypto list. Contact us if your desired crypto is not supported. | No (required when direction=SELL) | In the SELL direction, this parameter must be passed in by the merchant; the page does not offer a selection. |
| 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 (required when direction=SELL) | In the SELL direction, this parameter must be passed in by the merchant; the page does not offer a selection. |
| amount | The fiat amount to be paid. See fiat limits. | No (required when direction=SELL) | The system validates the amount against the limits for the currency pair to ensure it falls within the allowed range. Buy (BUY): If the amount is missing or over the limit, the user is redirected to the Buy Crypto page to select the amount again. Sell (SELL): There is no amount input page, so a missing amount prevents the user from reaching the payment page (the user is redirected to an error page). |
| payWayCode | The payment method the user wants to use. Currently supported: Credit/debit card: CARDGoogle Pay: GOOGLE_PAY Apply Pay: APPLE_PAYZen wallet: ZEN_WALLETDefaults to CARD for buy transactions when not specified. | No (required when lockPay=true) | When a method is specified and both the order and the user’s device support it, the user can pay with that method. If it is unsupported or not specified, the system defaults to CARD and the user can freely choose another method supported by their device. If lockPay=true is also passed in, the method is strictly locked and the user cannot switch. When payWayCode=CARD, you can use cardId to specify a particular bank card. |
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 | Before passing the email address, use encodeURIComponent to encode it to avoid issues caused by special characters. | |
| 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; required in merchant direct-connect mode | |
| 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 Mobile (width < 480px): When | 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 | |
| direction | Transaction direction. BUY = buy crypto (pay fiat to purchase crypto); SELL = sell crypto (convert crypto into fiat). Defaults to BUY when not passed in. | No | |
| lockPay | Whether to lock the payment/collection method specified by the merchant through payWayCode. Value is the string 'true' or 'false'; defaults to 'false'. | No | |
| cardId | When payWayCode=CARD, specifies a particular bank card for the user. | No (required when lockPay=true and payWayCode=CARD) | |
| resultUrl | The return URL for the payment result page. Once configured, when an order reaches a final state (successful / failed / closed), OSL Pay automatically redirects back to this URL and your page displays the final result. | No | |
| validTime | The validity period of the merchant order, in seconds. When passed in together with merchantOrder, order validity checking is enabled: the confirmation page polls for validation at a fixed interval, and when the order times out or is submitted again, the confirm button is grayed out to block further ordering. | No |
Required parameters for the sell (direction=SELL) flow. The merchant must pass the following parameters in the redirect URL:
- crypto, fiatCurrency, amount: Define the crypto to be sold, the target fiat currency, and the amount. The sell page does not provide amount/currency input, so the flow cannot reach the payment page if any of them is missing.
- payWayCode: The collection method for the sell flow; required when lockPay=true.
Updated 7 days ago