The PPRO test environment

PPRO requests from you a Certificate Signing Request (CSR) to provision a client SSL certificate and API credentials. The SSL certificate and credentials are bound to one another and cannot be mixed and matched with other clients. The SSL certificate is signed against PPRO’s test environment’s private Certificate Authority; the live environment uses a separate PPRO-managed private Certificate Authority.

This section walks you through:

  1. Generating a CSR
  2. Working with the PPRO-generated certificate
  3. Trusting PPRO's Certificate Authority
  4. Sending the first transaction
  5. Redirecting the consumer
  6. Completing a payment as a consumer
  7. Redirecting the consumer to a landing URL
  8. Handling PPRO's push notifications
  9. Pulling the transaction status after a push notification
  10. Optional: Testing with a real payment scheme's test host

1. Generating a CSR

A Certificate Signing Request (CSR) is required to communicate with PPRO’s API endpoint. API payloads will always fail if the incorrect PPRO-issued SSL client certificate and credential pair are not provided.

OpenSSL / LibreSSL commonly uses the steps below. Modify them according to your platform’s requirements (Windows etc.).

Use RSA with a key size of greater than or equal to 2048. We recommend a key size greater than 2048-bit (4096 bit is highly encouraged) if your infrastructure can use it.

  1. If you don't already have one, generate a private key: openssl genrsa -out private.key 2048
  2. Generate a Certificate Signing Request: openssl req -new -sha256 -key private.key -out my.csr



For step 2 above: During Certificate Signing Request creation, enter information into all these fields:

  • Country Name
  • State or Province Name
  • Locality Name
  • Organization Name
  • Contact Name - make sure this is the contact name of the operations team or another responsible team or person.
  • Email Address - make sure this is the email address of the operations team or another responsible team or person.

PPRO cannot sign the certificate unless the above fields are complete.

There are no limitations regarding the values for the key or CSR in the test environment.

Please confirm if any DN data from the CSR needs to be preserved when issuing a client SSL certificate. Note that PPRO also appends a contact email to client SSL certificates.

Send the resulting CSR to [email protected] for provisioning of the client SSL certificate.

2. Working with the PPRO-generated certificate

The PPRO team uses the CSR provided to create a certificate; PPRO also provides its CA.

The following example highlights how to create a .pem file to use for communicating with PPRO. Note that your environment may have different requirements for posting payloads to PPRO.

This involves concatenating the PPRO-provided certificate with the private key as-generated in the previous step.

cat ppro_provided.crt customer.key > customer.crt
//Converting to a pfx or p12 is recommended for ease of use, please see Microsoft's documentation on the topic

type ppro_provided.crt customer.key > customer.crt



Each environment has its own unique requirements. Make sure you adjust these steps accordingly.

3. Trusting PPRO’s certificate authority

PPRO uses its own in-house private certificate authority for signing both test and production client SSL certificates.

The PPRO integration team will provide PPRO’s Test Environment Certificate Authority (CA) when providing the client SSL Certificate. The live environment CA will be provided when a live SSL certificate is generated and needs to be trusted.

4. Sending the first transaction

Anatomy of a transaction

Once the .pem file is in-hand, it is time to send the first transaction. Below are the basic components of a transaction:

  1. Send a payload to PPRO to initiate a transaction, generating a redirect link and POST parameters.
  2. Redirect the consumer to the redirect link.
  3. The consumer pays at the payment scheme’s hosted payment page(s).
  4. The consumer is redirected back to the redirect URL (landing page) as defined in step 1.
  5. A listener script awaits a notification of the transaction status from PPRO.
  6. The listener script, when receiving a notification, using the notification’s data to get the status of the transaction

The above steps do not include notifying the merchant at any point in the lifecycle. This is outside the scope of PPRO’s activity - You must process PPRO’s notifications and use these to notify merchants.

Sending the transaction’s payload to PPRO

The PPRO system anticipates receiving the payload via HTTP post. The data in the payload must be URL-encoded and sent via HTTPS.

The endpoint for receiving transactions on the PPRO test system is

We require connections via TLS 1.2 and strong ciphers. Trust PPRO’s Certificate Authority in order to send transactions on PPRO’s test and live environments.

Your PPRO integration manager will provide a copy of the relevant Certificate Authority files for test and live to facilitate these communications.

A list of PPRO’s basic parameters for a payment transaction are as follows:

Field nameM/OTypeDescription
channelMasciiThe channel in the contract to use for the transaction. testchannel for testing and livechannel for production.
tagMasciiThe tag selects the payment method in the channel used for the transaction. You get a list of valid tags from our boarding team as a part of the account credentials.
currencyMasciiThe 3-letter ISO currency code (e.g. EUR)
amountMnumericThe amount to wire in the currency’s smallest representable unit as per ISO4217.


