Documentation

Scalapay

Private Preview

With Scalapay, merchants can offer flexible Buy Now, Pay Later (BNPL) options, like paying in 3 or 4 installments, across multiple European Markets. Giving consumers the freedom to split payments while boosting conversion and enhancing the overall shopping experience.

Payment method properties

Markets (consumer)IT FR ES PT DE BE AT FI NL
Processing currenciesEUR
Consumer currenciesEUR
Authentication methodsREDIRECT
Authentication timeout1 Hour
Minimum payment amount5.00 EUR
Maximum payment amount2000.00 EUR (can be enhanced to 4,999.99)
Payment instrumentPASSTHROUGH_WALLET
Recurring paymentsNo
Separate capturesNo
RefundFull - Partial - Multiple
Refund validity90 days for Pay in 3
120 days for Pay in 4
DisputesYes
Settlement riskNo

Make a Scalapay payment

Scalapay payments follow our standardized REDIRECT payment flow. However, we recommend including all relevant settings for any authentication methods you support. To make a payment, you'll need to provide the following data at minimum when calling the /v1/payment-charges endpoint:

FieldsDescription
paymentMethodSCALAPAY
consumer.nameFull name of the consumer, used for display and verification.
consumer.emailConsumer’s email address, used for receipts, verification, and support.
consumer.phoneConsumer’s phone number.
consumer.countryCountry code of the consumer.
order.orderItemsThe list of order items. (name, quantity, amount is mandatory)
order.shippingMethodType of delivery (Digital goods/services: VIRTUAL, Physical goods: TRACKED_DELIVERY, UNTRACKED_DELIVERY, IN_STORE_PICKUP, LOCKER_PICKUP or HYBRID)

📘

Guidance

To improve the consumer experience and maximize payment approval rates with the BNPL provider, consider including the following fields. See the API Reference for full details.

FieldsDescription
consumer.clientIP and UserAgent help with fraud checks and risk scoring.
consumer.billingAddressBilling address supports scoring and approval decisions.
consumer.profileProvide Merchant's CRM data to help improve approval rates.
order.shippingAddressSpecify the delivery address for physical goods to enable shipping and tracking.
order.industryDataInclude industry-specific fields for sectors such as AIRLINE, TRAVEL or EDUCATION.

Request

POST /v1/payment-charges

{
    "paymentMethod": "SCALAPAY",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "paymentDescriptor": "Acme Webshop Says Thank You",
    "merchantPaymentChargeReference": "merch_ref_12345",
    "amount": {
        "currency": "EUR",
        "value": 20000
    },
    "authenticationSettings": [
        {
            "settings": {
                "returnUrl": "https://www.ppro.com/"
            },
            "type": "REDIRECT"
        }
    ],
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+393331234567",
        "birthDate": "1995-01-01",
        "country": "IT",
        "locale": "it-IT",
        "client": {
            "ip": "11.22.22.33",
            "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 ...) Chrome/51.0..."
        },
        "taxIdentification": "SMTJHN95A01H501U",
        "merchantConsumerReference": "consumer_acme_12345",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+393331234567",
            "street": "Via del Corso 100",
            "postalCode": "00186",
            "city": "Roma",
            "region": "Lazio",
            "country": "IT"
        },
        "profile": {
            "createdDate": "2025-01-01",
            "firstOrderDate": "2025-01-05",
            "lastOrderDate": "2025-05-01",
            "lifetimeOrderCount": 10,
            "lifetimeOrderValue": 450000,
            "lifetimeCanceledOrderCount": 3
        }
    },
    "order": {
        "orderItems": [
            {
                "sku": "TSHIRT01",
                "category": "Apparel",
                "subCategory": "T-Shirt",
                "name": "Classic Cotton T-Shirt",
                "quantity": 1,
                "amount": 5000
            },
            {
                "sku": "JACKET10",
                "category": "Apparel",
                "subCategory": "Jacket",
                "name": "Black Leather Jacket",
                "quantity": 1,
                "amount": 15000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+393331234567",
            "street": "Piazza di Spagna, 3",
            "postalCode": "00187",
            "city": "Roma",
            "region": "Lazio",
            "country": "IT"
        },
        "orderReferenceNumber": "order_acme_12345",
        "totalTaxAmount": 4400
    },
    "autoCapture": true,
    "webhooksUrl": "https://webhook.site/50862fe4-0798-4d92-b3de-dcf1d11ba1ca"
}

Response

You'll receive our standard payment charge response with the available authentication methods:

{
    "id": "charge_F9xzoNWNPnopyZ9zKidHb",
    "paymentMethod": "SCALAPAY",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "UNSCHEDULED",
    "instrumentId": "instr_WGReQN3r1yhgwYR1OrQeR",
    "currency": "EUR",
    "country": "IT",
    "paymentDescriptor": "Acme Webshop Says Thank You",
    "status": "AUTHENTICATION_PENDING",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+393331234567",
        "birthDate": "1990-01-01",
        "country": "IT",
        "locale": "it-IT",
        "client": {
            "ip": "11.22.22.33",
            "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 ...) Chrome/51.0..."
        },
        "taxIdentification": "SMTJHN95A01H501U",
        "merchantConsumerReference": "consumer_acme_12345",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+393331234567",
            "street": "Via del Corso 100",
            "postalCode": "00186",
            "city": "Roma",
            "region": "Lazio",
            "country": "IT"
        },
        "profile": {
            "createdDate": "2025-01-01",
            "firstOrderDate": "2025-01-05",
            "lastOrderDate": "2025-05-01",
            "lifetimeOrderCount": 10,
            "lifetimeOrderValue": 450000,
            "lifetimeCanceledOrderCount": 3
        }
    },
    "order": {
        "orderItems": [
            {
                "sku": "TSHIRT01",
                "category": "Apparel",
                "subCategory": "T-Shirt",
                "name": "Classic Cotton T-Shirt",
                "quantity": 1,
                "amount": 5000
            },
            {
                "sku": "JACKET10",
                "category": "Apparel",
                "subCategory": "Jacket",
                "name": "Black Leather Jacket",
                "quantity": 1,
                "amount": 15000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "Luca",
            "lastName": "Rossi",
            "phoneNumber": "+393311234567",
            "street": "Piazza di Spagna, 3",
            "postalCode": "00187",
            "city": "Roma",
            "region": "Lazio",
            "country": "IT"
        },
        "orderReferenceNumber": "order_acme_12345",
        "totalTaxAmount": 4400
    },
    "authenticationMethods": [
        {
            "details": {
                "requestUrl": "https://payment.scalapay.com/hpp/qwerty124",
                "requestMethod": "GET"
            },
            "type": "REDIRECT"
        }
    ],
    "authorizations": [
        {
            "id": "authz_B77MEwwySeEeemVGrcA2u",
            "amount": 20000,
            "status": "AUTHENTICATION_PENDING",
            "merchantPaymentChargeReference": "merch_ref_12345",
            "createdAt": "2025-09-01T23:05:55.451Z",
            "updatedAt": "2025-09-01T23:05:55.451Z"
        }
    ],
    "captures": [],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-09-01T23:05:55.365Z",
    "updatedAt": "2025-09-01T23:05:55.451Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_F9xzoNWNPnopyZ9zKidHb/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_F9xzoNWNPnopyZ9zKidHb/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_F9xzoNWNPnopyZ9zKidHb/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_F9xzoNWNPnopyZ9zKidHb/voids"
        }
    }
}

Pick the desired authentication method

REDIRECT

  1. Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl.
    For example, with the value of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.
  2. The consumer will be presented with the reference number and instructions to complete the payment.

Handling the payment result

REDIRECT

  1. After the consumer completes the payment, they are redirected to the returnUrl specified in the payment charge creation request.
  2. Upon redirect back to your site, retrieve the latest payment status by performing a GET /v1/payment-charges/{paymentChargeId}. Use the returned status field to determine and display the final payment outcome to the consumer.
  3. Additionally, webhooks are triggered to notify you of the payment result. This ensures you receive the outcome even if the consumer closes their browser or fails to return to your website.

Payment instrument

A PASSTHROUGH_WALLET instrument will be created.

Request

GET /v1/payment-instruments/{instrument-id}

Response

{
    "id": "instr_WGReQN3r1yhgwYR1OrQeR",
    "type": "PASSTHROUGH_WALLET"
}

Sandbox testing

Test card numbers

PANExpiry DateCVVResult
5200828282828210any date, greater than last installment date123✅ Success
4000000000000341any date, greater than last installment date123❗Failure

Additional Information

Before you go live

  • Consumer journey of various products can be seen here
  • Consider having a look at Scalapay's post-payment consumer experience here
  • Check industry-specific data requirements: Reach out to your PPRO Account Manager to confirm if there are any additional industry data specifications needed for your industry vertical. Providing these details in the order.industryData can help maximize your payment approval rates.

Branding guidelines

  • Discover the media kit here

Disputes & chargebacks management

A dispute occurs when a consumer disputes a payment and contacts their issuer bank or the payment method provider to initiate a chargeback. Disputes are majorly categorized into the following two groups:

  • Fraud-related reasons — such as lost or stolen card, unauthorized signature, Card Not Present transaction, phishing, etc. — are typically initiated by the consumer’s issuing bank with the payment method provider, on behalf of the consumer.
    • In such cases, the payment method provider takes full responsibility for the confirmed fraud, and you as the merchant are not impacted.
  • Merchant-liability reasons — such as product not received by the consumer, unacceptable or faulty/fake goods, cancelled services or subscriptions, refunds not issued, or credits not yet received — are generally initiated either typically directly by the consumer with the payment method provider or via the issuer bank.
    • In such cases, the consumer is first requested to contact the merchant directly to resolve the dispute. If the merchant does not respond within 10 days, the provider/PPRO will contact the merchant on the consumer’s behalf. If, after a further additional 10 days & with 3 reminders, the merchant still fails to respond, or if the provider/issuer rules against the merchant, the disputed amount is charged back and deducted from the merchant’s future settlement payouts.
    • Merchants are strongly advised to respond within the defined timelines and provide the required information. Merchant responses are shared with the consumer, together with an invitation to resolve any remaining concerns directly.

The requirements for defending against disputes vary depending on the reason for the dispute. For all types of dispute, you must provide documents with details of transactions to help you build a strong case to challenge the dispute in your favor. Soon, you will also be able to manage the entire dispute process programmatically via the Global Dispute Platform and the Disputes API.

Updated about 15 hours ago