PPRO Gateway Guide


Services and Compatibility

Payment Gateway Company Name:
Services that work with Spreedly:
  • PPRO
Supported operations:
Unsupported operations:
Purchase, Authorize, Capture, Void
Supported payment types:
Bancontact, Blik, Boleto Bancario, Giropay, Ideal, Klarna, Multibanco, Oxxo, Sepa Direct Debit, Sofort, Trustly
Spreedly 3DS2 Global Supported
Gateway Specific 3DS2 Supported
Populate MIT GSF Support
Europe, North America, South America
API endpoint URL:

Authentication and Security

Specific names for credentials:
PPRO Contract ID

Onboarding Merchants in:

Additional Notes

In order to start using PPRO please reach out to success@spreedly.com

Adding PPRO as an LPM Gateway

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <contract_id>Your contract id</contract_id>

  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <contract_id>Your contract id</contract_id>
    <supports_purchase type="boolean">false</supports_purchase>
    <supports_authorize type="boolean">false</supports_authorize>
    <supports_capture type="boolean">false</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">false</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">false</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
      <value>Your contract id</value>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2023-07-14T19:31:01Z</created_at>
  <updated_at type="dateTime">2023-07-14T19:31:01Z</updated_at>

env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.add_gateway(:ppro, contract_id: "Your contract id")

@credentials={"contract_id"=>"Your contract id"}>

The Spreedly PPRO Gateway is intended to provide a consistent and convenient way to transact using payment methods other than credit cards. We currently support ten different local payment methods (LPMs). Most of these LPMs require sending your customer to a page hosted by a backend processor in order to complete the payment process (such as a mandate form in case of SEPA).

Local Payment Methods

Oxxo and Boleto Bancario

email Oxxo & Boleto Bancario
document_id Boleto Bancario
zip Boleto Bancario
city Boleto Bancario
state Boleto Bancario
address1 Boleto Bancario
Optional gateway specific fields
merchant_logo_url Oxxo & Boleto Bancario
due_date Oxxo & Boleto Bancario
beneficiary Boleto Bancario
render_type Boleto Bancario


Available country code BE
Minimum transaction amount 0.01 EUR
Maximum transaction amount 1,500 EUR for mobile payments (URL intent and QR code)
No known limit for the standard flow
Refund Full, Partial, Multiple Partial and Over-refund

Optional Parameter

app_to_app_url Custom app URL for redirecting the consumer back to the app, which triggered the payment. Overrides redirect_url for mobile flows.

For branding information, see the Bancontact branding guidelines.


Available country code PL
Minimum transaction amount 0.01 PLN
Maximum transaction amount 10,000 PLN / transaction
Refund Full, Partial and Multiple Partial


Available country code DE
Minimum transaction amount 1.00 EUR
Maximum transaction amount No limit.
Up to 10.000 EUR - payment guaranteed.*
Over 10.000 EUR - payment not guaranteed
Refund Full, Partial and Multiple Partial

For branding information, see the giropay branding guidelines.

Note transactions may change from any state at any time. This change occurs especially from a FAILED to a SUCCEEDED state.

* giropay contractually guarantees the payment for up to 6 weeks after the initial transaction.


Available country code NL
Minimum transaction amount 0.01 EUR
Maximum transaction amount Subject to transaction approval from the consumer’s bank
Refund Yes

Optional Parameter

bic Valid BIC. It can only contain 8 or 11 alphanumeric characters. Must be an iDEAL issuer’s BIC.

Note transactions may change from any state at any time. This change occurs especially from a FAILED to a SUCCEEDED state.

For information regarding branding, see the iDEAL branding guidelines.


Available country code Fair Financing: AT, DE, FI, NO, SE, UK
PayNow: AT, DE, NL, SE
Pay in 30 Days: DE, DK, FI, NL, NO, SE, UK
Minimum transaction amount None.
Maximum transaction amount Klarna now sets the maximum transaction value for all products offered.
Refund Full, Partial and Multiple partial


Field name M/O Description
tax_amount M The total tax amount of the order in the currency’s minor units. This information is essential to provide detailed purchase information to the consumer (e.g., on the invoice).
payment_method_category O The payment method category:


