API Quick Start Sending a Payment v1.4

Transcription

1 PPRO Financial Ltd, 23 Hanover Square, London W1S 1JB, UK API Quick Start Sending a Payment v1.4 Table of Contents Introduction... 2 Step 1 Create a CSR... 3 Step 2 Create a Certificate... 3 Step 3 Sending a Transaction... 4 Anatomy of a transaction... 4 Sending the transaction payload to PPRO... 4 Redirecting the Shopper... 7 Shopper Confirming Payment... 7 Shopper Redirect to Landing URL... 8 Listener Script Notification... 8 Getting the Transaction s Status... 9 Testing with a real Payment Scheme s Test Host... 9 SUCCEEDED after FAILED Note... 9 PPRO Financial Ltd, 23 Hanover Square, London, W1S 1JB, UK, Tel , Fax info@ppro.com, Managing Director: Simon Black, Company Registration No:

2 - 2 - Introduction This document is an unofficial quick start guide for clients looking to create quick, one-off implementations of the PPRO APIs. This document is not a substitute for the Girogate integration guide nor does it call all use cases [refunds, CSV file reporting etc.] or payment brands.

3 - 3 - Step 1 Create a CSR In order to communicate with PPRO s APIs, a CSR is required for PPRO to create a certificate for sending API payloads. API payloads will always fail if the incorrect certificate & credential pair is not provided. The steps below are commonly used by OpenSSL / LibreSSL. Please modify the below per your platform s requirements (windows etc.). Please use RSA with a key size of greater than or equal to The sample below uses a 4096 bit key as reference. 1. First generate a private key (if you don t already have one) a. openssl genrsa -out private.key Then generate the CSR a. openssl req -new -sha256 -key private.key -out my.csr There are no limitations regarding the values for the key or CSR on the test environment. Step 2 Create a Certificate The PPRO team will use the CSR provided to create a certificate; PPRO will also provide its CA. The following example highlights how to create a PEM file for use with communicating with PPRO. Note that the environment used by a client may have different requirements for posting payloads to PPRO. This involves concatenating the PPRO-provided certificate with the private key as-generated in step one. cat ppro_provided.crt customer.key > pemfile.pem Note that each environment has its own basic requirements. Please adjust these steps accordingly. The rest of this document will work on the assumption of using the PEM file. PPRO will also provide its CA for validation purposes.

4 - 4 - Step 3 Sending a Transaction Anatomy of a transaction Once the PEM file is in-hand, it is time to send the first transaction. A transaction ultimately has a few basic components: 1.) The payload sent to PPRO to initiate a transaction, generating a redirect link + post parameters 2.) The redirection of the shopper to the redirect link 3.) The shopper paying at the payment scheme s hosted payment page(s) 4.) The shopper being redirected back to the redirect URL (landing page) as defined in step 1 5.) A listener script awaiting a notification from PPRO of the status of the transaction 6.) The listener script, when receiving a notification, using the notification s data to get the status of the transaction The above steps exclude the notification of a merchant by our integrated client as this lifecycle is out of PPRO s purview. Sending the transaction payload to PPRO The PPRO system anticipates receiving the payload via HTTP post. The data in the payload must be urlencoded and sent via HTTPS. The endpoint for receiving transactions on the PPRO test system is as follows: Note that connections are recommend via TLS 1.2 and strong cyphers, as TLS versions older than 1.1 are set to be deprecated. Please also note that PPRO s Certificate Authority must be trusted in order to send transactions both on PPRO s test and live environment your PPRO integration manager will provide a copy of the relevant CA files for test and live to facilitate these communications.

5 - 5 - A list of PPRO s basic parameters for a payment transaction follows. Field name M/O Type Description channel M ascii Channel within 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 that will be used for this transaction. The client will receive a list of valid tags from our boarding team as 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 (e.g. cents). Txtype M ascii For transaction processing: TRANSACTION For transaction status pull: GETTXSTATUS 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 of the country in which the payment in- strument is issued/operated (e.g. DE). For details see payment method specific documentation. accountholdername M utf-8 The account holder - up to 100 characters. merchanttxid O ascii The client s transaction identifier, allowed characters are: [a-za-z0-9.,- _]. Up to 40 characters, uniqueness is not enforced and the client s respon- sibility in the context of a contract. sellingpoint O ascii The point of sale of the item (for client use) up to 50 characters. soldservice O utf-8 Service sold (for client use) - up to 50 characters. merchantredirecturl M ascii The URL the customer will be redirected to after the transaction or abort/failure (up to 255 chars) notificationurl M ascii The URL that will be signalled in case od a final status for a transaction, up to 255 characters (see Notifications) returnmode M ascii As of July 2017, please always use the value urlencodeext dynamicdescriptor O ascii The dynamic data to appear on the shopper s statement (support varies, please discuss with PPRO the use of this parameter) preferredlanguage O ascii The 2-character ISO language code to prefer if available A URL-encoded string of the above would look as follows: tag=dumbdummy&countrycode=de&currency=eur&amount=1055&txtype=transaction&login=mylogin& password=mypassword&contractid=mymerchantcontract&channel=testchannel&merchantredirecturl= https%3a%2f%2fmyurl.com%2fsuccess.php&notificationurl=https%3a%2f%2fmyurl.com%2fnotification.php &soldservice=stuff&dynamicdescriptor=dyndescriptor&accountholdername=tester+tester&merchanttxid=ab C123&preferredlanguage=EN&sellingpoint=Sold+Here&returnmode=urlencodeext

