• Documentation
• PPRO

PPRO Gateway Guide

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>

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

#<Spreedly::Gateway:0x000000013a971360
@token="ABd9KrzpqaKp1RkuJQmUXUp0Qqe",
@created_at="2023-07-14T19:31:02Z",
@updated_at="2023-07-14T19:31:02Z",
@gateway_type="ppro",
@state="retained",
@name="PPRO",
@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

Bancontact

Optional Parameter

For branding information, see the Bancontact branding guidelines.

BLIK

giropay

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

Optional Parameter

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

Parameters

For information regarding branding, see the Klarna official website.

Multibanco

SEPA

Parameters

Sofort

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

Parameters

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.

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

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.