See Klarna documentation about Payment Method Categories.
If no value is set, this parameter defaults to the configuration set when PPRO boards the merchant with Klarna.
billing_address M The billing address. It is passed as a URL-encoded serialized JSON string (see Klarna documentation about the billing address).
Make sure you follow Klarna’s postal code validation rules
emd O Stands for “Extra Merchant Data”, a pass-through field containing additional information about the merchant and the transaction. It is passed as an URL-encoded JSON string. Corresponds to the attachment.body of the Create Payment Session call.
hpp_title O The title of the hosted payment page, displayed in the browser’s tab. If not set, defaults to the title set in the merchant configuration provided during the boarding process.
logo_url O URL of the merchant’s logo to be displayed on Klarna’s hosted payment page. If not set, defaults to the logo set in the merchant configuration.
order_items M The items being purchased. Passed as URL-encoded serialized JSON string (see Klarna documentation about Order Lines)
customer O Consumer information to be forwarded to Klarna as a URL-encoded serialized JSON string (see Klarna documentation about Customer data).
Sending the date_of_birth field prevents Klarna from prompting it in their hosted payment page.
purchase_type O The type of purchase being made. Defines, for example, the label of the button on Klarna’s hosted payment page:


It can also be set in the merchant configuration. If not specified, defaults to CONTINUE.
shipping_address O The shipping address. Passed as URL-encoded serialized JSON string. Defaults to transientin.billingaddress
Make sure you follow Klarna’s postal code validation rules
background_images O The images to be used as a background on Klarna’s payment page (the image best matching the resolution will be used). This is a pass-through field. Check Klarna’s documentation for more information about the correct format. This value can also be set in the merchant configuration.

For information regarding branding, see the Klarna official website.


Available country code PT
Minimum transaction amount None.
Maximum transaction amount 99.999,99 EUR
Refund No


Available country code EU countries: AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE

EEA Countries: IS, LI, NO

Countries that have bilateral agreements with EU: AD, SM, MC, VA

Other SEPA-supporting countries (supported EUR-denominated accounts only): PF, TF, GI, GG, IM, JE, BL, PM, CH, GB, WF
Minimum transaction amount EUR 0.10
Maximum transaction amount EUR 1,000
Refund Full, Partial, Multiple Partial and Over refund


Field Name M/O/C Description
One-off payments or first payment in recurring series
email M Consumer’s email address. It is required to send the direct debit mandate.
iban M Valid IBAN
debtor_address C The full address of the party to be debited (eg: shopper). Up to two lines are supported, each separated by a #.

Ex: Street 123#43212 City

This parameter is only required for the following countries; the parameter is not required for other countries.

Andorra, French Polynesia, French Southern Territories, Gibraltar, Great Britain, Guernsey, Holy See (Vatican City State), Isle of Man, Jersey, Monaco, New Caledonia, Saint Barthélemy, Saint Pierre and Miquelon, San Marino, Switzerland, Wallis and Futuna


Available country code AT, BE, CH, DE, ES, GB, IT, NL, PL
Minimum transaction amount 1 EUR (or equivalent)
Maximum transaction amount Low&medium risk: 5,000 EUR

High risk: 2,500 EUR

A VIP project can be enabled on request. The limits for VIP project are:

5,000,00 EUR / 24h 10,000,00 EUR / 24h 15,000,00 EUR / 36h 25,000,00 EUR / 24h There is an exception if an end consumer’s bank has set a lower payment limit for the end consumer’s bank account than the above determined limit(s) for SOFORT. If this is the case, a SOFORT transaction exceeding this bank account limit is not possible.
Refund Full, Partial and Multiple Partial

Transactions may change from any state, especially from FAILED to a SUCCEEDED state at any time.

For information regarding branding, see the Sofort official website.


Available country code AT, DE, DK, EE, ES, FI, GB, LT, LV, NL, NO, SE
Minimum transaction amount 0.01 EUR (or equivalent)
Maximum transaction amount 1000 EUR/transaction or equivalent

Sweden and Finland: 2000 EUR/transaction or equivalent
Refund Full, Partial and Multiple Partial


Field Name M/O/C Description
consumer_ref M The ID, username, hash, or anything used to identify the consumer. Make sure it is the same ID, username, or hash used in the merchant’s shopping system. For example, if the shopper John Doe is identified with the unique identifier ABCXYZ123, populate the field specin.consumerref with ABCXYZ123.
client_ip O The consumer’s publicly-routable IPv4.
national_id O The consumer’s social security number/ personal number/birth number/etc. Some banks use it for identifying transactions and Know Your Customer or Anti Money Laundering
beneficiary_id M Only for e-wallet merchants: ID, username, hash, or anything uniquely identifying the ultimate beneficiary
beneficiary_name M Only for e-wallet merchants: The ultimate beneficiary’s full name (see Annotations for details)
beneficiary_address M Only for e-wallet merchants: The ultimate beneficiary’s street address (street, zip code, city), excluding the country

Example: Main street 1, 12345, Barcelona
beneficiary_country_code M Only for e-wallet merchants: The ultimate beneficiary’s country of residence (two-letter ISO 3166 code)

Example: ES

For branding information, see the Trustly official website.