For 1 JPY, the amount is 1.

For 1 IDR, the amount is 100.
txtypeMasciiThe value for transaction processing: TRANSACTION
loginMasciiThe login as provided by PPRO
passwordMasciiThe password as provided by PPRO
contractidMasciiDefines the merchant for whom PPRO will be processing the transaction
countrycodeMasciiThe 2-letter ISO country code from which the consumer will be paying. This also typically aligns with the locale of the payment method, as many methods are only valid in a single country. For details, see payment method-specific documentation and the PPRO FAQ, as schemes may have multiple valid values.
accountholdernameMutf-8The account holder - a minimum of 3 characters, up to 100 characters.
merchanttxidOasciiThe transaction identifier. Allowed characters: [a-zA-Z0-9.,- _].
 Maximum of 40 characters. Uniqueness is not enforced.

It is your responsibility to communicate the merchant’s transaction identifier if required.
sellingpointOasciiThe point of sale of the item (for your use) – up to 50 characters.

Informational field only. Not carried through to the payment scheme. It is echoed back to you at transaction completion (FAILED or SUCCEEDED).
soldserviceOutf-8Service sold (for your use) - up to 50 characters.

Informational field only that is not carried through to the payment scheme. It is echoed back to you at transaction completion (FAILED or SUCCEEDED).
merchantredirecturlMasciiThe URL the consumer will be redirected to after the transaction or in case of abort/failure.

Minimum length 13 characters. Maximum length 255 characters.
Must start with http:// or https://.
Allowed characters are the ascii range [a-zA-Z0-9] and the following characters: -.\_~:/?#\[]@!$&’()\*+,;=%.
notificationurlMasciiThe URL signalled for the final status of a transaction. The same restrictions as for merchantredirecturl apply.

(See Notifications)
returnmodeMasciiAs of July 2017, always use the value urlencodeext.
specin.dynamicdescriptorOasciiThe dynamic data to appear on the consumer’s statement

(payment method support varies, please discuss with PPRO regarding the use of this parameter )
preferredlanguageOasciiThe 2-character ISO language code is preferred if available.

The example below shows a URL-encoded string containing the parameters above:

tag=test&countrycode=DE¤cy=EUR&amount=1055&txtype=TRANSACTION&login=MYLOGIN&password=MYPASSWORD&contractid=MYMERCHANTCONTRACT&channel=testchannel&¬ &specin.dynamicdescriptor=DynDescriptor&accountholdername=Tester+Tester&merchanttxid=ABC123&preferredlanguage=en&returnmode=urlencodeext

Once the payload is successfully sent to PPRO, the system returns a set of parameters to redirect the consumer as a parameterized HTTP response.

5. Redirecting the consumer

The HTTP response of the transaction call will return the following parameters:

  • rs
  • cs

These four parameters are then constructed together like in the example below to create the URL to which the consumer is redirected. The period in the sample is used to indicate concatenation.

$REDIRECTURL . ‘&rs=’ . $rs . ‘&cs=’ . $cs

Note that the $REDIRECTURL already includes the string ?tx=1234567890 where 1234567890 is the PPRO-assigned transaction identifier.

Below is a correctly-constructed redirect URL. The parameter tx is included in the REDIRECTURL.

A consumer clicking/tapping or being redirected to this URL arrives at the landing page of the payment brand to initiate a payment.

The REDIRECTSECRET can be optionally stored to validate PPRO as the source of the transaction. Please see the Payment Gateway section for more information.

6. The consumer completes the payment

This section only covers integrating against the testing brand called ‘dumbdummy’. This is also the value of the tag parameter.

The dumbdummy simulator enables integrators to test the majority of scenarios for payment, as well as delay delivery of the push notification with or without a delay. PPRO provides API-level simulators for all schemes within its ecosystem, a full list of possible values for tag will be provided.

The remainder of this section will assume that you selected a successful response.

7. Redirecting the consumer to a landing URL

Once the payment is completed (either successfully or failed), the consumer is redirected to the merchant redirect URL. Regardless of the result, the transaction id is available in the GET parameters and triggers either a success or error page. This txid can then be used to pull the status of the transaction at this point (one time) prior to arrival of the notification. This one-time pull is useful if there's business logic that can be more quickly triggered than by waiting for the notification to arrive very shortly after the status change.

We recommend validating that the consumer redirect to the landing url (merchantredirecturl) was from PPRO. You can do this with a sample hash:

If (cs == (sha256(sha256(TXID+"."+REDIRECTSECRET)+"."+SHAREDSECRET)))

Then OK

Else NO

