Pensio Payment Gateway Merchant API Integration Guide 10. Jan. 2012 Copyright 2011 Pensio ApS
Table of Contents Revision History 5 Concept 7 Protocol 7 API base url 7 Authentication 7 Method calls 7 API/index 7 API/login 7 API/payments 8 Optional parameters 8 Return values 8 Example 8 Example XML Result 8 API/captureReservation 10 Required parameters 10 Optional parameters 10 Example 10 Orderlines Example 10 Example XML Result 10 API/releaseReservation 12 Required parameters 12 Example 12 Example XML Result 12 API/refundCapturedReservation 13 Required parameters 13 Optional parameters 13 Example 13 Example XML Result 13 API/splitTransaction (Deprecated) 15 Required parameters 15 Example 15 Example XML Result 15 API/setupSubscription 18 Required parameters 18 Optional parameters 18 Ignored parameters 18 Example 18 API/captureRecurring 19 Required parameters 19 Optional parameters 19 Example 19 Example XML Result 19 API/preauthRecurring 21 2 of 41
Required parameters 21 Optional parameters 21 Example 21 Example XML Result 21 API/fundingList 23 Required parameters 23 Optional parameters 23 Example 23 Example XML Result 23 API/fundingDownload 25 Required parameters 25 Optional parameters 25 Example 25 Example Result 25 Content description 25 API/reservationOfFixedAmountMOTO 27 Required parameters: 27 Required Credit Card parameters (normal): 27 Required Credit Card parameters (token): 27 Optional parameters: 27 Mandatory fraud detection parameters: 27 Optional fraud detection parameters: 28 Example (based on new credit card) 28 Example (based on credit card token) 28 Example XML Result 28 Example XML Error (when using an unknown credit card token) 29 API/credit 30 Required parameters: 30 Required Credit Card parameters (normal): 30 Required Credit Card parameters (token): 30 Optional parameters: 30 API/getTerminals 31 Example XML Output 31 API/getInvoiceText 32 Required parameters 32 Example 32 Example XML Result 32 Explanation of error cases 33 API/createPaymentRequest 35 GET Example: 35 Return xml example 35 Parameters additionally available for createpaymentrequest 35 API/createInvoiceReservation 37 Required parameters: 37 Optional parameters: 37 Mandatory parameters for invoice payments: 37 3 of 41
Parameters for invoice payment identification: 37 GET Example: 38 Return xml example 38 Detailed Response XML descriptions: 40 ThreeDSecureResult: 40 4 of 41
Revision History Date 13. Jul. 2009 Added revision history table Corrected http to https Changes 4. Aug. 2009 Corrected the example result of capturerecurring 9. Sep. 2009 CreatedDate and UpdatedDate to returned Transactions 24. Nov. 2009 Added API/preauthRecurring 26. Nov. 2009 Added info about CardStatus 17. Dec. 2009 Added <Result> to all api responses 12. Feb. 2010 Changed old term 'transaction' with new term 'payment' where possible. Added MO/TO section. 16. Mar. 2010 Added info about auto reauth 4. May. 2010 Added 'payment_status' to payments API call 25. May. 2010 Added note about refunds not being available on all payments 2. Jun. 2010 Updated example xml Added fundinglist documentation 23. Jun. 2010 Added fraud detection parameters to response XML 7. Sep. 2010 Added payment_source to MO/TO reservation method to allow additional non 3D Secure ecommerce payments. 28. Sep. 2010 Added updated description of the funding download CSV file. Updated API response examples with ReconciliationIdentifiers. General update of examples 27. Oct. 2010 Added explanation of error cases 19. Jan. 2011 Added fraud/avs info to moto call 14. Feb. 2011 Minor correction on fundinglist example 15. Feb. 2011 Added orderlines to capture 17. Feb. 2011 Added data types to fundingdownload description 15. Mar. 2011 Added getinvoicetext 28. Mar. 2011 Added Example to getinvoicetext 10. May. 2011 Added API/login method 11. May. 2011 Added API/getTerminals method General clean up of document 03. Oct. 2011 Added documentation for createpaymentrequest 05. Oct. 2011 Added description for callback url send to createpaymentrequest 5 of 41
Date Changes 20. Oct. 2011 Added documentation for createinvoicereservation 25. Oct. 2011 Documented the new elements in the API response (ThreeDSecureResult, BlacklistToken, PaymentNature, PaymentNatureService) 21. Dec. 2011 Documented new elements in the API response (CustomerInfo/UserAgent, CustomerInfo/IpAddress) Added documentation for credit api method 6 of 41
Concept When the orders are being paid by the customers they end up as a payment in the Pensio Payment Gateway. From there they must be handled by you either using our browser based Merchant Information Interface or by integrating our API in your current IT solution. Protocol The API uses normal HTTPS traffic for communication. This should pose no problems with firewalls, it should be easy to integrate into anything and the traffic is encrypted. Since we use HTTPS you can access all the actions from your browser to inspect the return values and formatting of the responses. API base url https://{yourshopname}.pensio.com/merchant/api/ https://testgateway.pensio.com/merchant/api/ Authentication To authenticate with our system your IT system must use normal HTTP authentication. You can find numerous examples in numerous programming languages on the web on how to do this. The username and password for your shops is: Username: Password: {API_USERNAME} {API_PASSWORD} Method calls The API has a number of methods you can call on it. All of these are invoked with simple HTTP requests and their responses are simple XML which can be parsed easily by your IT system. API/index This method requires no authentication and is presented for your system to test the connection to our system. API/login This method requires authentication and is presented for your system to test the username/password before doing any real API calls. 7 of 41
API/payments This action is used to get a list of payments. This action takes some optional parameters which will limit the number of results. Optional parameters shop terminal The shop that you want to get payments for default is to show payments from all the shops enabled for the API user. The terminal you want to get payments for detault is to show payments for all terminals. string string transaction_id The id of a specific payment. [0 9a f]{1,32} shop_orderid payment_status Return values The shop orderid passed in by the shop when the payment was created. The latest status of the payments seached for, e.g. 'preauth', 'captured','refunded','released' etc. See the status dropdown in the orders search filter in the Merchant Information Interface for more. Below is an explanation of some of the non obvious values in the returned xml. [a za Z0 9]{1,100} string <CardStatus> <RecurringMaxAmount> <TransactionInfo> <FraudRiskScore> Gives an indication wether a card is expired or is about to expire. Expired is returned for expired credit cards, SoonExpired for cards that will expire in the next 3 months and Valid for everything else. If no creditcard has been set on the payment yet, it will be NoCreditCard The maximum amount that can be captured from a Recurring Payment The payment infos that was submitted to the payment form. Key will be the tagname and the content the value. When fraud detection is enabled for the terminal, this value will contain the risk in percentage (0.00 100.00) of this order being a fraud attempt Expired SoonExpired Valid NoCreditCard float Node float Example https://gateway.pensio.com/merchant/api/payments/?terminal=terminal+1 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/transactions</Path> <ErrorCode>0</ErrorCode> <ErrorMessage /> </Header> <Body> 8 of 41
<ResultFilter /> <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>captured</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1.00</ReservedAmount> <CapturedAmount>1.00</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo> <UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent> <IpAddress>127.127.127.127</IpAddress> </CustomerInfo> <ReconciliationIdentifiers> <ReconciliationIdentifier> <Id>f4e2533e c578 4383 b075 bc8a6866784a</id> <Amount currency="978">1.00</amount> <Type>captured</Type> <Date>2010 09 28T12:00:00+02:00</Date> </ReconciliationIdentifier> </ReconciliationIdentifiers> </Transaction> </Transactions> </Body> </APIResponse> 9 of 41
API/captureReservation When the funds of a payment has been reserved and the goods are ready for delivery your system should capture the payment. By default auto reauth is enabled for all terminals, which means if the capture fails the system will automatically try to reauth the payment and then capture again. Reauthed payments, however, do not have cvv or 3d secure protection, which means the protection against chargebacks is not as good. If you wish to disable auto reauth for one or more of your terminals please contact Pensio. Required parameters transaction_id The id of a specific payment. [0 9a f]{1,32} Optional parameters amount orderlines If you do not want to capture the full amount a smaller amount can be captured. This must be more than 0.00 and it must be equal to or less than the reserved amount. If you capture an invoice payment, the orderlines is mandatory. OrderLines should be an array of lines with the following keys: float Key Type Description description String (255) Description of item. itemid String (100) Item number. quantity Decimal Quantity. taxpercent Decimal Decimal unitcode String (50) Measurement unit, e.g., kg. unitprice Decimal Unit price excluding sales tax reconciliation_i dentifier If you wish to define the reconciliation identifier used in the reconciliation csv files, you can choose to set it here. Example https://gateway.pensio.com/merchant/api/capturereservation/?transaction_id=12345&amount=0.20 Orderlines Example https://gateway.pensio.com/merchant/api/capturereservation/? transaction_id=12345&amount=14.50&orderlines[0][description]=white%20sugar&orderlines[0] [itemid]=productid&orderlines[0][quantity]=1.5&orderlines[0][taxpercent]=20&orderlines[0] [unitcode]=kg&orderlines[0][unitprice]=5.75&orderlines[1][description]=brown%20sugar&orderlines[1] [itemid]=productid2&orderlines[1][quantity]=2.5&orderlines[1][taxpercent]=20&orderlines[1] [unitcode]=kg&orderlines[1][unitprice]=8.75 10 of 41
Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/captureReservation</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <CaptureAmount>0.20</CaptureAmount> <CaptureCurrency>978</CaptureCurrency> <Result>Success</Result> <CaptureResult>Success</CaptureResult> <! deprecated > <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>captured</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1.00</ReservedAmount> <CapturedAmount>1.00</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo> <UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent> <IpAddress>127.127.127.127</IpAddress> </CustomerInfo> <ReconciliationIdentifiers> <ReconciliationIdentifier> <Id>f4e2533e c578 4383 b075 bc8a6866784a</id> <Amount currency="978">1.00</amount> <Type>captured</Type> <Date>2010 09 28T12:00:00+02:00</Date> </ReconciliationIdentifier> </ReconciliationIdentifiers> </Transaction> </Transactions> </Body> </APIResponse> 11 of 41
12 of 41
API/releaseReservation Every now and then you for some reason do not want to capture a payment. In these cases you must cancel it to release the reservation of the funds. Required parameters transaction_id The id of a specific payment. [0 9a f]{1,32} Example https://gateway.pensio.com/merchant/api/releasereservation/?transaction_id=12345 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/releaseReservation</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <CancelResult>Success</CancelResult> <! deprecated > <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>cancelled</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1.00</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo> 13 of 41
<UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent> <IpAddress>127.127.127.127</IpAddress> </CustomerInfo> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse> API/refundCapturedReservation Sometimes after delivering the goods/services and capturing the funds you want to repay/refund the customer. Either you want to make a full refund or you only want to make a partial refund. Note that not all payments can be refunded, and some can be refunded multiple times, depending on the payment nature (CreditCard, E Payment, BankPayment and ideal) and on the acquirer used. Required parameters transaction_id The id of a specific payment. [0 9a f]{1,32} Optional parameters amount reconciliation_i dentifier Example The amount you want to refund the card holder. This must be less than or equal to the amount which was captured in this payment. If you wish to define the reconciliation identifier used in the reconciliation csv files, you can choose to set it here. float String {0,100} https://gateway.pensio.com/merchant/api/refundcapturedreservation/?transaction_id=12345&amount=0.12 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/refundCapturedReservation</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <RefundAmount>0.12</RefundAmount> <RefundCurrency>978</RefundCurrency> <Result>Success</Result> <RefundResult>Success</RefundResult> <! deprecated > <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> 14 of 41
<Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>refunded</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1.00</ReservedAmount> <CapturedAmount>1.00</CapturedAmount> <RefundedAmount>0.12</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 11:34:56</CreatedDate> <UpdatedDate>2010 09 28 13:00:00</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo> <UserAgent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.41 Safari/535.7</UserAgent> <IpAddress>127.127.127.127</IpAddress> </CustomerInfo> <ReconciliationIdentifiers> <ReconciliationIdentifier> <Id>f4e2533e c578 4383 b075 bc8a6866784a</id> <Amount currency="978">1.00</amount> <Type>captured</Type> <Date>2010 09 28T12:00:00+02:00</Date> </ReconciliationIdentifier> <ReconciliationIdentifier> <Id>8774bcef 7549 4497 948e 82280ca69f80</Id> <Amount currency="978">0.12</amount> <Type>refunded</Type> <Date>2010 09 28T13:00:00+02:00</Date> </ReconciliationIdentifier> </ReconciliationIdentifiers> </Transaction> </Transactions> </Body> </APIResponse> 15 of 41
API/splitTransaction (Deprecated) Please use multiple capture invocations instead. If only part of the delivery can be delivered at the moment, the payment can be split into two. Required parameters transaction_id The id of a specific payment. [0 9a f]{1,32} amount Example The amount you want for the first of the splitted payments. This must be less than the amount which was authed in this payment. https://gateway.pensio.com/merchant/api/splittransaction/?transaction_id=1&amount=1500.00 float Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/splitTransaction</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <SplitResult>Success</SplitResult> <! deprecated > <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>splitted</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>2500.00</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> 16 of 41
<Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> <Transaction> <TransactionId>2</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1500.00</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo/> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> <Transaction> <TransactionId>3</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>1000.00</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo/> 17 of 41
<CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse> 18 of 41
API/setupSubscription This method is used to setup a subscription for later use with API/captureRecurring or API/preauthRecurring. It is mostly a Required parameters The same as for API/reservationOfFixedAmountMOTO Optional parameters The same as for API/reservationOfFixedAmountMOTO Ignored parameters As this method is works as a short cut for API/reservationOfFixedAmountMOTO the parameter type will be ignored. Example https://gateway.pensio.com/merchant/api/setupsubscription? terminal=pensio+terminal&shop_orderid=abc123&amount=42.75¤cy=eur&cardnum=4111111111111111&emont h=08&eyear=2022&cvc=123 19 of 41
API/captureRecurring This is used to capture a recurring payments once. You can call this multiple times with the same payment to do several captures. Required parameters transaction_id The id of the original recurring payment. [0 9a f]{1,32} Optional parameters amount reconciliation_i dentifier Example The amount you want to capture. This must be less than the max amount defined by the original setup of a recurring payment 1. If you wish to define the reconciliation identifier used in the reconciliation csv files, you can choose to set it here. float String {0,100} https://gateway.pensio.com/merchant/api/capturerecurring/?transaction_id=1&amount=5 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/captureRecurring</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>recurring_confirmed</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>0</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>10.00</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> 1 Please read refer to the ecommerce API specification on how to set up a card holder for recurring payments. 20 of 41
<SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers /> </Transaction> <Transaction> <TransactionId>2</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>captured</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>5.00</ReservedAmount> <CapturedAmount>5.00<CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo/> <CustomerInfo/> <ReconciliationIdentifiers> <ReconciliationIdentifier> <Id>f4e2533e c578 4383 b075 bc8a6866784a</id> <Amount currency="978">5.00</amount> <Type>captured</Type> <Date>2010 09 28T12:34:56+02:00</Date> </ReconciliationIdentifier> </ReconciliationIdentifiers> </Transaction> </Transactions> </Body> </APIResponse> 21 of 41
API/preauthRecurring This is used to create a preauth from a recurring payment, as opposed to capturing it right away. You can call this multiple times with the same 'recurring_confirmed' payment to do several preauths. Note that the reservations must later be captured with the API/captureRecurring call. Required parameters transaction_id The id of the original recurring payment. [0 9a f]{1,32} Optional parameters amount Example The amount you want to preauth. This must be less than the max amount defined by the original setup of a recurring payment 2. float https://gateway.pensio.com/merchant/api/preauthrecurring/?transaction_id=1&amount=5 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/preauthRecurring</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Transactions> <Transaction> <TransactionId>1</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>recurring_confirmed</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>0</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>10.00</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> 2 Please read refer to the ecommerce API specification on how to set up a card holder for recurring payments. 22 of 41
</PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> <Transaction> <TransactionId>2</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorderid</ShopOrderId> <Shop>Pensio Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>5.00</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>13.37</FraudRiskScore> <FraudExplanation>Fraud detection explanation</fraudexplanation> <TransactionInfo> <Form_Created_At>2010 09 28 12:34:56</Form_Created_At> <Form_Provider>Pensio Test Form</Form_Provider> <Merchant_Provided_Info>Some info by merchant</merchant_provided_info> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse> 23 of 41
API/fundingList Used to get a list of fundings, which details when and how much money is transfered to your companys bank account. Required parameters Optional parameters page Example This method will only show 100 fundings pr. call. Setting this parameter allows you to fetch more. Int https://gateway.pensio.com/merchant/api/fundinglist/?page=1 Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/fundingList</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Fundings numberofpages="1"> <Funding> <Filename>CreatedByTest</Filename> <ContractIdentifier>1234567890123456</ContractIdentifier> <Shops> <Shop>Pensio Functional Test Shop</Shop> <Shop>Pensio Functional Test Shop Two</Shop> </Shops> <Acquirer>TestAcquirer</Acquirer> <FundingDate>2010 09 26</FundingDate> <Amount>50.00 EUR</Amount> <CreatedDate>2010 09 27</CreatedDate> <DownloadLink> http://localhost/merchant.php/api/fundingdownload?id=1 </DownloadLink> </Funding> <Funding> <Filename>CreatedByTest</Filename> <ContractIdentifier>1234567890123456</ContractIdentifier> <Shops> <Shop>Pensio Functional Test Shop</Shop> <Shop>Pensio Functional Test Shop Two</Shop> </Shops> <Acquirer>TestAcquirer</Acquirer> <FundingDate>2010 09 26</FundingDate> <Amount>50.00 EUR</Amount> <CreatedDate>2010 09 27</CreatedDate> <DownloadLink> http://localhost/merchant.php/api/fundingdownload?id=2 </DownloadLink> </Funding> </Fundings> 24 of 41
</Body> </APIResponse> 25 of 41
API/fundingDownload Used to get a comma separated value file containing the details of a funding. Required parameters Optional parameters id The id of the funding. Int Example https://gateway.pensio.com/merchant/api/fundingdownload?id=32 Example Result Date;Type;ID;"Reconciliation Identifier";Payment;Order;Terminal;Shop;"Transaction Currency";"Transaction Amount";"Exchange Rate";"Settlement Currency";"Settlement Amount";"Fixed Fee";"Fixed Fee VAT";"Rate Based Fee";"Rate Based Fee VAT" "2010 09 22 00:00:00";payment;5;3f664acc c71d 45e6 8c6a a15838451a77;5;"settlement functional4c9a127b159a0";"pensio Test Terminal";"Pensio Functional Test Shop";EUR;50.00;100.000000;EUR;50.00;;;; Content description Column name Type Description Date YYYY MM DD The 'settlement date' of the transaction this is the date within the Visa/MC networks where the transaction is processed. Typically this is the bank day following the date of the payment/refund. Type string Type of the funding. Possible values: payment, refund, chargeback, and adjustment. ID string(100) Pensio payment ID Reconciliation Identifier * UUID Unique ID of the funding record Payment * [0 9a f](1 40) Pensio payment ID Order * string(100) Shop order ID Terminal * string(100) Terminal name Shop * string(100) Shop name Transaction Currency string(3) The currency of the original payment, ISO 4217 Transaction Amount float The amount of the original payment Exchange Rate float Exchange rate from transaction to settlement amount. (exchage rate 1/1 = 100) Settlement Currency string(3) The currency of the settlement record, ISO 4217 Settlement Amount float The amount of the settlement record Fixed Fee float Fixed transaction cost (incl. VAT where applicable) 26 of 41
Fixed Fee VAT float VAT of the transaction cost Rate Based Fee float Rate based transaction cost (incl. VAT where applicable) Rate Based Fee VAT float VAT of the transaction cost * Only available if the transaction is related to a funding 27 of 41
API/reservationOfFixedAmountMOTO This will create a MO/TO payment. The payment can be made with a credit card, or a credit card token and the CVV. Required parameters: terminal <TERMINAL TITLE> string shop_orderid The id of the order in your web shop, this is what we will post back to you so you know which order a given payment is associated with. amount The amount of the payment in english notation (ex. 89.95) For a recurring payment the amount is the maximum amount for each capture. currency The currency of the order. It is a 3 digit currency code. Our gateway comply with the ISO 4217 standard 3. Required Credit Card parameters (normal): [a za Z0 9]{1,100} float Integer cardnum The credit card number (PAN) [0 9]{11 19} emonth The expiry month 01 12 eyear The expiry year 2000 2999 Required Credit Card parameters (token): credit_card_token A credit card token previously received from an ecommerce payment or an other MO/TO payment. [0 9a f]{40} Optional parameters: cvc The CVC/CVV/CVV2/Security Code [0 9]{3 4} transaction_info type This is a one dimensional associative array. This is where you put any value that you would like to bind to the payment. The type of payment. This should be either payment, paymentandcapture or recurring. Defaults to payment Array, max 50 entries. Each entry of max 255 chars. String payment_source The source of the payment. Default is moto ecommerce / moto Mandatory 4 fraud detection parameters: billing_city The city of the customer's billing address. string billing_region The region of the customer's billing address. string billing_postal The postal code of the customer's billing string 3 http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list 1.htm or read more about the standard in general at: http://en.wikipedia.org/wiki/iso_4217 4 Fraud detection parameters are only mandatory if fraud detection is enabled for the terminal 28 of 41
billing_country address. The country of the customer's billing address as a 2 character ISO 3166 country code. [a za Z]{2} Optional fraud detection parameters: email The customer's email address. string customer_phone The customer's telephone number. string bank_name bank_phone billing_firstname billing_lastname billing_address The name of the bank where the credit card was issued. The phone number of the bank where the credit card was issued. The first name for the customer's billing address. The last name for the customer's billing address. The street address of the customer's billing address. string String String String string Example (based on new credit card) <form action="https://gateway.pensio.com/merchant/api/reservationoffixedamountmoto/"> <input name="terminal" value="terminal 1" /> <input name="shop_orderid" value="myorder123" /> <input name="amount" value="2499.95" /> <input name="currency" value="978" /> <input name="cardnum" value="4111111111111111" /> <input name="eyear" value="2014" /> <input name="emonth" value="09" /> <input name="cvc" value="123" /> </form> Example (based on credit card token) <form action="https://gateway.pensio.com/merchant/api/reservationoffixedamountmoto/"> <input name="terminal" value="terminal 1" /> <input name="shop_orderid" value="myorder123" /> <input name="amount" value="2499.95" /> <input name="currency" value="978" /> <input name="credit_card_token" value="0a4d55a8d778e5022fab701977c5d840bbc486d0" /> <input name="cvc" value="123" /> </form> Example XML Result <?xml version="1.0"?> <APIResponse version="20100929"> <Header> 29 of 41
<Date>2010 09 29T12:34:56+02:00</Date> <Path>API/reservationOfFixedAmountMOTO</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Transactions> <Transaction> <TransactionId>3</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>85c1d13de7b5dceb6b739829cc27e089631b0fda</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorder123</ShopOrderId> <Shop>Pensio Functional Test Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>2499.95</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <TransactionInfo> <Payment_Type>payment</Payment_Type> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse> Example XML Error (when using an unknown credit card token) <?xml version="1.0"?> <APIResponse version="20100929"> <Header> <Date>2010 02 12T21:45:52+01:00</Date> <Path>API/reservationOfFixedAmountMOTO</Path> <ErrorCode>762813994</ErrorCode> <ErrorMessage>No credit card with selected token exists: 0a4d55a8d778e5022fab701977c5d840bbc486d0</ErrorMessage> </Header> <Body/> </APIResponse> 30 of 41
API/credit This will create a Credit payment. The payment can be made with a credit card, or a credit card token and the CVV. The result is the same as a reservationoffixedamountmoto. Note that most acquirers does not support credits, contact support if you need this functionality. Required parameters: terminal <TERMINAL TITLE> string shop_orderid The id of the order in your web shop, this is what we will post back to you so you know which order a given payment is associated with. amount The amount of the payment in english notation (ex. 89.95) For a recurring payment the amount is the maximum amount for each capture. currency The currency of the order. It is a 3 digit currency code. Our gateway comply with the ISO 4217 standard 5. Required Credit Card parameters (normal): [a za Z0 9]{1,100} float Integer cardnum The credit card number (PAN) [0 9]{11 19} emonth The expiry month 01 12 eyear The expiry year 2000 2999 Required Credit Card parameters (token): credit_card_token A credit card token previously received from an ecommerce payment, an other MO/TO payment or another credit payment. [0 9a f]{40} Optional parameters: cvc The CVC/CVV/CVV2/Security Code [0 9]{3 4} transaction_info This is a one dimensional associative array. This is where you put any value that you would like to bind to the payment. Array, max 50 entries. Each entry of max 255 chars. payment_source The source of the payment. Default is moto ecommerce / moto 5 http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list 1.htm or read more about the standard in general at: http://en.wikipedia.org/wiki/iso_4217 31 of 41
API/getTerminals This method will allow you to extract a list of terminals that you have access to. The list will contains some details about the terminals. The method takes no parameters. Example XML Output <?xml version="1.0"?> <APIResponse version="20100929"> <Header> <Date>2011 05 11T23:43:20+02:00</Date> <Path>API/getTerminals</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>OK</Result> <Terminals> <Terminal> <Title>Pensio Multi Nature Terminal</Title> <Country>DK</Country> <Natures> <Nature>CreditCard</Nature> <Nature>EPayment</Nature> <Nature>IdealPayment</Nature> <Nature>Invoice</Nature> </Natures> <Currencies> <Currency>DKK</Currency> <Currency>EUR</Currency> </Currencies> </Terminal> <Terminal> <Title>Pensio BankPayment Terminal</Title> <Country></Country> <Natures> <Nature>BankPayment</Nature> </Natures> <Currencies> <Currency>EUR</Currency> </Currencies> </Terminal> </Terminals> </Body> </APIResponse> 32 of 41
API/getInvoiceText GetInvoiceText is used for gathering information to print on the customer invoice for invoice/gothia payments. This is typically used when merchants print their own invoices from their backend system. As the invoice sent to the customer needs to include some information from Gothia, this call is mandatory if you use Gothias PayByBill product. Regarding TextInfos; These are a set of key/value pairs which depends on which service you use. You can typically find the password for the customer to access Gothia systems (also found in LogonText), so you can customize the "LogonText" by using these values, if desired. The invoice number is always used as username. Please refer to Gothia documentation for further details. Required parameters transaction_id The id of a specific payment. [0 9a f]{1,32} amount Example If you do not want to invoice the full amount a smaller amount can be captured. This amount must equal a previously captured amount https://gateway.pensio.com/merchant/api/getinvoicetext/?transaction_id=12345&amount=0.20 float Example XML Result <?xml version="1.0" encoding="utf 8"?> <APIResponse version="20100929"> <Header> <Date>2011 03 10T15:36:43+01:00</Date> <Path>API/getInvoiceText</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <InvoiceText> <AccountOfferMinimumToPay>200</AccountOfferMinimumToPay> <AccountOfferText>Ønsker du å delbetale denne fakturaen går du enkelt inn på paybybill.gothiagroup.com. Brukernavnet tilsvarer ditt fakturanummer og passordet er angitt på fakturaen. Etter at du har godkjent vilkårene, betaler du inn aktiveringsbeløpet som er angitt på fakturaen. Det vil da opprettes en kundekonto hos Gothia som gjør at du kan dele opp fakturabeløpet over tid gjennom tilsendt månedsfaktura.</accountoffertext> <BankAccountNumber>123456789</BankAccountNumber> <LogonText>Logg på kunde.gothiagroup.com med fakturanr og passord. Passord : xxxxxx</logontext> <OcrNumber>234234523</OcrNumber> <MandatoryInvoiceText>Fordringen er overdraget Gothia Financial Group AB til ejendom. Betaling, indsigelser samt alle.</mandatoryinvoicetext> <InvoiceNumber>7373</InvoiceNumber> <CustomerNumber>832</CustomerNumber> <TextInfos> <TextInfo> <Name>Password</Name> <Value>xxxxxx</Value> </TextInfo> 33 of 41
</TextInfos> <Address> <FirstName>John</FirstName> <LastName>John</LastName> <Address>Anywhere Street 12</Address> <City>Anywhere City</City> <PostalCode>1111</PostalCode> <Country>DK</Country> </Address> </InvoiceText> </Body> </APIResponse> Explanation of error cases The merchant API can return two types of errors, an error in the data/format of the request or an error that happened while the system tried to execute what was requested. These two kinds of errors are represented differently in the system. An error in the data/format of the request will be described in the header of the response, like so: <?xml version="1.0"?> <APIResponse version="20100929"> <Header> <Date>2010 02 12T21:45:52+01:00</Date> <Path>API/yourApiCall</Path> <ErrorCode>234</ErrorCode> <ErrorMessage>Error message detailing what the error was</errormessage> </Header> <Body/> </APIResponse> So if the errorcode in the header is 0 that means the merchant api was able to understand and verify the request that was send. In the case of an error when trying to execute what was requested, the error message will be shown like this: <?xml version="1.0"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/yourApiCall</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Error</Result> <MerchantErrorMessage>Error message for you the merchant</merchanterrormessage> <CardHolderErrorMessage>Error message that is safe to be read by the cardholder</cardholdererrormessage> <Transactions> <Transaction> <TransactionId>3</TransactionId> <CardStatus>Valid</CardStatus> <CreditCardToken>85c1d13de7b5dceb6b739829cc27e089631b0fda</CreditCardToken> <CreditCardMaskedPan>411111******1111</CreditCardMaskedPan> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken> <ShopOrderId>myorder123</ShopOrderId> <Shop>Pensio Functional Test Shop</Shop> 34 of 41
<Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>0</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2010 09 28 12:34:56</CreatedDate> <UpdatedDate>2010 09 28 12:34:56</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <TransactionInfo> <Payment_Type>payment</Payment_Type> </TransactionInfo> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse> Notice the payment (in the api also called transaction) is returned if possible in this type of error, which will allow you to check if the payment is in the state you expected it to. If for example you try to capture 40EUR on a payment has 40EUR reserved, and the payment fails but already has 40.00 set as the captured amount, that payment was already captured at an earlier time. In that case you can conclude that the payment was captured as expected, even though this call to the api was unsuccessful. In some cases there will be more information in the error response, for example in the case of a capture error the response will also contain the amount and currency that the system tried to capture. 35 of 41
API/createPaymentRequest As an alternative way of redirecting to the pensio payment form, you can now make a serverside http post to the createpaymentrequest url in the ecommerce api, with the same parameters you would normally send to the form method (See furhter down for parameters additionally supported by createpaymentrequest). It will return an api response with a url to redirect the user to. Because this call does not happen in the browser, you do not need to worry about the user tampering with the data posted to the gateway, and thus don't need to pass a checksum for the customer information. GET Example: https://gateway.pensio.com/merchant/api/createpaymentrequest/? terminal=shop+test+terminal&shop_orderid=order1234567&amount=2.25¤cy=978&language=da&transacti on_info[referer]=john+doe&secondary_amount=5.89&customer_info[billing_city]=glostrup&customer_info[ billing_region]=copenhagen&customer_info[billing_postal]=2600&customer_info[billing_country]=dk&cus tomer_info[email]=myuser%40mail.dk&customer_info[username]=myuser Return xml example <?xml version="1.0"?> <APIResponse version="20100929"> <Header> <Date>2010 09 29T12:34:56+02:00</Date> <Path>API/createPaymentRequest</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Url>https://gateway.pensio.com/merchant.php/API/requestForm? pid=2349494a 6adf 49f7 8096 2125a969e104</Url> </Body> </APIResponse> Parameters additionally available for createpaymentrequest cookie The cookie to be sent to your callback urls 1). String config[callback_ form] config[callback_ ok] config[callback_ fail] config[callback_ redirect] config[callback_ open] Sending this will override the callback form setting on the terminal Sending this will override the callback ok setting on the terminal Sending this will override the callback fail setting on the terminal Sending this will override the callback redirect setting on the terminal Sending this will override the callback open setting on the terminal String (Url) String (Url) String (Url) String (Url) String (Url) 36 of 41
config[callback_ notification] Sending this will override the callback notification setting on the terminal String (Url) 1) Cookie explanation: Additionally a cookie parameter can be sent to createpaymentrequest, which is then passed back as the complete cookie for the callbacks. For example, if the cookie parameter is set to: PHPSESSID=asdfasdfdf23; mycookie=mycookievalue, the Cookie header in the callback to your page will be: Cookie: PHPSESSID=asdfasdfdf23; mycookie=mycookievalue The complete cookie, including session cookie, in php can be fetched like this: $_SERVER['HTTP_COOKIE'] 37 of 41
API/createInvoiceReservation Required parameters: terminal <TERMINAL TITLE> string shop_orderid The id of the order in your webshop. This is what we will post back to you so you know which order a given payment is associated with. amount The amount of the payment in english notation (ex. 89.95) For a recurring payment the amount is the maximum amount for each capture. currency Optional parameters 7 : The currency of the order. It is a 3 digit currency code. Our gateway complies with the ISO 4217 standard 6. [a za Z0 9]{1,100} float integer transaction_info type This is a one dimensional assosiative array. This is where you put any value that you would like to bind to the payment. The type of the authorization: payment : A normal reservation that must later be captured, only valid for Credit Card payments. paymentandcapture : A payment which is captured upon authorization, valid for both Credit Card, E Payment, ideal and Bank Payments. recurring : The setup of a recurring payment, only valid for Credit Card Payments. Defaults is payment. Array, max 50 entries. Each entry of max 255 chars. string Mandatory parameters for invoice payments: customer_info[billing_postal] customer_info[billing_address] customer_info[email] The postal code of the customer's billing address. The street address of the customer's billing address. Mandatory for DK, FI and DE The customer's email address. Required for NO and DE. string string string Parameters for invoice payment identification: Exactly one of these parameters must also be sent. organisationnumber The country specific organisation number string 6 http://www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes/currency_codes_list 1.htm or read more about the standard in general at: http://en.wikipedia.org/wiki/iso_4217 7 The gateway will issue an error if you pass any parameters not explicitly listed as required or optional in this documentation. 38 of 41
personalidentifynumber birthdate for the customer, if it is a corporate customer. The country specific personal identity number for the customer, for countries where it is applicable. eg. Norway, Sweden, Finland The birthdate of the customer for countries where a personal identity number is not allowed to be used. Eg. Germany and Denmark. string YYYY MM DD GET Example: https://gateway.pensio.com/merchant/api/createinvoicereservation/? terminal=shop+test+terminal&shop_orderid=order1234567&amount=2.25¤cy=978&language=da&transacti on_info[referer]=john+doe&secondary_amount=5.89&customer_info[billing_city]=glostrup&customer_info[ billing_region]=copenhagen&customer_info[billing_postal]=2600&customer_info[billing_country]=dk&cus tomer_info[email]=myuser%40mail.dk&customer_info[username]=myuser&organisationnumber=1235323 Return xml example <?xml version="1.0"?> <APIResponse version="20110831"> <Header> <Date>2011 10 20T11:50:09+02:00</Date> <Path>API/createInvoiceReservation</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Transactions> <Transaction> <TransactionId>416</TransactionId> <CardStatus>NoCreditCard</CardStatus> <CreditCardToken /> <CreditCardMaskedPan /> <ThreeDSecureResult>Not_Applicable</ThreeDSecureResult> <BlacklistToken/> <ShopOrderId>asdf23</ShopOrderId> <Shop>Pensio Test Shop</Shop> <Terminal>Pensio Test Terminal</Terminal> <TransactionStatus>invoice_initialized</TransactionStatus> <MerchantCurrency>978</MerchantCurrency> <CardHolderCurrency>978</CardHolderCurrency> <ReservedAmount>20</ReservedAmount> <CapturedAmount>0</CapturedAmount> <RefundedAmount>0</RefundedAmount> <RecurringMaxAmount>0</RecurringMaxAmount> <CreatedDate>2011 10 20 11:50:09</CreatedDate> <UpdatedDate>2011 10 20 11:50:09</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentNatureService name="testacquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> 39 of 41
<SupportsMultipleRefunds>false</SupportsMultipleRefunds> </PaymentNatureService> <PaymentNature>Invoice</PaymentNature> <TransactionInfo /> <CustomerInfo/> <ReconciliationIdentifiers /> </Transaction> </Transactions> </Body> </APIResponse> 40 of 41
Detailed Response XML descriptions: ThreeDSecureResult: The 3d secure result can be one of the following: Not_Applicable 3d secure is not applicable for this type of payment or for the state the payment is in Disabled 3D Secure has been disabled in the gateway CardType_Not_Supported The card is not part of a 3d secure scheme Not_Attempted Pensio does not support 3d secure with this acquirer/card type combination Not_Enrolled The card is not enrolled in the applicable 3d secure scheme, so the transaction was completed without 3d secure Declined 3d Secure is declined, so the payment have been declined as well Error An error occured, so the transaction was completed without 3d secure Attempted 3d secure was attempted but not successful, so the transaction was completed without full 3d secure Successful Successful and 3d secured payment 41 of 41