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 Certificate Authority; the live environment uses a separate PPRO-managed Certificate Authority.

This section walks you through:

1. Generating a CSR
2. Working with the PPRO-generated certificate
3. Sending the first transaction
4. Redirecting the consumer
5. The consumer completes the payment
6. Redirecting the consumer to a landing url
7. Handling PPRO’s push notifications
8. Pulling the transaction status after a push notification
9. 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 4096.

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

👍

Note

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

👍

Note

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

3. 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 https://testapi.girogate.de.

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:

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&merchantredirecturl=https%3A%2F%2Fmyurl.com%2Fsuccess.php¬ificationurl=https%3A%2F%2Fmyurl.com%2Fnotification.php &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.

4. Redirecting the consumer

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

• REDIRECTURL
• REDIRECTSECRET
• 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.

https://testapi.girogate.de/ti/test?tx=1234567890&rs=hz0pNrqQp01w2a2hH2dVhEA74GGrJEVE&cs=cfbded036039ebfaddffe550a54037500e970766de344c17c22b71968d76f6ed

A consumer clicking/tapping or being redirected to this URL via a GET request 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.

5. 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.

6. 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.

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

sha256hash

txid

finaltimestamp

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:

sha256(sha256(txid+"."+finaltimestamp)+"."+notificationsecret)

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.

👍

Note

Customers can opt to also return the merchanttxid in notifications.

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

sha256(sha256(txid+"."+merchanttxid+"."+finaltimestamp)+"."+notificationsecret)

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

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

Post the parameters URL-encoded to the following endpoint: https://testapi.girogate.de

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:

REQUESTSTATUS=SUCCEEDED&STATUS=SUCCEEDED&MERCHANTTXID=ABC123&FUNDSSTATUS=NOT_EXPECTED&FLAGS=&TXID=95018005&ERRMSG=&CHANNEL=testchannel&TAG=dumbdummy&REDIRECTSECRET=90H8c101AV8A8FWLTlj4aZ4Yqw3b8uhk&SPECOUT.PAYMENTPURPOSE=1UQDEWA&SPECOUT.SRCACCOUNTHOLDER=Former Glory&SPECOUT.SRCACCOUNTNUMBER=322205970&SPECOUT.SRCBANKCODE=70025175&SPECOUT.SRCBANKNAME=HypoVereinsbank Penzberg&SPECOUT.SRCBIC=HYVEDEMM643&RAND3089298895=bc1070cf58dfd990b796bda3bfdb0fd7e1f1826d&SPECOUT.SRCIBAN=DE25700251750322205970

👍

Note

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

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

By default, most 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.

A limited number of payment methods provide their own test host for testing, these are referred to as Sandboxes, they can give a test user an idea of the shopper's experience when paying with the payment method. PPRO can provide access to the available sandboxes on request. PPRO will provide an additional contractid to be used for sandbox testing. Please note - not all payment methods provide sandboxes and as the sandboxes are scheme hosted PPRO cannot promise that they will be working as intended.

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.