Initiate a purchase

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
 -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
 -H 'Content-Type: application/xml' \
 -d '{
    "transaction": {
      "amount": 1000,
      "currency_code": "EUR",
      "payment_method": {
        "payment_method_type": "sofort",
        "country_code": "BE",
        "full_name": "John Doe"
      "amount": 1000,
      "currency_code": "EUR",
      "retain_on_success": true,
      "redirect_url": "https://example.com",
      "callback_url": "https://example.com",

The required redirect_url and callback_url fields should point to listening endpoints on your servers. They will be used to give you results after the customer completes their transaction.

The state field of the transaction: it is set to pending. We’ve also received back a status code of 202, which indicates that this transaction isn’t complete - rather it needs further processing in order to actually collect payment.

To do that further processing, you simply need to redirect the customer’s browser to the checkout_url returned in the transaction.

Redirecting to this url will land the customer on the offsite page they will use to authorize payment. In this case, we’re using SEPA direct debit and so the user will see a localized version of the SEPA mandate.

Note that these pages will be hosted by a payment method or financial institution specific provider.

Finalizing the transaction

Once the customer completes the offsite flow, their browser will be sent back to the redirect_url that you specified when creating the transaction.

Note the extra field tacked on to the redirect_url; the transaction_token allows you to determine the target transaction for the redirect. You can then lookup details on the transaction and see exactly what happened.

Note the state field of the transaction: it is set to processing. This indicates that the transaction has been accepted and submitted for processing. Funds have not been received yet. The next section expands upon the various payment states.


Currently almost all LPMs, execept Multibanco, process refunds. Oxxo and Boleto Bancario require additional refund parameters which are account_number, bank_agency and bank_number. If you want to process a refund for Oxxo and Boleto Bancario make sure that those parameters are part of the payment method.

refund_account_number M Consumer’s bank account number
refund_bank_agency M Consumer’s bank agency number
refund_bank_name M Consumer’s bank name (minimum length of two characters)

Payment states

For payment methods like SEPA Direct Debit, the transaction will not be succeeded at this stage. This is because funds have not actually reached your account yet. The state attribute of the transaction will be processing to indicate that the transaction was accepted, but it might take a few days for the funds to actually reach your account.

It’s up to you at this point how you’d like to respond if the transaction is in the processing state. Some businesses may want to simply grant the customer access to whatever service they’re buying, knowing that a significant percentage of them will be successful and that they will eventually receive the funds. Others maybe shipping a very expensive product, and may want to wait until the funds actually hit their account before shipping.

So how will you know when the state of the transaction actually moves from processing? The answer lies in the following section on Callbacks.

Important note about transaction states

Be aware that, based on how several alternate payment methods work, including SEPA Direct Debit, there is always a chance for a transaction to succeed after it has been marked as failed by the system. The succeeded state, on the other hand, is final. You will receive a callback notification if a transaction succeeds after it has been marked as failed.

Gateway Specific Fields

selling_point point of sale
sole_service service sold
merchantrefundid allows a client specified identifier to be passed in as part of a refund call
preferred_language 2-letter language code of the language preferred when presenting payment pages to the consumer
beneficiary Bradesco-only The beneficiary of the payment - for example, the merchant’s name and order number
render_type How to render LPM: as PDF or HTML. Default: PDF.
merchant_logo_url Bradesco-only The URL of the logo to be displayed on the payment page.

curl https://core.spreedly.com/v1/transactions/KS3oZgWXCfFeirK16anYbijLxR/credit.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
            <merchant_refund_id>Your merchant refund id</merchant_refund_id>
            <selling_point>Your point of sell</selling_point>
            <sold_service>Your service sold</sold_service>
            <preferred_language>Language preferred when presenting payment page</preferred_language>

Preferred Language


The Belgian market is diverse in its language support requirements. We recommend detecting the language of the consumer and sending the preferred_language. The options are fr, nl, de or en.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
 -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
 -H 'Content-Type: application/xml' \
 -d '{
    "transaction": {
      "payment_method": {
        "payment_method_type": "bancontact",
        "country_code": "BE",
        "full_name": "John Doe"
      "amount": 1000,
      "currency_code": "EUR",
      "retain_on_success": true,
         "redirect_url": "https://example.com",
         "callback_url": "https://example.com",
         "gateway_specific_fields": {
               "ppro": {
                       "preferred_language": 'fr'


The callback_url you specified when creating the purchase provides another way to receive notice of transaction state. For payment methods such as SEPA Direct Debit, the transaction will initially move to a state of processing and stay there for a time (usually 2-3 days) before the funds are actually transferred. You’ll eventually receive a callback indicating that the transaction has moved to a different state. There are other payment methods where the transaction state may change from FAILED to a SUCCEEDED at any time.

For more information on callbacks, see Spreedly’s Offsite Payments documentation.