Skip to main content

Satispay

Satispay is a mobile payment method popular in Italy, enabling shoppers to pay in seconds using their phone app. It offers seamless account-to-account checkout and strong support for real-time authorization and refunds.

Satispay app checkout screenSatispay app checkout screen

Mobile-First Checkout​

Satispay initiates a push notification to the shopper’s app where they confirm the payment in one tap.

  • Fast checkout experience
  • Real-time confirmation
  • Strong adoption in Italy

Details​

Country Italy
Currency EUR
InputPhone number or QR code
Integrations Direct API

Capabilities​

Refunds
Partial refunds
Multiple partial refunds
Final amount captured later
Multiple partial captures
Incremental authorizations
Disputes
Recurring payments
Split payments
Flow TypesImmediateReccuring
info
  • Partial refunds are only possible within 365 days from the payment creation date.
  • Delayed capture is possible upto 10 days after the original authorization.

Flows

Satispay Onboarding​

This flow works for ONE_TIME , RECURRING , and TOKEN_ONLY transaction types.

Steps​

  1. Shopper selects Satispay.
  2. Merchant Initiates Payment with Nopan.
  3. Nopan initiates the payment with Satispay by asking to create an authorizatoin token.
  4. Satispay returns back a tokenId and a redirect url.
  5. Merchant redirects the user to Satispay
info
  • On Mobile the redirect will be intercepted and shopper will get redirected to Satispay app right away
  • On Desktop shopper may choose to scan a QR code or enter their phone number and get push notification
  1. Shopper accepts authorization.
  2. Nopan completes first payment.
  3. Nopan notifies merchant about transaction being completed.
  4. Alternatively merchant periodically checks for the status of transaction.
tip

In case the payment is set as a ONE_TIME, merchants can choose not to redirect. Instead they can do one of 2 things:

  • Collect a phone number and display it on their end
  • Request a QR Code and display it on their end

Integration​

Send a POST /payments/initiate request to Nopan with the following format: 

{
  "processingAccountId": "merchant",
  "clientTransactionId": "order123",
  "returnUrl": "https://api.merchant.callback?ref=order123",
  "transactionType": "RECURRING",
  "paymentDetails": {
    "amount": 200,
    "currency": "EUR",
    "country": "IT",
    "description": "Product ID 1234 purchase"
  },
  "providerDetails": {
    "providerId": "SATISPAY"
  },
  "payerDetails": {
    "payerId": "payerUUID"
  },
  "requestContext": {
    "ipAddress": "203.0.113.45",
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
    "channel": "WEB",
    "deviceId": "device-99001",
    "locale": "it-IT"
  },
  "metadata": {
    "subscriptionId": "sub-456",
    "customerId": "cust-789",
    "billingCycle": "monthly"
  }
}

tip

returnUrl and payerId fields are mandatory.

Satispay Recurring​

This flow works only with RECURRING transaction types.

Steps​

  1. Merchant sends Nopan a Charge Request with either a payerId or a payment token.
  2. Nopan validates payment token with Satispay
  3. Nopan initiates a payment with Satispay
  4. Nopan notifies merchant about transaction being completed.

Integration​

Send a POST /payments/charge request to Nopan with the following format:

{
  "clientTransactionId": "order123",
  "transactionType": "RECURRING",
  "paymentDetails": {
    "amount": 200,
    "currency": "EUR",
    "country": "IT",
    "description": "Product ID 1234 purchase"
  },
  "providerDetails": {
    "providerId": "SATISPAY"
  },
  "payerDetails": {
    "payerId": "payerUUID",
    "paymentToken": "paymentTokenUUID"
  }
}
tip

paymentToken or payerId is required.

Testing​

Leverage Nopan Mocking framework to test your Satispay integration with Nopan. Alternatively merchant can request to register with Satispay sanbox environment and receive a special test app they can use to test vairous scenarious.

info

Contact Nopan if you would like to register with Satispay sandbox account. You will need:

  • Valid phone number.
  • Email address.
  • Use cases you would like to test

You can also choose to mock the behaviour with Nopan directly. See Mocking for more details.

Error Codes​

info

For a full list of Nopan error codes, see Error Handling.

Satispay Code
Nopan Reason Code
Description
Action
21 – Insufficient availability
1000
Non sufficient funds.
Retry
27 – Payment not allowed
8003
Operation not supported.
Adjust Logic
34 – Unauthorized
1020
Declined. Possible fraud.
Fix Request
36 – Missing or invalid fields
4000
Invalid input.
Fix Request
41 – Resource not found
4001
Payment not found.
Fix Request
45 – Unable to fulfill the request
8004
Provider error.
Retry
70 – Anti-hammering violation
3000
Rate limit exceeded.
Retry
131 – Payment too old to be refunded
5008
Refund window expired.
Adjust Logic
172 – Pre-authorized payment token invalid
2002
Invalid payer identifier.
Fix Request
173 – User not found
2002
Invalid payer identifier.
Fix Request
246 – HOTP token not valid
4000
Request failed validation.
Fix Request

Requirements​

  • Merchant must be registered with Satispay.
  • Shopper must have the Satispay mobile app.
  • Recurring transactions require prior consent.

Learn More​

Learn more about differences in the recurring models on Satispay website.