PPRO fact sheet

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>
        <contract_id>Your contract id</contract_id>
      </gateway>'

<gateway>
  <token>RicQLGz0JoFtXQpb4CfDeK2cuPH</token>
  <gateway_type>ppro</gateway_type>
  <name>PPRO</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <contract_id>Your contract id</contract_id>
  <characteristics>
    <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>
  </characteristics>
  <credentials>
    <credential>
      <name>contract_id</name>
      <value>Your contract id</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>merchant_refund_id</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_field>merchant_logo_url</gateway_specific_field>
    <gateway_specific_field>render_type</gateway_specific_field>
    <gateway_specific_field>beneficiary_name</gateway_specific_field>
    <gateway_specific_field>beneficiary_id</gateway_specific_field>
    <gateway_specific_field>beneficiary_address</gateway_specific_field>
    <gateway_specific_field>beneficiary_country_code</gateway_specific_field>
    <gateway_specific_field>refund_bank_name</gateway_specific_field>
    <gateway_specific_field>refund_account_number</gateway_specific_field>
    <gateway_specific_field>refund_bank_agency</gateway_specific_field>
    <gateway_specific_field>due_date</gateway_specific_field>
    <gateway_specific_field>app_to_app_url</gateway_specific_field>
    <gateway_specific_field>shopper_reference</gateway_specific_field>
    <gateway_specific_field>company</gateway_specific_field>
    <gateway_specific_field>tax_amount</gateway_specific_field>
    <gateway_specific_field>payment_method_category</gateway_specific_field>
    <gateway_specific_field>emd</gateway_specific_field>
    <gateway_specific_field>hpp_title</gateway_specific_field>
    <gateway_specific_field>logo_url</gateway_specific_field>
    <gateway_specific_field>order_items</gateway_specific_field>
    <gateway_specific_field>customer</gateway_specific_field>
    <gateway_specific_field>purchase_type</gateway_specific_field>
    <gateway_specific_field>background_images</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>bancontact</payment_method>
    <payment_method>blik</payment_method>
    <payment_method>boleto_bancario</payment_method>
    <payment_method>giropay</payment_method>
    <payment_method>ideal</payment_method>
    <payment_method>klarna</payment_method>
    <payment_method>multibanco</payment_method>
    <payment_method>oxxo</payment_method>
    <payment_method>sepa_direct_debit</payment_method>
    <payment_method>sofort</payment_method>
    <payment_method>trustly</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-07-14T19:31:01Z</created_at>
  <updated_at type="dateTime">2023-07-14T19:31:01Z</updated_at>
</gateway>

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

Fields	Payment Method
`email`	Oxxo & Boleto Bancario
`document_id`	Boleto Bancario
`zip`	Boleto Bancario
`city`	Boleto Bancario
`state`	Boleto Bancario
`address1`	Boleto Bancario

Option Gateway Specific Fields	Payment Method
`merchant_logo_url`	Oxxo & Boleto Bancario
`due_date`	Oxxo & Boleto Bancario
`beneficiary`	Boleto Bancario
`render_type`	Boleto Bancario

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

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: 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 - CONTINUEIt 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.

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, Multiple Partial and Over refund

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
`shopper_reference`	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.
`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.

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.


`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>
        <gateway_specific_fields>
          <ppro>
            <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>
          </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": "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.