The SHAREDSECRET is provided with your PPRO credentials. The CS is appended to the end of the merchantredirecturl.

If the consumer abandons the transaction (e.g. by closing the browser window), the redirectURL is never triggered. In this scenario, wait for a push notification from PPRO (described in this section) to get the status of the abandoned transaction. PPRO considers this a ‘timeout’ in its nomenclature.

8. Handling PPRO’s push notifications

Once PPRO knows the transaction status, it sends a push notification to the notification URL as provided in the original transaction. PPRO does not send any push notifications until there is a status change. This means that a transaction can be in a PENDING status for some time depending on the behavior of the payment scheme. Some schemes could move the payment from PENDING to SUCCEEDED in a few minutes, some in a few days. Each scheme has a defined time limit until the transaction is considered abandoned and timed out.

The following parameters are posted to the listener script:




A checksum can be calculated using the data above plus the notification secret key that PPRO provides. If this checksum passes, it is confirmed that the notification came from PPRO and not a third party.

Below is the formula for calculating the hash:


If this hash matches the value in sha256hash as posted by PPRO, then it is assumed to be safe to pull the status.

However, successful receipt of the hash must be confirmed in the first 4 kilobytes of the HTML body of the script with the text “RECEIVED OK” (without quotes, all caps) and the HTTP status response code 200.

If this confirmation step is not followed, PPRO continues to resend the notification to the same URL once every approximately 15 minutes up to 191 additional attempts. The URL defined for a transaction’s notification cannot be changed once the transaction is initialized.



Customers can opt to also return the merchanttxid in notifications.

If this option has been opted in, then the sha256 checksumming formula needs to include the MerchantTXID:


Note that this is not the standard behavior; it needs to be requested and approved.

9. Pulling the transaction status after a push notification

The status of a transaction is considered to be unchanged until PPRO sends a push notification. Polling the transaction status without having received a notification is not allowed.

The following parameters are required when requesting a transaction status:

Field nameM/OTypeDescription
txtypeMasciiFor pulling the transaction status (GETTXSTATUS).
loginMasciiThe login as provided by PPRO.
passwordMasciiThe password as provided by PPRO.
contractidMasciiThe merchant contractid as provided by PPRO.
returnmodeMasciiAs of July 2017, always use the value urlencodeext.
txidMasciiThe txid as provided in the push notification.

Post the parameters URL-encoded to the following endpoint:

The response is a URL-encoded string with the result of the transaction. It also includes any other relevant transaction data. See the following sample:




The response varies by payment method. Refer to the Payment Methods documentation for more details.

10. Optional: Testing with a real payment scheme’s test host

By default, all payment schemes on PPRO’s test host use the PPRO-created ‘click-through’ simulators to simulate a consumer redirect and asynchronous workflow. These simulators are a 1:1 match of how PPRO’s live API behaves, but they do not simulate a real transaction as a consumer would see it.

PPRO allows you to simulate a real payment scheme on its test host via the Sofort scheme. By using the tag ‘directpay’, you can test a full end-to-end payment as a consumer would see it. This test can only be undertaken on the PPRO and SOFORT test hosts. After being redirected to SOFORT, you can enter the following bank code: ‘88888888’ to test with the test bank. The rest of the requested data can be dummy data.

Technical Approval (sign off or certification)

Once the integration is completed and ready to go live, provide PPRO with the following information in a request to [email protected]:

  • PPRO Transaction IDs (txids) of the following:
    • 2 Succeeded Transactions
    • 1 Failed UserAbort
    • 2 Failed Timeout

One of the two timeout transactions will be forced into a SUCCEEDED status. This tests your ability to handle a scenario where a transaction succeeds after an initial failure, for example, due to a technical issue at the payment scheme. This SUCCEEDED after FAILED scenario is further documented in Integration recommendations.

PPRO will then validate the transactions in its logs. We pay particular attention to whether or not a transaction’s notificationurl is correctly processing push notifications. This is a common failure point during technical approval. Make sure that the notificationurl is validating the successful receipt of notification. Learn more about notifications from the Notifications Notifications section. For more details about handling push notifications, check this section.

PPRO does not define client UAT or other certification requirements. We rely on our clients to define further UAT or testing requirements.

Live Credentials

Once technical approval is given, a confirmation email will be sent. This email triggers PPRO’s account management teams to reach out to provision a first live merchant. Note that live credentials are not provisioned without a first merchant ready to board.

PPRO’s account management/boarding team will also reach out requesting a CSR for PPRO’s live environment.

Please confirm if any DN (distinguished name) data from the CSR needs to be preserved when issuing a client SSL certificate. Note that PPRO also appends a contact email to client SSL certificates.