PPRO fact sheet

Adding a PPRO 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_field>terms_accepted</gateway_specific_field>
    <gateway_specific_field>p24_method</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>ideal</payment_method>
    <payment_method>klarna</payment_method>
    <payment_method>klarna_pay_now</payment_method>
    <payment_method>multibanco</payment_method>
    <payment_method>oxxo</payment_method>
    <payment_method>pix</payment_method>
    <payment_method>sepa_direct_debit</payment_method>
    <payment_method>sofort</payment_method>
    <payment_method>trustly</payment_method>
    <payment_method>eps</payment_method>
    <payment_method>p24</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 fourteen 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
Boleto Bancario
Bancontact
BLIK
eps
iDeal
Klarna
Klarna Pay
Multibanco
PIX
P24
SEPA
Sofort
Trustly

Oxxo

Parameters

Payment Method Fields	Description
`email`	RFC compliant email address of the account holder

Gateway Specific Fields	M/O/C	Description
`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. Max logo size: W=1200, H=627. Max URL characters is 255
`due_date`	O	Due date in format YYYY-MM-DD. Defaults to NOW + 3 days

For further reference go to: Payment Method Integration - Oxxo

Boleto Bancario

Parameters

Payment Method Fields	Description
`email`	RFC compliant email address of the account holder
`document_id`	Consumer’s CPF or CNPJ tax id
`zip`	8 digit post code of the billing address
`city`	City of the billing address (2-30 characters)
`state`	Brazilian state of the billing address; 2 letter-code
`address1`	Street of the billing address (2-50 characters)

Gateway Specific Fields	M/O/C	Description
`merchant_logo_url`	O	Bradesco-only The URL of the logo to be displayed on the payment page. Max logo size: W=1200, H=627. Max URL characters is 255.
`due_date`	O	Due date in YYYY-MM-DD format. Defaults to NOW + 3 days
`beneficiary`	O	Bradesco-only The beneficiary of the payment - for example, the merchant’s name and order number
`render_type`	O	How the Boleto will be rendered: as PDF or HTML. Default: PDF

For further reference go to: Payment Method Integration - Boleto Bancario

Bancontact


Available country code	BE
Refund	Full, Partial, Multiple Partial and Over-refund

Parameters

Gateway Specific Field	M/O/C	Description
`app_to_app_url`	O	Custom app URL for redirecting the consumer back to the app, which triggered the payment. Overrides `redirect_url` for mobile flows.

For further reference go to: Payment Method Integration - Bancontact

For branding information, see the Bancontact branding guidelines.

BLIK


Available country code	PL
Refund	Full, Partial and Multiple Partial

Important note: Transactions may change from any state at any time. This change occurs especially from a FAILED to a SUCCEEDED state.

For further reference go to: Payment Method Integration - Blik

eps


Available country code	AT
Refund	Full, Partial and Multiple Partial

For further reference go to: Payment Method Integration - eps

iDEAL


Available country code	NL
Refund	Yes

Parameters

Payment Method Fields	M/O/C	Description
`bic`	O	Valid BIC. It can only contain 8 or 11 alphanumeric characters. Must be an iDEAL issuer’s BIC.

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

For further reference go to: Payment Method Integration - iDEAL

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
Refund	Full, Partial and Multiple partial

Parameters

Payment Method Fields	Description
`billing_address`	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
`shipping_address`	The shipping address. Passed as URL-encoded serialized JSON string. Defaults to transientin.billingaddress Make sure you follow Klarna’s postal code validation rules

Gateway Specific Fields	M/O/C	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.
`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.
`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 further reference go to: Payment Method Integration - Klarna

For information regarding branding, see the Klarna official website.

Klarna Pay


Available country code	AT, CH, DE, SE, GB
Refund	Full, Partial and Multiple partial

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

Parameters using same model as Klarna.

For further reference go to: Payment Method Integration - Klarna Pay

Multibanco


Available country code	PT
Refund	No.

For further reference go to: Payment Method Integration - Multibanco

PIX


Available country code	BR
Refund	Full, Partial and Multiple partial

For further reference go to: Payment Method Integration - PIX

P24


Available country code	PL
Refund	Full, Partial and Multiple partial

Parameters

Gateway Specific Fields	M/O/C	Description
`p24_method`	O	The numeric identifier of the bank. Used for bypassing the P24 HPP and redirecting to a pre-selected banking page. The values for this SPECIN are retrieved via the REQUESTDATA call; this is documented below.
`terms_accepted`	O	Determines whether the GDPR page is displayed before the payment page. Possible values: - 0 (default): The GDPR page is shown - 1: The GDPR page is not shown

For further reference go to: Payment Method Integration - Przelewy24

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

Parameters

One-off payments or first payment in recurring series

Payment Method Fields	M/O/C	Description
`email`	M	Consumer’s email address. It is required to send the direct debit mandate.
`iban`	M	Valid IBAN

One-off payments or first payment in recurring series

Gateway Specific Fields	M/O/C	Description
`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

For further reference go to: Payment Method Integration - SEPA

Sofort


Available country code	AT, BE, CH, DE, ES, GB, IT, NL, PL
Refund	Full, Partial, Multiple Partial and Over refund

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

For further reference go to: Payment Method Integration - Sofort

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
Refund	Full, Partial and Multiple Partial

Parameters

Transaction Fields	Description
`ip`	The consumer’s publicly-routable IPv4.

Gateway Specific Fields	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.
`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 further reference go to: Payment Method Integration - Trustly

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"
      },
      "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.