PPRO Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
PPRO
Services that work with Spreedly:
  • PPRO
Supported operations:
Purchase, Refund
Unsupported operations:
Authorize, Capture, Void
Supported payment types:
Bancontact, Blik, Boleto Bancario, Giropay, Ideal, Klarna, Multibanco, Oxxo, Sepa Direct Debit, Sofort, Test, Trustly
Spreedly 3DS2 Global Supported
No
Gateway Specific 3DS1 Supported
No
Gateway Specific 3DS2 Supported
No
Regions:
Europe, North America, South America
API endpoint URL:
https://api.girogate.de

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>
        <gateway_type>ppro</gateway_type>
        <contractid>Your contract id</contractid>
      </gateway>'

<gateway>
  <token>DQABlEAIRfA29qTxbdMIAuFhSh1</token>
  <gateway_type>ppro</gateway_type>
  <name>PPRO</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <contractid>Your contract id</contractid>
  <characteristics>
    <supports_purchase type="boolean">true</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>
  </characteristics>
  <credentials>
    <credential>
      <name>contractid</name>
      <value>Your contract id</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>merchantrefundid</gateway_specific_field>
    <gateway_specific_field>selling_point</gateway_specific_field>
    <gateway_specific_field>sold_service</gateway_specific_field>
    <gateway_specific_field>preferred_language</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>bancontact_ppro</payment_method>
    <payment_method>blik_ppro</payment_method>
    <payment_method>boleto_bancario_ppro</payment_method>
    <payment_method>giropay_ppro</payment_method>
    <payment_method>ideal_ppro</payment_method>
    <payment_method>klarna_ppro</payment_method>
    <payment_method>multibanco_ppro</payment_method>
    <payment_method>oxxo_ppro</payment_method>
    <payment_method>sepa_direct_debit_ppro</payment_method>
    <payment_method>sofort_ppro</payment_method>
    <payment_method>test_ppro</payment_method>
    <payment_method>trustly_ppro</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2022-08-24T16:25:01Z</created_at>
  <updated_at type="dateTime">2022-08-24T16:25:01Z</updated_at>
</gateway>


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


#<Spreedly::Gateway:0x00007f89cda49fa8
@token="WoXNJO9n4tynMQrYBiJq8C24NVq",
@created_at="2022-08-24T16:24:21Z",
@updated_at="2022-08-24T16:24:21Z",
@gateway_type="ppro",
@state="retained",
@name="PPRO",
@credentials={"contractid"=>"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

Bancontact

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.

BLIK

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


Optional Parameter

email The RFC-compliant email address of the account holder

Boleto Bancario

Available country code BR
Minimum transaction amount 0.02 BRL
Maximum transaction amount 250,000.00 BRL
Refund Full and Partial


Parameters

Field Name M/O Description
beneficiary O Bradesco-only The beneficiary of the payment - for example, the merchant’s name and order number
billing_city M City of the billing address (2-30 characters)
billing_post_code M 8 digit post code of the billing address
billing_state M Brazilian state of the billing address; 2 letter-code
billing_street M Street of the billing address (2-50 characters)
due_date O Due date in YYYY-MM-DD format. Defaults to NOW + 3 days
email M RFC compliant email address of the account holder
national_id M Consumer’s CPF or CNPJ tax id
render_type O How the Boleto will be rendered: as PDF or HTML. Default: PDF.
merchant_logo_url O Bradesco-only The URL of the logo to be displayed on the payment page.
Refund Parameters
account_number M The consumer’s bank account number
bank_agency M The consumer’s bank agency number
bank_name M The consumer’s bank name (minimum length of two characters)

giropay

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.

iDEAL

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.

Klarna

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


Parameters

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:

- DIRECT_DEBIT
- DIRECT_BANK_TRANSFER
- PAY_NOW
- PAY_LATER
- PAY_OVER_TIME

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:

- BUY
- RENT
- BOOK
- SUBSCRIBE
- DOWNLOAD
- ORDER
- CONTINUE

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.

Multibanco

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

Oxxo

Available country code MX
Minimum transaction amount None.
Maximum transaction amount 10,000 MXN/transaction
Refund Full, Partial and Multiple Partial


Parameters

Field name M/O Description
due_date O Due date in format YYYY-MM-DD. Defaults to NOW + 3 days
email M RFC compliant email address of the account holder
merchant_logo_url O The URL of the logo to be displayed on the payment page. If not set, it defaults to the PPRO logo.
Refund Parameters
account_number M Consumer’s bank account number
bank_agency M Consumer’s bank agency number
bank_name M Consumer’s bank name (minimum length of two characters)

SEPA

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


Parameters

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

Sofort

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.

Trustly

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


Parameters

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": "ppro_lpm",
        "lpm_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.

Refunds

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.

account_number M Consumer’s bank account number
bank_agency M Consumer’s bank agency number
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

curl https://core.spreedly.com/v1/transactions/KS3oZgWXCfFeirK16anYbijLxR/credit.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <gateway_specific_fields>
          <ppro>
            <merchantrefundid>Your merchant refund id</merchantrefundid>
            <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>
          </ppro>
        </gateway_specific_fields>
      </transaction>'

Preferred Language

Bancontact

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": "ppro_lpm",
        "lpm_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'
               }
         }
    }
  }'

Callbacks

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.