6 - 6 - The above appears as follows if formatted in JSON: { "tag": "dumbdummy", "countrycode": "DE", "currency": "EUR", "amount": "1055", "txtype": "TRANSACTION", "login": "MYLOGIN", "password": "MYPASSWORD", "contractid": "MYMERCHANTCONTRACT", "channel": "testchannel", "merchantredirecturl": "https%3a%2f%2fmyurl.com%2fsuccess.php", "notificationurl": "https%3a%2f%2fmyurl.com%2fnotification.php", "soldservice": "Stuff", "dynamicdescriptor": "DynDescriptor", "accountholdername": "Tester+Tester", "merchanttxid": "ABC123", "preferredlanguage": "EN", "sellingpoint": "Sold+Here", "resturnmode": "urlencodeext", } Note the JSON sample above is presented for readability purposes only; the API only supports posting of data via a urlencoded string as shown above the JSON sample. Once the payload is successfully sent to PPRO, the system will return a set of parameters to redirect the shopper as a parameterized HTTP response.

7 - 7 - Redirecting the Shopper The HTTP response of the transaction call will return the following parameters: REDIRECTURL REDIRECTSECRET rs cs These four parameters are then constructed together as follows to create the URL to which the shopper will be redirected. A period is used in the following sample to indicate concatenation. $REDIRECTURL. &REDIRECTSECRET=. $REDIRECTSECRET. &rs=. $rs. &cs=. $cs Note that the $REDIRECTURL already includes the string?tx= where is the PPROassigned transaction identifier. A sample, correctly-constructed redirect URL follows. Note the parameter tx is included in the REDIRECTURL. WmN3BnGG&rs=hz0pNrqQp01w2a2hH2dVhEA74GGrJEVE&cs=cfbded036039ebfaddffe550a e de344c17c22b71968d76f6ed A shopper clicking or being redirected to this URL will land on the landing page of the payment brand to commit a payment. Shopper Confirming Payment This guide will only cover 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 a payment, as well as delay delivery of the push notification with or without a delay. The remainder of this guide will assume that a successful response was selected.

8 - 8 - Shopper Redirect to Landing URL Once the payment has been successfully committed (or failed), the shopper will be redirected to the merchant redirect URL. Regardless of the result, the transaction id will be available in the POST parameters upon the success or error page being triggered. This txid is then to be used to pull the status of the transaction. It is also recommended to validate that the shopper redirect to the landing url (merchantredirecturl) was from PPRO. This is done with a sample hash: If (cs == (sha256(sha256(txid+. +REDIRECTSECRET)+"."+SHAREDSECRET+) Then OK Else NOK The SHAREDSECRET is provided with your PPRO credentials. CS is appended to the end of the merchantredirecturl. Listener Script Notification Once the transaction s status is known by PPRO, a push notification will be sent to the notification URL asprovided in the original transaction. PPRO will 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. The following parameters will be posted to the listener script: sha256hash txid finaltimestamp A checksum can be calculated using these data plus the notification secret key provided by PPRO. If this checksum passes, it is confirmed that the notification came from PPRO and not a third party. The formula for calculating the hash follows: sha256(sha256(txid+"."+finaltimestamp)+"."+notificationsecret) If this hash matches the value in sha256hash as-posted by PPRO, it is time to get the transaction s status.

9 - 9 - Getting the Transaction s Status The following parameters are required when requesting a transaction s status: Field name M/O Type Description txtype M ascii For transaction processing: TRANSACTION For transaction status pull: 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, please always use the value urlencodeext txid M ascii The txid as-provided in the push notification The parameters are to be posted URL encoded to the following endpoint: The response will be a urlencoded string with the result of the transaction, as well as any other relevant transaction data. A sample follows: REQUESTSTATUS=SUCCEEDED&STATUS=SUCCEEDED&MERCHANTTXID=ABC123&FUNDSSTATUS=NOT_EXPECT ED&FLAGS=&TXID= &ERRMSG=&CHANNEL=testchannel&TAG=dumbdummy&REDIRECTSECRET=90H 8c101AV8A8FWLTlj4aZ4Yqw3b8uhk&SPECOUT.PAYMENTPURPOSE=1UQDEWA&SPECOUT.SRCACCOUNTHOLD ER=Former Glory&SPECOUT.SRCACCOUNTNUMBER= &SPECOUT.SRCBANKCODE= &SPECOUT.SRCBAN KNAME=HypoVereinsbank Penzberg&SPECOUT.SRCBIC=HYVEDEMM643&RAND =bc1070cf58dfd990b796bda3bfdb0fd7e1f18 26d&SPECOUT.SRCIBAN=DE Note that the response per payment brand varies, please refer to PPRO s complete API spec for more details. Testing with a real Payment Scheme s Test Host By using the tag directpay (now known as SOFORTÜBERWEISUNG or SOFORT), a client can test a full end-toend payment as a shopper would see it. Note that this test can only be undertaken on PPRO s and SOFORT s test hosts. After redirecting to SOFORT, the tester can enter the following bank code: to test with the dummy bank. The rest of the requested data can be dummy data. SUCCEEDED after FAILED Note Note that by their design, some payment schemes can return a SUCCEEDED status after a failed status. PPRO asks its customers to account for this case (and all related logic on the shopper side) while integrating.