SnappPay BNPL Integration Guide | Webito Merchant Documentation

Comprehensive SnappPay BNPL (Buy Now, Pay Later) Setup Guide in Webito

Buy Now, Pay Later (BNPL) has become one of the most powerful conversion and sales growth engines in modern e-commerce. In Iran, SnappPay (part of the Snapp Group) is the market leader in consumer credit, allowing shoppers to split their cart total into 4 equal monthly installments without checks, promissory notes, guarantors, or interest, while merchants receive the full order amount settled upfront by SnappPay.

The Webito SnappPay plugin connects directly to SnappPay's modern OAuth2 REST API and handles the critical Two-Phase Settlement (Settle) flow with 100% automated reliability.

1. Key Business Benefits of SnappPay for Your Store

Performance Metric (KPI)	Impact of SnappPay	Underlying Reason
Checkout Conversion Rate	35% to 55% Increase	The customer pays only 25% at checkout, significantly lowering price hesitation.
Average Order Value (AOV)	40% to 70% Growth	Shoppers comfortably add complementary products and higher-tier variants.
Credit Default Risk	0% for the Merchant	SnappPay assumes 100% of installment collection risk. Payouts are fully guaranteed.
New Customer Acquisition	10M+ SuperApp Users	Prominent SnappPay branding attracts loyal users from Iran's largest digital ecosystem.

2. Merchant Onboarding & Required Credentials

To obtain merchant API credentials:

Submit your merchant request via the official portal (snapppay.ir) or email [email protected] (Merchant Hotline: 021-96862222).
Provide corporate registration documents, national economic ID, active Enamad license, and an official corporate bank IBAN (Sheba).
Execute the merchant agreement to receive your Client ID, Client Secret, Username, and Password from portal.snapppay.ir.

Parameter in Webito	SnappPay Specification	Required?	Description	Example
Client ID	`client_id`	Yes	Unique merchant client identifier in SnappPay OAuth2	`webito_merchant_live_01`
Client Secret	`client_secret`	Yes (Secret)	Confidential client secret key for access token generation	`sec_snapp_8899aabbccddee`
Username	`username`	Yes	Merchant portal service username	`merchant_shop_user`
Password	`password`	Yes (Secret)	Merchant service password	`P@ssw0rd!Snapp2026`
Sandbox Mode	Test Environment	No	Route requests to staging server (`staging-api.snapppay.ir`)	`true / false`

3. Payment Flow & Mandatory Two-Phase Settlement

Unlike standard debit gateways, SnappPay mandates a Two-Phase Settle architecture. Webito orchestrates this sequence seamlessly:

mermaid
sequenceDiagram
    autonumber
    actor Customer as Shopper / Buyer
    participant Webito as Webito Storefront
    participant SnappPay as SnappPay API (OAuth2 / Payment)

    Webito->>SnappPay: 1. Generate Bearer Access Token (/oauth/token)
    Customer->>Webito: 2. Select SnappPay 4-Installment Checkout
    Webito->>SnappPay: 3. Create Payment Intent & Token (/payment/v1/token)
    Webito-->>Customer: 4. Redirect to SnappPay Hosted Portal (payment.snapppay.ir)
    Customer->>SnappPay: 5. Pay 1st installment (25%) via dynamic SMS OTP
    SnappPay-->>Webito: 6. Return to Store Callback with Payment Token
    Webito->>SnappPay: 7. Verify Transaction Status (/payment/v1/verify)
    SnappPay-->>Webito: 8. Confirm authorization validity (Status: SUCCESS)
    Webito->>SnappPay: 9. Execute Two-Phase Settle (/payment/v1/settle)
    SnappPay-->>Webito: 10. Confirm final debit and order capture (200 OK)
    Webito-->>Customer: 11. Render Order Confirmation & Receipt Screen

[!CAUTION] Critical Warning Regarding the Settle Step If a store's gateway fails to call /settle after verification, SnappPay assumes the merchant was unable to fulfill the order and will automatically reverse (revert) the transaction after 30 minutes, refunding the customer's initial installment. Webito's plugin executes the Settle call immediately after verification.

4. Troubleshooting & Common Error Codes

HTTP Status	Error / Code	Root Cause	Resolution
401	`Unauthorized / Invalid Client`	Client ID or Client Secret is misconfigured	Re-copy credentials from `portal.snapppay.ir` into Webito.
403	`IP Not Whitelisted`	Server static IP is not registered with SnappPay	Email your Webito server's dedicated outbound IP to SnappPay support.
400	`User Not Eligible`	Shopper does not have enough BNPL credit limit	Customer must increase their credit limit in the Snapp superapp.
409	`Duplicate / Token Expired`	Payment token was already consumed or timed out	Shopper must re-initiate checkout from their cart.
504	`Gateway Timeout`	Upstream bank or PSP delay	Webito automatically executes idempotent verification retries.

5. Frequently Asked Questions (FAQ)

Q: What is the merchant fee/commission for SnappPay?
A: SnappPay merchant commission typically ranges between 2% and 5% depending on category, volume, and agreement terms. Buyers pay zero interest or fees.

Q: When are funds paid out to the merchant?
A: SnappPay settles 100% of the purchase amount (minus agreed commission) via national Paya banking cycles within 24 to 48 business hours.

Q: How are customer order returns handled?
A: Clicking "Refund" in the Webito order screen calls SnappPay's /revert endpoint. Debited installments are refunded to the customer's wallet and future installments are cancelled.

Related Articles

Help Categories

SnappPay BNPL 4-Installment Payment Gateway Setup Guide in Webito