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 Certificate Authority; the live environment uses a separate PPRO-managed Certificate Authority.
This section walks you through:
- Generating a CSR
- Working with the PPRO-generated certificate
- Sending the first transaction
- Redirecting the consumer
- Completing a payment as a consumer
- Handling PPRO's push notifications
- Pulling the transaction status after a push notification
- 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.
- If you don't already have one, generate a private key: openssl genrsa -out private.key 4096
- 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:
- Send a payload to PPRO to initiate a transaction, generating a redirect link and POST parameters.
- Redirect the consumer to the redirect link.
- The consumer pays at the payment scheme’s hosted payment page(s).
- The consumer is redirected back to the redirect URL (landing page) as defined in step 1.
- A listener script awaits a notification of the transaction status from PPRO.
- 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:
Field name | M/O | Type | Description |
---|---|---|---|
channel | M | ascii | The channel in the contract to use for the transaction. testchannel for testing and livechannel for production. |
tag | M | ascii | The 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. |
currency | M | ascii | The 3-letter ISO currency code (e.g. EUR) |
amount | M | numeric | The amount to wire in the currency’s smallest representable unit as per ISO4217. Example: For 1 JPY, the amount is 1. For 1 IDR, the amount is 100. |
txtype | M | ascii | The value for transaction processing: TRANSACTION |
login | M | ascii | The login as provided by PPRO |
password | M | ascii | The password as provided by PPRO |
contractid | M | ascii | Defines the merchant for whom PPRO will be processing the transaction |
countrycode | M | ascii | The 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. |
accountholdername | M | utf-8 | The account holder - a minimum of 3 characters, up to 100 characters. |
merchanttxid | O | ascii | The 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. |
sellingpoint | O | ascii | The 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). |
soldservice | O | utf-8 | Service 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). |
merchantredirecturl | M | ascii | The 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: -.\_~:/?#\[]@!$&’()\*+,;=% . |
notificationurl | M | ascii | The URL signalled for the final status of a transaction. The same restrictions as for merchantredirecturl apply.(See Notifications) |
returnmode | M | ascii | As of July 2017, always use the value urlencodeext . |
specin.dynamicdescriptor | O | ascii | The dynamic data to appear on the consumer’s statement (payment method support varies, please discuss with PPRO regarding the use of this parameter ) |
preferredlanguage | O | ascii | The 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&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 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 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:
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
checksumming formula needs to include the MerchantTXID:
sha256(sha256(txid+"."+merchanttxid+"."+finaltimestamp)+"."+notificationsecret)
Note that this is not the standard behavior; 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:
Field name | M/O | Type | Description |
---|---|---|---|
txtype | M | ascii | For pulling the transaction status (GETTXSTATUS). |
login | M | ascii | The login as provided by PPRO. |
password | M | ascii | The password as provided by PPRO. |
contractid | M | ascii | The merchant contractid as provided by PPRO. |
returnmode | M | ascii | As of July 2017, always use the value urlencodeext. |
txid | M | ascii | The txid as provided in the push notification. |
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.
. 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.
Updated 15 days ago