Optimal Payments Hosted Payments API Reference Guide
December 2014 1.3.4 This manual and accompanying electronic media are proprietary products of Optimal Payments plc. They are to be used only by licensed users of the product. © 1999–2015 Optimal Payments plc. All rights reserved. The information within this document is subject to change without notice. The software described in this document is provid- ed under a license agreement, and may be used or copied only in accordance with this agreement. No part of this manual may be reproduced or transferred in any form or by any means without the express written consent of Optimal Payments plc. All other names, trademarks, and registered trademarks are the property of their respective owners. Optimal Payments plc makes no warranty, either express or implied, with respect to this product, its merchantability or fitness for a particular purpose, other than as expressly provided in the license agreement of this product. For further information, please contact Optimal Payments plc. International Head Office 3500 de Maisonneuve W., Suite 700 Montreal, Quebec H3Z 3C1 Canada Tel.: (514) 380-2700 Fax: (514) 380-2760 Email: [email protected] Technical support: [email protected] Web: www.optimalpayments.com U.K. Office Compass House, Vision Park Chivers Way, Histon Cambridge CB24 9AD United Kingdom Email: [email protected] Technical Support: [email protected] Web: www.optimalpayments.com U.S. Office 1209 Orange Street Wilmington, DE 19801 Gatineau Office 75 Promenade du Portage Gatineau, Quebec J8X 2J9 Canada Release Notes
Release Notes
Version Date Details
1.3.4 December 2014 • Added Pingit functionality
1.3.3 October 2014 • Added accordD functionality for select merchants
1.3.2 May 2014 • Added authCode parameter to order status response table and to Return Keys appendix • Updated HTML example in ThreatMetrix appendix • Added functionality for Giropay, NETELLER, PayPal, Sofort Banking and Ukash • Updated extended options key/value pairs table • Updated values for transaction.status parameter
1.3.1 February 2014 • Added MasterPass functionality • Updated extended options key/value pairs table
1.3 October 2013 • Updated extended options key/value pairs table • Added section for rebilling with a profile • Added silent post for prepaid cards • Added ThreatMetrix appendix. • Add optional delimiter for redirects and callbacks • Corrected rebill examples to include currencyCode • Added error message for updating a transaction • Added orderTimeout extended option and error message
1.2 May 2013 • Updated Return Keys appendix • Added Test and Production URLs section • Added section for updating an order • Removed Order/Response Examples appendix • Added section for rebilling • Added parameters to shipping details table • Added parameters to order status response table • Updated error response table • Added four appendices • Updated extended options key/value pairs table
1.1 March 20, 2013 • Added customer profiles • Added mobile functionality • Added return keys table • Added key/value pairs
1.0 January 1, 2013 Document release
Optimal Payments Hosted Payments API Reference Guide 1.3.4 III December 2014
IV Contents
1 Hosted Payments API
Overview ...... 1-1 API key...... 1-1 URLs ...... 1-2 Test URL ...... 1-2 Production URL ...... 1-2 Workflow overview ...... 1-2 Mobile capability ...... 1-2 Operations supported...... 1-3 Using this guide ...... 1-3 Audience ...... 1-3 Functionality...... 1-3 Symbols ...... 1-3 Setting up an order...... 1-4 Adding details to your order request ...... 1-5 Customer profiles ...... 1-5 Profile object example 1 ...... 1-6 Profile object example 2 ...... 1-6 Profile object example 3 ...... 1-7 Shopping cart information ...... 1-7 Ancillary fee information...... 1-8 Billing detail information...... 1-8 Shipping details ...... 1-9 Callbacks ...... 1-11 Redirects ...... 1-12 Links...... 1-13 Payment methods...... 1-14 Payment method notes ...... 1-15 Addendum data ...... 1-16 addendumData for MasterPass...... 1-17 Localisation ...... 1-17 Finance plan...... 1-18 Order response ...... 1-18 Making a payment ...... 1-20
Optimal Payments Hosted Payments API Reference Guide 1.3.4 V December 2014
Making a payment using a silent post ...... 1-21 Silent post for prepaid cards...... 1-21 Silent post for credit cards ...... 1-22 Silent post for Giropay ...... 1-23 Silent post for iDEAL ...... 1-23 Silent post for NETELLER ...... 1-24 Silent post for Sofort Banking ...... 1-24 Silent post for Ukash ...... 1-24 Silent post for other supported payment methods ...... 1-24 Making a payment using customer profile ...... 1-25 Making a payment using a Hosted Payments customer profile ...... 1-25 Making a silent post payment using a customer profile ...... 1-26 Rebilling ...... 1-26 Rebilling with a profile ...... 1-27 Rebill request response...... 1-27 Cancelling an order ...... 1-27 Cancel order response ...... 1-28 Updating an order ...... 1-28 Updating a held order ...... 1-29 Updating rebills ...... 1-29 Update response ...... 1-29 Obtaining an order status ...... 1-30 Order status response ...... 1-30 Associated transactions parameters...... 1-31 Refunding an order...... 1-31 Order refund response ...... 1-31 Settling an order ...... 1-32 Order settlement response ...... 1-33 Getting an order report...... 1-33 Order report response ...... 1-33 Resending a callback ...... 1-35 Resend callback response ...... 1-35
A Extended Options
Introduction ...... A-1 Key/value pairs for extended options ...... A-1
B Return Keys
Callback return keys ...... B-1 Redirect return keys ...... B-2
C Error Responses
VI December 2014
D ThreatMetrix Silent Post
Overview ...... D-1 Implementing ThreatMetrix ...... D-1 Profiling HTML...... D-1 HTML ...... D-2 Redirecting the profile server URL ...... D-3 RedirectMatch ...... D-3 Rewrite Module ...... D-3
E Order Status Response Parameters
Order status response...... E-1
Optimal Payments Hosted Payments API Reference Guide 1.3.4 VII December 2014
VIII CHAPTER 1
Hosted Payments API
Overview The Optimal Payments Hosted Payments API is a RESTful interface for making secure payments by way of your e-commerce site. The REST API works with JSON messages and responses. • With the API, your customer can pay securely using a PCI-compliant hosted payments page. • By using a payment page hosted by Optimal Payments, sensitive payment information such as credit card numbers is handled by Optimal Payments. • The Optimal Payments payment page helps reduce the overhead of PCI audit requirements and its associated costs. The API does not allow merchants to pass card data. If you wish your e-commerce site to collect and pass card data, then you need to use the Optimal Payments Web Services API and comply with PCI guidelines regarding the handling of card data.
Optimal Payments may add additional elements in future releases of this API, so ensure that your inte- gration is flexible enough to ignore any unrecognized response fields.
API key In order for you to use the Optimal Payments REST API, Optimal Payments must first set you up on their system and provide you with an API key. Your API key looks something like this: • Key ID – MerchantXYZ • Key Password – B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702 151182fdc952272661d290ab2e5849e31bb03deede7e The case-sensitive API key is sent using HTTP Basic Authentication. To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request. The Authorization header is constructed as follows: 1. The Key ID and Key Password are combined into a string separated by a colon, e.g., “Key ID:Key Password”. 2. The resulting string literal is then encoded using Base64. 3. The authorization method and a space (i.e., “Basic”) are then put before the encoded string. For example, using the Key ID and Password examples above, the header is formed as follows: Authorization: Basic bWVyY2hhbnQteHl6OkItdHN0MS0wLTUxZWQzOWU0LTMxMmQwMjM0NWQzZjEyMzEyMDg4MWRmZjliYjQwMjBhOD ll OGFjNDRjZGZkY2VjZDcwMjE1MTE4MmZkYzk1MjI3MjY2MWQyOTBhYjJlNTg0OWUzMWJiMDNkZWVkZTdl For additional details, please refer to http://en.wikipedia.org/wiki/Basic_access_authentication.
You must keep your API key safe and ensure that it is used appropriately for your needs.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-1 Hosted Payments API December 2014
URLs
Test URL In order to test your integration with Optimal Payments, use the following Test URL: https://api.test.optimalpayments.com For example: https://api.test.optimalpayments.com/hosted/v1/orders
Production URL In order to process live requests with Optimal Payments, use the following Production URL: https://api.optimalpayments.com For example: https://api.optimalpayments.com/hosted/v1/orders
Workflow overview The following diagram provides a simple overview of the workflow when you submit a purchase request to the API.
Mobile capability The Optimal Payments Hosted Payments page supports mobile devices by incorporating a responsive design that adapts dynamically to the size of the device or browser.
1-2 December 2014 Operations supported
Operations supported The API currently supports the following transaction types:
Table 1-1: API Operations
Transaction Description Endpoint URL Operation
Create an Order See Setting up an order on page 1-4 for hosted/v1/orders POST details.
Cancel an Order See Cancelling an order on page 1-27 for hosted/v1/orders/{id} DELETE details.
Update an Order See Updating an order on page 1-28 for hosted/v1/orders/{id} PUT details.
Get an Order See Obtaining an order status on page 1- hosted/v1/orders/{id} GET 30 for details.
Refund an Order See Refunding an order on page 1-31 for hosted/v1/orders/{id}/refund POST details.
Settle an Order See Settling an order on page 1-32 for hosted/v1/orders/{id}/settlement POST details.
Get an Order Report See Getting an order report on page 1-33 hosted/v1/orders GET for details.
Resend Callback See Resending a callback on page 1-35 for hosted/v1/orders/{id}/resend_callback GET details.
Process a Rebill See Rebilling on page 1-26 for details. hosted/v1/orders/{id} POST
Using this guide This user guide details major system functions. Each section provides an overview of functions, which are then broken down into procedures with steps to be followed.
Audience This user’s guide is intended for Optimal Payments merchants using the API to process transac- tion requests with Optimal Payments Hosted Payments.
Functionality This guide may document some features to which you do not have access. Access to such func- tionality is allotted on a merchant-by-merchant basis. If you have any questions, contact your Account Manager/Sales Representative or the Customer Service team on [email protected].
Symbols This user guide uses the following symbols to bring important items to your attention:
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-3 Hosted Payments API December 2014
Table 1-2: Symbols
Symbol Description
This note icon denotes a hint or tip to help you use the transaction processing application more efficiently.
This warning icon alerts you about actions you might take that could have important consequences.
Setting up an order To set up an order and accept a payment, your shopping cart or back-end application must first make a call to our API “order ” endpoint using your API key, and POST some basic data about the payment you wish your customer to make. Only three fields are required.
Table 1-3: Order Creation Parameters
Name Required Type Description
merchantRefNum Required String This is your own transaction ID, for your reference pur- Max = 40 poses. This should be unique for each transaction.
currencyCode Required ISO4217 This is the currency in which to process the transaction. E.g., GBP or USD
totalAmount Required Integer This is the total amount of the transaction (note that this E.g., 999 would value must be equal to the amounts passed in the ancil- authorise £9.99 laryFees and shoppingCart parameters, discussed below). Merchants can provide zero (0) as an amount, if they need to process a verification with no value on the card. In this case, the authType must be set to auth, using the extendedOptions feature (see Appendix A: Extended Options for details).
customerIp Optional String The value should be the incoming IP address of your cus- Max =15 tomer, which will restrict the payment page to being viewable only from this IP address.
customerNotificationEmail Optional String This is the consumer’s email address, to which notifica- Max = 256 tions regarding the purchase request are sent.
merchantNotificationEmail Optional String This is the merchant’s email address, to which notifica- Max = 256 tions regarding the purchase request are sent.
dueDate Conditional Date This is the date the order request will be processed. YYYY-MM-DD Include this parameter only when processing a rebill (see Rebilling on page 1-26). (UTC)
Though the customerIp parameter is not mandatory, Optimal Payments recommends including it for additional security.
This example is represented in JSON as follows:
1-4 December 2014 Adding details to your order request
{ "customerIp" : "123.123.123.123", "merchantRefNum" : "MERCHANT_REF_123", "currencyCode" : "GBP", "totalAmount" : 1125, "customerNotificationEmail" : "[email protected]", } Once you have generated this structure, you can POST it to the Optimal Payments servers using your API key. You can even do this from the command line using the “curl” utility: curl -X POST \ -u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \ -H "Content-Type: application/json" \ -d '{"merchantRefNum": "MERCHANT_REF_123", "currencyCode": "GBP", "totalAmount": 1000 }' \ https://api.optimalpayments.com/hosted/v1/orders The structure is the same for all orders set up in the system, no matter how complex. See Adding details to your order request on page 1-5 for information on more parameters you can include in your order (e.g., shopping cart data or ancillary fees such as taxes or shipping). Note that the order in which you include parameters is not important. Regardless of parameter order, Optimal Payments will render the fields on the payment page in logical order.
Adding details to your order request You can use the API by passing a minimum amount of required data. However, Optimal Pay- ments recommends that you provide as much additional information as possible in your order request. Including additional data can dramatically improve the user experience and maximise confidence in proceeding with the transaction, leading to a better conversion rate.
See Making a payment on page 1-20 to see an example of what a payment page would look like when you submit a detailed order request.
Customer profiles The Hosted Payments API allows merchants to create customer profiles for their customers. Once a customer profile is created, there are two ways that it can be used to accept payments from the customer. See Making a payment using customer profile on page 1-25 for details. The profile information is also used to populate the customer name field of the billing address displayed on the payment page. To add the customer profile information to the order, add a profile object to the JSON structure.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-5 Hosted Payments API December 2014
Table 1-4: Profile Parameters
Name Required Type Description
merchantCustomerId Conditional String This is the customer ID that the merchant has assigned to the cus- Max = 100 tomer. When this parameter is included in the request, a customer profile will be created. •Once a profile.id is created for the customer, the merchantCustomerId parameter no longer needs to be included in the request. • If you are creating a profile for a new customer, then the merchantCustomerId parameter should be included in the request.
firstName Optional String This is the customer’s first name. Max = 80
lastName Optional String This is the customer’s last name. Max = 80
id Optional String This is the customer ID previously returned by Optimal Payments Max = 80 when the profile was created (see Table 1-17: Order Response Parameters on page 1-19). If you include the id in the request, then the customer profile asso- ciated with that ID will be used for the transaction. See Making a payment using a silent post on page 1-21 for details on required parameters. If the id is invalid, an error is returned.
paymentToken Optional String This is the payment token previously returned by Optimal Pay- Max = 80 ments when the profile was created (see Table E-1: Order Status Response Parameters on page E-1). If you include the paymentToken in the request, then the card num- ber associated with that token will be used for the transaction. See Making a payment using a silent post on page 1-21 for details on required parameters. If the paymentToken is invalid, an error is returned.
Profile object example 1 In the following profile object, a profile is being created. "profile" : { "merchantCustomerId" : "[email protected]", "firstName" : "Jane", "lastName" : "Jones" }
Profile object example 2 In the following profile object, an existing id and paymentToken are being used for the transaction request. "profile" : { "id" : "12345", "paymentToken" : "LgM8x0ymeXozGG1", }
1-6 December 2014 Shopping cart information
See Making a silent post payment using a customer profile on page 1-26 for details.
Profile object example 3 In the following profile object, an existing id is being used for the transaction request. "profile" : { "id" : "12345" } See Making a payment using a Hosted Payments customer profile on page 1-25 for more details.
Shopping cart information To add shopping cart information to the order, add a shoppingCart array of objects to the JSON structure.
Table 1-5: Shopping Cart Parameters
Name Required Type Description
amount Required Integer This is the total amount of the item in the shopping cart. E.g., 999 would be £9.99
description Required String This is your description of the shopping cart item. It will appear on the Max = 50 payment page.
sku Optional String This is your ID for the shopping cart item (e.g., your internal SKU or ID). Max = 60 It is not displayed on the payment page, but is reflected back upon que- rying an order status.
quantity Optional Integer This is the quantity of the shopping cart item. It will appear on the pay- ment page.
The shoppingCart array is optional. However, if you include it, then the amount and description parameters are mandatory.
The shoppingCart array would look like this: "shoppingCart" : [ { "amount" : 500, "quantity" : 2, "sku" : "id/sku-1", "description" : "Wrench" }, { "amount" : 200, "quantity" : 1, "sku" : "id/sku-2", "description" : "Hammer" } ] Note that the totalAmount provided in the initial order must add up to the amounts (and ancillary fees, see Ancillary fee information on page 1-8) passed in the shoppingCart section.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-7 Hosted Payments API December 2014
The description label on the payment page is not localised, regardless of the language specified in the locale settings (see Localisation on page 1-17). So, for example, if the description included were “Hammer”, and the localisation settings were for French, “Hammer” would be displayed on the payment page, and not “Marteau”.
Ancillary fee information To add ancillary fees to the order, add an ancillaryFees array of objects to the JSON structure.
Table 1-6: Ancillary Fee Parameters
Name Required Type Description
amount Required Integer This is the amount of the fee. E.g., 999 would This value can be negative to indicate a discount. be £9.99
description Required String This is your description of the fee. Max = 50 The totalAmount provided in the initial order must include any ancillary fees (and shopping cart items) passed in the ancillaryFees section.
The ancillaryFees array would look like this: "ancillaryFees" : [ { "amount" : 300, "description" : "Postage" }, { "amount" : 125, "description" : "Tax" } ]
Billing detail information To add billing details to the order, include a billingDetails object to the JSON structure. These details are used to pre-populate the payment form when the payment page is requested for pay- ment. The street and zip parameters are used for address verification checks. No further valida- tion on other address information is performed (other than data-type integrity checks).
Table 1-7: Billing Details Parameters
Name Required Type Description
city Optional String This is the city in the billing address. Max = 40
country Required String This is the country in the billing address. Max = 2 Use ISO 3166-1 alpha-2 country codes.
street* Optional String This is the first line of the street address in the billing address. Max = 50
1-8 December 2014 Shipping details
Table 1-7: Billing Details Parameters (Continued)
Name Required Type Description
street2 Optional String This is the second line of the street address in the billing address. Max = 50
zip* Required String This is the postal/zip code in the billing address. Max = 10
state Optional Enum This is the state/province/region in the billing address. OR If country is U.S. or Canada, then Enum, using ISO_3166-2 state String codes. Otherwise, use a string. Max = 40
phone Optional String This is the telephone number in the billing address. Max = 40
useAsShippingAddress Optional Boolean Indicates whether this address should also be used as the shipping address. Possible values are: •true •false
* Parameters marked with an asterisk can be prefilled by the merchant on the payment page. Only the numbers (or first line) of address are prefilled as per the payment form instructions.
The billingDetails object is optional. However, if you include it, then the country and zip parameters are mandatory.
The billingDetails array would look like this: "billingDetails" : { "city" : "London", "country" : "EG", "street" : "123 Grosvenor Street", "street2" : "#25", "zip" : "EG123", "state" : "County", "phone" : "1234578544", "useAsShippingAddress" : true }
Shipping details To add shipping details to the order, include a shippingDetails object to the JSON data structure.
Table 1-8: Shipping Details Parameters
Name Required Type Description
city Optional String This is the city in the shipping address. Max = 40
country Required String This is the country in the shipping address. Max = 2 Use ISO 3166-1 alpha-2 country codes.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-9 Hosted Payments API December 2014
Table 1-8: Shipping Details Parameters (Continued)
Name Required Type Description
recipientName* Optional String This is the name of the recipient in the shipping address. Max = 256
street* Optional String This is the first line of the street address in the shipping address. Max = 50
street2 Optional String This is the second line of the street address in the shipping address. Max = 50
zip* Required String This is the postal/zip code in the shipping address. Max = 10
state Optional Enum This is the state/province/region in the billing address. OR If country is U.S. or Canada, then Enum, using ISO_3166-2 state codes. String Otherwise, use a string. Max = 40
phone Optional String This is the telephone number in the shipping address. Max = 40
carrier Optional Enum This is the shipment carrier. Possible values are: •APC = APC Overnight •APS = AnPost • CAD = Canada Postal Service •DHL •FEX = Fedex •RML = Royal Mail • UPS = United Parcel Service • USPS = United States Postal Service •OTHER
shipMethod Optional Enum This is the method of shipment. Possible values are: •N = Next Day/Overnight • T = Two-Day Service •C = Lowest Cost • O = Other
The shippingDetails object is optional. However, if you include it, then the country and zip parameters are mandatory.
The shippingDetails array would look like this: "shippingDetails" : { "city" : "Cambridge", "country" : "EG", "recipientName" : "Jane Smith", "street" : "321 Daffodil Lane", "street2" : "#12", "zip" : "EL321", "state" : "County", "phone" : "4412345785" }
1-10 December 2014 Callbacks
You should include shipping details for any purchase that requires delivery of physical goods.
Callbacks Callbacks can be made back to a merchant system either in-line with a transaction authorisation or asynchronously shortly after. Optimal Payments recommends asynchronous callbacks as the customer experience is significantly better. The callback system can detect problems with the merchant system and retry any failed attempts until a successful response is received.
You can avoid callbacks if you poll the self endpoint for the transaction ID. See the link.rel parameter in Table 1-17: Order Response Parameters on page 1-19.
To add callbacks to the order, add a callback array of objects to the JSON structure for each callback type required.
Table 1-9: Callback Parameters
Name Required Type Description
format Required Enum Possible values are: •json •get • form-urlencoded •xml
rel Required Enum This is the callback type, allowing different endpoints to be targeted depending on the end state of the transaction. Possible values are: •on_success •on_decline •on_hold Multiple callbacks of the same type are possible, and can be appended to the array.
retries Optional Int This specifies the number of callback attempts to make on the system after 0 to 10 receiving an error from the merchant endpoint.
returnKeys Optional Array This is an array of parameter names to be passed back to the URL in the format specified, including those passed in addendumData. See Table 1: Callback Return Keys on page B-1 for more information on this parameter.
synchronous Optional Boolean This parameter specifies that the callback should be made in-line with the authorisation. The system will time out any synchronous callback that takes longer than 20 seconds to complete. Possible values are: •true •false Default value is false. Optimal Payments recommends that this flag is set to false. Callbacks will be made back to the merchant within 10 minutes of a transaction attempt.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-11 Hosted Payments API December 2014
Table 1-9: Callback Parameters (Continued)
Name Required Type Description
uri Required String This is the URL to which to send the callback. If this is an HTTPS address, Max = 1024 please ensure that your certificate is valid – otherwise, the callback will fail.
delimiter Optional String This specifies the delimiter to use when parameters are sent to the callback Max = 10 URI (e.g, “;” “&” “$”). By default an ampersand (&) is used. NOTE: The delimiter parameter is supported only when the format param- eter is set to get or form-urlencoded.
The callback array is optional. However, if you include it, then the format, rel, and uri parameters are mandatory.
The callback array would look like this: "callback" : [ { "format" : "json", "rel" : "on_success", "retries" : 3, "returnKeys" : [ "id" ], "synchronous" : true, "uri" : "https://success.example.com/transaction_success.php" } ] Here are examples of the callbacks when setting returnKeys to id: • json – the JSON structure is posted in the response body: {"id":"####", "merchantRefNum": "####"} • xml – the XML document is posted in the response body:
Callbacks are retried every 5 minutes if a non-200 response is returned by the merchant, up to the num- ber of callback retries set by the merchant (default is 3).
Redirects Redirects are similar to callbacks in that they cause a connection back to the merchant system but from the browser of the customer instead. To add redirects to the order, add a redirect array of objects to the JSON structure.
1-12 December 2014 Links
Table 1-10: Redirect Parameters
Name Required Type Description
rel Required Enum This is the redirect type, allowing different endpoints to be targeted depending on the end state of the transaction. Possible values are: • on_success • on_error •on_decline • on_timeout • on_hold
returnKeys Optional Array This is an array of parameter names to be passed back to the URL in the format specified, including those passed in addendumData. See Table 2: Redirect Return Keys on page B-2 for more information on this parameter.
uri Required String This is the URL to which to send the redirect. If this is an HTTPS address, please Max = 1024 ensure that your certificate is valid – otherwise, the redirect will cause the browser to display a certificate warning.
delimiter Optional String This specifies the delimiter to use when parameters are sent to the redirect URI Max = 10 (e.g, “;” “&” “$”). By default an ampersand (&) is used.
The redirect array is optional when using the Optimal Payments Hosted Payments page, but mandatory when using a silent post. However, if you include it, then the rel and uri parameters are mandatory.
The redirect array would look like this: "redirect" : [ { "rel" : "on_success", "returnKeys" : [ "id" ], "uri" : "https://example.com/success.html" } ] In the event of multiple redirects with the same name being sent, only the first will be used. No parameters will be passed back by default. You can encode simple parameters into the URL and do not need to use returnKeys, provided the redirection URL is kept under 100 characters.
Never rely on a redirection to determine the end state of a transaction, as they can fail or be tampered with. Always use a callback or a “status” call to obtain transaction status.
Links To add links to the order, add a link array of objects to the JSON structure. You can send different links (e.g., to cancel a payment and return to the shopping basket). The link section works in the same way as redirects. All addendum data fields are available for the return keys, and a subset of callback parameters (see Callbacks on page 1-11).
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-13 Hosted Payments API December 2014
Table 1-11: Link Parameters
Name Required Type Description
rel Required Enum This is the link type, allowing different endpoints to be targeted depending on the end state of the transaction. Possible values are: •cancel_url • return_url
returnKeys Optional Array This is an array of parameter names to be passed back to the URL in the for- mat specified, including those passed in addendumData.
uri Required String This is the URL to which to send the link. If this is an HTTPS address, please Max = 1024 ensure that your certificate is valid – otherwise, the link will cause the browser to display a certificate warning.
The link array is optional. However, if you include it, then the rel and uri parameters are mandatory.
The link array would look like this: "link" : [ { "rel" : "cancel_url", "returnKeys" : [ "JSESSIONID" ], "uri" : "https://example.com/cancel.html" } ]
Payment methods To add payment methods to the order, add a paymentMethod array of objects to the JSON struc- ture.
1-14 December 2014 Payment methods
Table 1-12: Payment Method Parameters
Name Required Type Description
paymentMethod Optional Array This is the payment method. Possible values are: •card •giropay •ideal •interac • masterpass • neteller • paynearme •paypal •pingit •poli • prepaidcard • sofortbanking •ukash The default payment method is card. It does not have to be passed if card-only payments are required. You can specify one type or multiple types. The first option in the array will be presented as the default payment option on a transaction, with the opportunity to pay in the alternative methods on the payment page.
The paymentMethod array would look like this: "paymentMethod" : [ "card" ]
Payment method notes Table 1-13: Payment Method Notes
Payment Method Configure Merchant Account Process Refunds via the Notes with Payment Method Details Hosted Payments API
card No Yes
giropay Yes No
ideal Yes No
interac Yes Yes
masterpass No Yes
neteller Yes Yes
paynearme Yes No You can control the expiry date for a PayNearMe voucher by adding the orderTimeout variable as an extended option of the order. For example, setting the value to 172800 (seconds) would extend the expiry date by 48 hours.
paypal Yes Yes
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-15 Hosted Payments API December 2014
Table 1-13: Payment Method Notes (Continued)
Payment Method Configure Merchant Account Process Refunds via the Notes with Payment Method Details Hosted Payments API
pingit Yes No Pingit should be implemented as a Silent Post when possible to avoid an extra click. The Pingit applica- tion will open directly on the mobile device.
poli Yes No
prepaidcard No Yes
sofortbanking Yes No
ukash Yes No You should provide the Ukash change voucher (and expiry date) back to the voucher holder at the end of the transaction process in the event that the amount paid is less than the voucher value.
Addendum data Addendum data allows you to specify additional data (e.g., affiliate codes, session IDs, etc.) to be stored against the transaction and returned to you in status calls, reports, etc. Addendum data parameters are available to be sent back in callbacks and redirection URLs. To add addendum data to the order, add an addendumData array of objects to the JSON structure.
Table 1-14: Addendum Data Parameters
Name Required Type Description
key Required String This is a description of the data you are adding to the order. Max = 50
value Required String This is the value for the key/value pair. Max = 100
The addendumData array is optional. However, if you include it, then the key and value parameters are mandatory.
The addendumData array would look like this: "addendumData" : [ { "key" : "affiliate_code", "value" : "test12345" }, { "key" : "JSESSIONID", "value" : "ABCDE12345" }, ]
1-16 December 2014 Localisation
Up to 10 addendum data key/value pairs are enabled per order. They do not need to be defined in advance and can be different on each transaction.
addendumData for MasterPass If you are implementing MasterPass (see Table 1-12: Payment Method Parameters on page 1-15), you can include extra values in an addendumData array in order to override some default settings in your merchant account.
These keys are all optional. If they are not included in your request, the default settings of your merchant account will be used.
Table 1-15: MasterPass addendumData Key/Value Pairs
Key Name Key Value Description
acceptRewardProgram Boolean This allows you to receive reward details back if the shopper has an true/false accepted loyalty/reward card in MasterPass that is also enabled on your merchant account with Optimal Payments. See Obtaining an order status on page 1-30 for details.
suppressShippingAddress Boolean This allows you to prevent MasterPass from asking for a delivery address, true/false which is ideal, e.g., if you sell digital download goods.
shippingLocationProfile String This allows you to specify the countries that you deliver to, so that Max = 8 MasterPass does not return an address you are unable to ship to. MasterPass stores shipping address details for each card the customer has on file there. NOTE: If you set this location to a value that does not match the shipping address of the customer’s profile with MasterPass, the order will fail. Please contact the Customer Service team for available values.
The MasterPass addendumData array would look like this: "addendumData" : [ { "key" : "acceptRewardProgram", "value" : "false" }, { "key" : "suppressShippingAddress", "value" : "false" }, { "key" : " shippingLocationProfile ", "value" : "default" }, ]
Localisation Localisation enables the payment/receipt pages/emails to be displayed using the locale requested. The system will attempt a best-match to the localisation information passed in the locale parameter. To add localisation information to the order, pass the locale parameter as follows:
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-17 Hosted Payments API December 2014
"locale" : "en_GB" Currently supported values are: •en_GB •en_US •fr_CA •fr_FR
If the locale parameter is not passed or an unsupported ISO 639-1 code is sent to the API then the default value provided in the merchant’s integration configuration will be used.
Finance plan The accordD array allows you to specify a financing plan along with the regular order.
Do not include this array unless you are instructed to do so by Optimal Payments.
Table 1-16: accordD Parameters
Name Required Type Description
financingType Required Enumeration This is the type of financing offered. Possible values are: • DEFERRED_PAYMENT – Deferred payment financing • EQUAL_PAYMENT – Equal payment financing
plan Required String This is the plan number for this financing transaction. Max = 3
gracePeriod Conditional Integer This is the grace period, in months, associated with deferred payment Max = 99 transactions.
term Conditional Integer This is the number of payments, in months, for equal payment transac- Max = 99 tions.
The accordD array would look like this: { "accordD" : { "financingType" : "DEFERRED_PAYMENT", "plan" : "123", "gracePeriod" : 12 } }
Order response If everything in your order is set up correctly, the server will return an order response.
1-18 December 2014 Order response
Table 1-17: Order Response Parameters
Name Type Description
totalAmount Integer This is the amount of the transaction that was processed. E.g., 999 would be £9.99
currencyCode ISO4217 This is the currency in which the transaction was processed. E.g., GBP or USD
link.rel Enum This is the link type, allowing different results to be displayed, depending on the end state of the transaction. Possible values are: • hosted_payment – URI for the payment page. Customers should be redi- rected to this URI to see their invoice and complete payment; or this should be used as the form action on the merchant payment page if using a silent post. • self – This URI can be called to return a JSON object about the current status of the order, e.g., to see if the payment has been settled. • resend_callback – If a callback URI is specified in the initial request, calling this URI will re-queue the callback and resend it (which is useful if your call- back retries have run out).
link.uri String This is the URL to which the link was sent. Max = 1024
merchantRefNum String This is your own transaction ID, included in your initial transaction. Max = 40
mode Enum This parameter is for internal use only. Possible values are: •live
id String This ID represents the original transaction request. This ID will be used for sub- Max = 128 sequent transactions associated with the original request, such as making a pay- ment or requesting an order status.
profile.id String This is the customer ID of the profile created during the order request. Max = 80
The JSON structure for the response might look like this: { "link" : [ { "rel" : "hosted_payment", "uri" : "https://api.optimalpayments.com/hosted/v1/payment/53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8 d09b37db190a0f6ce44f8ea1461be2" }, { "rel" : "self", "uri" : "https://[api_key]@api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF" } ], "currencyCode" : "GBP", "totalAmount" : 1125, "mode" : "live", "type" : "order",
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-19 Hosted Payments API December 2014
"id" : "25TWPTLHRR81AIG1LF", "merchantRefNum" : "MERCHANT_REF_123" “profile” : { “id” : “1231”, }, } In this example, 53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8d09b37db190a0f6ce44f8ea 1461be2 is a secure version of the ID returned in the response to the initial order request.
Making a payment As a result of a successful call to the API, Optimal Payments will provide you with a hosted_pay- ment URL – this is the URL of the payment page. Note that the URL does not include the API key, so it is safe to hand back to the customer. To load the payment page, visit the link, or redirect your customer to the link from your shopping cart/back-end system. By default, the payment page is locked to the IP address that you passed in via the original request. You will need to create a loop based on the link array. Iterate through the array to identify the object where the rel is hosted_payment, and redirect your customer to the published URI. The status of the transaction can be tracked using the self URL, or you can specify a callback address in the initial call (see Callbacks on page 1-11). In the previous example payment (see Setting up an order on page 1-4), you would redirect the user to the page, which has no additional details. https://api.optimalpayments.com/hosted/v1/payment/53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8d 09b37db190a0f6ce44f8ea1461be2 Here, 53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8d09b37db190a0f6ce44f8ea1461be2 is a secure version of the ID returned in the response to the initial order request.
The secure version of the ID must be used to load payment pages because there is no API key present in the payment URL. The normal ID (i.e., ######) can be used for the other API calls because the merchant must use their API key for those calls.
The payment page for an order might look like this:
1-20 December 2014 Making a payment using a silent post
Upon a successful transaction, Optimal Payments can return a callback to notify you of the status of the request (see Callbacks on page 1-11).
Making a payment using a silent post You can allow your customers to make a payment on your own, branded payment page by using a silent post. As in the case of a regular payment, Optimal Payments will provide you with a hosted_payment URL when you make a successful call to the API – this is the URL of the payment page. The SUBMIT action of your payment form should be to the hosted_payment URL you have received from Optimal Payments (see Table 1-17: Order Response Parameters on page 1-19).
In order to make a payment using a silent post, you must include the extended option silentPost. See Appendix A: Extended Options.
You will need to create a loop based on the link array. Iterate through the array to identify the object where the rel is displayed, and set your form SUBMIT action to the published URI. The status of the transaction can be tracked using the self URL, or you can specify a callback address in the initial call (see Callbacks on page 1-11).
Silent post for prepaid cards To initiate a silent post for prepaid cards, set the fields on your payment page to the values in the following table.
Table 1-18: Silent Post Parameters for Prepaid Cards
Field Required Type Description
cardNum Conditional String This is the full prepaid card number. Min = 8 NOTE: Use either cardNum or referenceId. Max = 20
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-21 Hosted Payments API December 2014
Table 1-18: Silent Post Parameters for Prepaid Cards (Continued)
Field Required Type Description
referenceId Conditional String This is the reference ID for the prepaid card, returned in the Max = 36 response to the enrollments request that created the card. NOTE: Use either cardNum or referenceId.
lastFourSsn Yes String This is the last four digits of the customer’s Social Security Number. Length = 4
storeCardIndicator Optional Boolean This indicates whether the customer has granted permission to store card details for future use within their associated profile (if applicable). Possible values are: •true •false
Silent post for credit cards To initiate a silent post for credit cards, set the credit card fields on your payment page to the val- ues in the following table.
Table 1-19: Silent Post Parameters for Credit Cards
Field Required Type Description
cardNum Yes String This is the full card number. Min = 8 Max = 20
cardExpiryMonth Yes Integer This is the month the card expires. Total = 2
cardExpiryYear Yes Integer This is the year the card expires. Total = 2
cvdNumber Yes String This is the 3- or 4-digit security code that usually appears on the Total = 3 or 4 back of the card.
storeCardIndicator Optional Boolean This indicates whether the customer has granted permission to store card details for future use within their associated profile (if applicable). Possible values are: •true •false
If 3D Secure is enabled, then after a silent post the 3D Secure challenge will appear in a full, unbranded page on the Optimal Payments system. After the 3D Secure challenge, the system will redirect as per the rel/uri values sent in by the merchant (specified in Table 1-10: Redirect Parame- ters on page 1-13).
1-22 December 2014 Making a payment using a silent post
Silent post for Giropay To initiate a silent post for the giropay payment method, set the fields on your payment page to the values in the following table.
Table 1-20: Silent Post Parameters for giropay
Field Required Type Description
nbx_customerBIC Yes String This is the customer’s Bank Identifier Code (BIC).
nbx_customerIBAN Yes String This is the customer’s International Bank Account Number (IBAN).
Please consult Giropay documentation for maximum/minimum field values.
Silent post for iDEAL To initiate a silent post for the ideal payment method, set the fields on your payment page to the values in the following table.
Table 1-21: Silent Post Parameters for ideal
Field Required Type Description
senderHolder Yes String This is the owner of the sending account. Max = 27
senderIBAN Yes String This is the IBAN of the sending account. Max = 34
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-23 Hosted Payments API December 2014
Silent post for NETELLER To initiate a silent post for the neteller payment method, set the fields on your payment page to the values in the following table.
Table 1-22: Silent Post Parameters for neteller
Field Required Type Description
netAccount Yes Integer This is the NETELLER account ID.
secureId Yes Integer This is the password for the NETELLER account.
Please consult NETELLER documentation for maximum/minimum field values.
Silent post for Sofort Banking To initiate a silent post for the sofortbanking payment method, set the fields on your payment page to the values in the following table.
Table 1-23: Silent Post Parameters for sofortbanking
Field Required Type Description
senderHolder Yes String This is the name of the account owner.
senderBankBIC Yes String This is the Bank Identifier Code of the account.
senderIBAN Yes String This is the International Bank Account Number for the account.
senderCountryID Yes String The is the account owner’s country. Use ISO 3166-1 alpha-2 country codes.
Silent post for Ukash To initiate a silent post for the ukash payment method, set the fields on your payment page to the values in the following table.
Table 1-24: Silent Post Parameters for ukash
Field Required Type Description
voucherNumber Yes Integer This is the Ukash voucher number.
voucherValue Yes Integer This is the value of the Ukash voucher.
Please consult Ukash documentation for maximum/minimum field values.
Silent post for other supported payment methods For the following payment methods, no additional parameters need to be passed with the Silent Post order, as the redirect occurs immediately and no intermediary page is displayed:
1-24 December 2014 Making a payment using customer profile
•interac •masterpass • paynearme •paypal •pingit •poli
Making a payment using customer profile
Making a payment using a Hosted Payments customer profile If you have created a customer profile, you can use the Hosted Payments customer profile fea- tures for your customers to securely store their card details with Optimal Payments for future use. When the customer is redirected to the Hosted Payments page, they will see an option to store their card details.
If the customer chooses to store their card details, then the next time they return to make a pay- ment, you should pass the id (as described in Profile object example 3 on page 1-7). Redirect the cus- tomer to the Hosted Payments page, where they will see their stored card information.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-25 Hosted Payments API December 2014
The Hosted Payments customer profile feature offers customers the following options on the Hosted Payments page: • Store multiple cards • Set a card as default • Forget (remove) cards •Edit card expiry dates • Add/edit billing addresses
Making a silent post payment using a customer profile If you have created a customer profile for your customer, you may be able to submit fewer parameters with a silent post. • If you have provided a valid profile.id and profile.paymentToken in the order request, then you need to include only a value for cvdNumber in the silent post. • If you have provided only a valid profile.id (and no profile.paymentToken) in the order request, then you must include all values in Table 1-19: Silent Post Parameters for Credit Cards on page 1-22 in the silent post. In this case, an additional profile.paymentToken will be assigned to the profile.id and returned in the order response (see Table E-1: Order Status Response Parameters on page E-1) – this new token can then be used in future requests (i.e., a single profile.id can have multiple profile.paymentToken instances assigned to it). See Customer profiles on page 1-5 for more information.
Rebilling You can process a rebill against your customer’s card by using a previous successful order id. The rebill can be immediate or can be set up to run at a future date. Rebilling an order requires a POST to the following URL: curl u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \ https://api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF Here, 25TWPTLHRR81AIG1LF is the ID returned in the response to the initial order request. The following example would process an immediate rebill: { "totalAmount": 100, "currencyCode" : "GBP", "merchantRefNum": "XYZ" } The following example would process a rebill with a future date: { " totalAmount ": 100, "currencyCode" : "GBP", "merchantRefNum": "XYZ", "dueDate": "2013-06-22" } The following example would process a rebill with a future date, using a different merchant account: { " totalAmount ": 100, "currencyCode" : "GBP",
1-26 December 2014 Rebilling with a profile
"merchantRefNum": "XYZ", "dueDate": "2013-06-22", "extendedOptions" : [ { "key" : " merchantAccount", "value" : "REBILL99991234", } } A rebill request has the same parameter requirements as an order creation request, with the fol- lowing exceptions: •Do not include links and redirects, which are not applicable. • If the rebill is for a future date, then you must include the dueDate parameter. See Setting up an order on page 1-4 and Adding details to your order request on page 1-5.
Rebilling with a profile You can process a rebill against a customer’s profile by using a previous profile.id and profile.paymentToken and using the extended option recurringIndicator. The following example would process a payment against profile.id 123456 and paymentToken LgM8x0ymeXozGG1: { "totalAmount" : "100", "currencyCode" : "GBP", "merchantRefNum" : "mreference", "profile" : { "id" : "123456", "paymentToken": "LgM8x0ymeXozGG1" }, "extendedOptions": [ { "key" : "recurringIndicator", "value" : true } ] }
Rebill request response If the rebill is immediate, the server will return a rebill response. • To see the parameters returned in the response for a rebill request, see Table 1-17: Order Response Parameters on page 1-19. • The transaction details returned are the same as those described in Table E-1: Order Status Response Parameters on page E-1. If the rebill is in the future, then the server will return the parameters found in Table 1-17: Order Response Parameters on page 1-19.
Cancelling an order In order to cancel an order, call DELETE rather than GET on an order URL.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-27 Hosted Payments API December 2014
DELETE [api_key]@https://api.optimalpayments.com/hosted/v1/orders/{id}
Cancel order response If the order has been created but no card authorisation has taken place, then the same structure as for a GET status will be returned, except that the status will be set to cancelled. See Table E-1: Order Status Response Parameters on page E-1 for descriptions. If the order has been created and a card authorisation has taken place but has not yet been set- tled, then the system will attempt to process a reversal on the authorisation. The same structure as for a GET status will be returned, except that the status will be set to cancelled, and transaction.reversed will be set to true/false depending on the outcome of the reversal. In the event of an error (e.g., the payment has already been finalised or previously cancelled), an exception will be raised. The JSON structure for the cancel order response might look like this: { "currencyCode" : "GBP", "extendedOptions" : [], "link" : [ { "rel" : "self", "uri" : "https://[api_key]@api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF" } ], "merchantRefNum" : "QLB8W1BF6D3JDX4XKC", "id" : "25TWPTLHRR81AIG1LF", "totalAmount" : 7557, "transaction" : { "amount" : 7557, "associatedTransactions" : [], "authType" : "purchase", "settled" : false, "currencyCode" : "GBP", "lastUpdate" : "2012-06-01T17:12:14", "merchantRefNum" : "QLB8W1BF6D3JDX4XKC", "paymentType" : "card", "refunded" : false, "status" : "cancelled" } }
You can cancel a rebill request in the same way you can cancel an order. See Cancelling an order on page 1-27 for details.
Updating an order You can update certain items relating to an order. Updating an order requires a PUT to the following URL with the details of your update: PUT [api_key]@https://api.optimalpayments.com/hosted/v1/orders/{id}
1-28 December 2014 Updating a held order
Optimal Payments supports the following updates: • You can update an order with the status of held. • You can update a rebill.
Updating a held order You can request that an order with a transaction.status of held be released.
The merchant’s account must be configured by Optimal Payments to be able to place transactions on hold.
The example below would release an order to a status of success. { "transaction" : { "status": "success" } } The example below would release an order to a status of cancelled. { "transaction" : { "status": "cancelled" } }
When a held order is set to cancelled, an authorisation reversal will be attempted.
Updating rebills If a rebill has not been processed, then you can edit all of the details associated with that rebill. See Rebilling on page 1-26 for the list of values that can be edited. The example below would modify the amount and date of a rebill. { 'dueDate' : '2013-06-01', 'totalAmount' : 5545 }
Update response An update response will have the same structure as GET status except for the following: • When you update a held order, the status will be updated. See Table E-1: Order Status Response Parameters on page E-1 for descriptions. • When you update a rebill, the requested values will be updated (e.g., dueDate or amount). See Rebilling on page 1-26 for descriptions.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-29 Hosted Payments API December 2014
Obtaining an order status To find out the status of the transaction request, you can call the self link (returned in the response from Optimal Payments) at any time from your application, or from the command line. curl -u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \ https://api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF Here, 25TWPTLHRR81AIG1LF is the ID returned in the response to the initial order request.
Order status response If everything in your order status request is set up correctly, the server will return an order status response, which tells you everything we know about the status of the order. The parameters included in the order status response may include the parameters that were part of the original transaction request (see Setting up an order on page 1-4 and Adding details to your order request on page 1-5). See Appendix E: Order Status Response Parameters to see additional parameters that may be included in the response. The JSON structure for the order status response might look like this: { "link" : [ { "rel" : "hosted_payment", "uri" : "https://api.optimalpayments.com/hosted/v1/payment/53616c7465645f5ffeb47c2287dbf903bbb4627b16929a27b8 d09b37db190a0f6ce44f8ea1461be2" }, { "rel" : "self", "uri" : "https://[api_key]api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF" } ], "currencyCode" : "GBP", "transaction" : { "status" : "pending", "lastUpdate" : "2012-05-14T15:12:18", "authType" : "purchase", "merchantRefNum" : "MERCHANT_REF_123", "associatedTransactions" : [], "currencyCode" : "GBP", "refunded" : false, "amount" : 1000, "paymentType" : "card", "settled" : false }, "totalAmount" : 1000, "id" : "25TWPTLHRR81AIG1LF", "merchantRefNum" : "MERCHANT_REF_123" } The response contains all of the information you provided in the initial call, in the same struc- ture, but with two additional elements: •transaction •link
1-30 December 2014 Refunding an order
You can see from the transaction data that the status is pending, which means that the transaction has not been processed. This status will be updated if a payment is made and accepted.
Associated transactions parameters Table 1-25: Associated Transactions Parameters
Name Type Description
associatedTransactions.amount Integer This is any transaction relating to the original order (e.g., refund). E.g., 999 would be £9.99
associatedTransactions.authType Enum This is the transaction type. Possible values are: • auth – This is an authorisation-only transaction. • purchase – This is a transaction with immediate billing. • settlement – This transaction is the settlement of a previous authorisation-only transaction. • refund – This is a refund transaction.
associatedTransactions.datetime dateTime UTC This is the date and time at which the associated transaction was processed.
associatedTransactions.reference String This is the Optimal Payments reference for the associated transaction. Max = 20
Refunding an order Refunding an order requires a POST to the following URL: POST [api_key]@https//:api.optimalpayments.com/hosted/v1/orders/{id}/refund Table 1-26: Order Refund Parameters
Name Required Type Description
amount Optional Integer This is the amount to refund. If an amount is not specified, the full E.g., 999 would transaction is refunded. You can not refund more than the original be £9.99 amount authorised.
merchantRefNum Optional String This is your own transaction ID for this refund, for your reference Max = 40 purposes.
It is not currently possible to process refunds for Giropay, iDEAL, Pingit, POLi, Sofort Banking, or Ukash transactions via the API. You will need to issue these via your merchant account with the relevant payment method.
Order refund response The server will return a response containing the following parameters to your order refund.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-31 Hosted Payments API December 2014
Table 1-27: Order Refund Response Parameters
Name Type Description
amount Integer This is the amount of the transaction that was refunded. E.g., 999 would be £9.99
authType Enum This is the transaction type. It will be set to: •refund
confirmationNumber Integer This is the confirmation number returned by Optimal Payments in response to the refund request.
currencyCode ISO4217 This is the currency in which the transaction was refunded. E.g., GBP or USD
mode Enum This indicates whether the transaction was processed in a test or a live environment. Possible values are: •live •test
originalMerchantRefNum String This is the transaction ID you assigned to the original refund transaction, Max = 40 for your reference purposes.
id String This is the ID you included as part of the original refund transaction. Max = 128
The JSON structure for the order refund response might look like this: { "currencyCode" : "GBP", "amount" : 100, "originalMerchantRefNum" : "MERCHANTREF12346", "mode" : "live", "confirmationNumber" : 1997160616609792, "authType" : "refund", "id" : "25TWPTLHRR81AIG1LF" }
Settling an order Depending on your integration type, you may wish to settle a transaction at some point after the original authorisation (e.g., you are going to ship goods in a few days). The API is the same as for refunds: POST [api_key]@https://api.optimalpayments.com/hosted/v1/orders/{id}/settlement This will settle for the full amount. Optional parameters for amount and merchantRefNum can also be passed in a POST: curl -X POST \ -H "Content-Type: application/json" \ -u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \ -d '{ "amount": 100, "merchantRefNum": "XYZ" }' \ https://api.optimalpayments.com/hosted/v1/orders/25TWPTLHRR81AIG1LF/settlement
1-32 December 2014 Order settlement response
Table 1-28: Order Settlement Parameters
Name Required Type Description
amount Optional Integer This is the amount of the payment. If an amount is not specified, E.g., 999 would the full transaction is settled. You can not settle more than the orig- be £9.99 inal amount authorised.
merchantRefNum Optional String This is your own transaction ID for this payment, for your reference Max = 40 purposes.
Order settlement response The server will return a response to your payment completion. It has the same parameters as the response for an order refund, except the authType will be set to the value of settlement. See Table 1- 27: Order Refund Response Parameters on page 1-32 a description of the parameters. The JSON structure for the order completion response might look like this: { "amount" : 1125, "authType" : "settlement", "confirmationNumber" : 1998572559920972, "currencyCode" : "GBP", "mode" : "live", "originalMerchantRefNum" : null, "id" : "25TWPTLHRR81AIG1LF" }
Getting an order report You can retrieve a list of orders made to the API using a GET. • You can include an offset. • You can include the number of records to return (up to 100). •Use next and prev links, relative to the offset, to obtain the next/previous records (as applica- ble). curl -u jTxL2wsNysJ8Jzmpdwim:NAA043a7c53c66ac3826c5e \ https://api.optimalpayments.com/hosted/v1/orders?num=2&start=2 Table 1-29: Order Report Parameters
Name Required Type Description
num Optional Integer This is the number of records to return. Max = 100
start Optional Integer This is the record number at which to start. For example, setting the value to 20 would start the report at the 20th order.
Order report response Many of the parameters included in the order report response are the same as those included in the order status response (see Order status response on page 1-30). In addition, the order report response may contain the following parameters:
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-33 Hosted Payments API December 2014
Table 1-30: Order Report Response Parameters
Name Type Description
count Integer This is the total number of records available.
navigation.next String This is the URI to call to get the next set of records. Max = 1024
navigation.previous String This is the URI to call to get the previous set of records. Max = 1024
num Integer This is the number of records to return per request. Max = 100
If everything is set up correctly, the server will respond with this JSON structure. The full order (including all passed parameters and extended options) is returned in the array. In the event that all orders are returned, no next/prev links will be supplied. { "count" : 2, "navigation" : { "prev" : "https://api.optimalpayments.com/hosted/v1/orders?num=2&start=0", "next" : "https://api.optimalpayments.com/hosted/v1/orders?num=2&start=0" }, "records" : [ { "currencyCode" : "GBP", "extendedOptions" : [], "merchantRefNum" : "AFHXRY6PS2WFQNXR0K", "id" : "25TWPTLHRR81AIG1LF", "totalAmount" : 125, "transaction" : { "amount" : 125, "associatedTransactions" : [], "authType" : "purchase", "settled" : false, "currencyCode" : "GBP", "lastUpdate" : "2012-05-31T09:08:32", "merchantRefNum" : "AFHXRY6PS2WFQNXR0K", "paymentType" : "card", "refunded" : false, "status" : "Success" } }, { "currencyCode" : "GBP", "customerIp" : "127.0.0.1", "extendedOptions" : [], "merchantRefNum" : "1", "paymentMethod" : [ "card" ], "id" : "25TWPTLHRR81AIG1LF", "totalAmount" : 150,F
1-34 December 2014 Resending a callback
"transaction" : { "amount" : 150, "associatedTransactions" : [], "authType" : "purchase", "settled" : false, "currencyCode" : "GBP", "lastUpdate" : "2012-06-01T11:44:56", "merchantRefNum" : "1", "paymentType" : "card", "refunded" : false, "status" : "Success" } } ], "num" : 2 }
Resending a callback You can request that callbacks be resent to your merchant system, as you have configured them for the initial transaction. See Callbacks on page 1-11 for details. Resending a callback requires a GET to the following URL: GET [api_key]@https://api.optimalpayments.com/hosted/v1/orders/{orderId}/resend_callback
Resend callback response The server will return a 200 HTTP status code if successful. Otherwise, an error will be returned. See Appendix C: Error Responses for details.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 1-35 Hosted Payments API December 2014
1-36 APPENDIX A
Extended Options
Introduction Extended options enable you to activate/deactivate certain features in the payment system. For example, if you are passing in billing information from your system, you may wish to prevent it being edited on the payment page. You can disable fields from being editable by setting an extended option. To add extended options to the order, add an extendedOptions array of objects to the JSON struc- ture.
Table A-1: Extended Options Parameters
Name Required Type Description
key Optional String This is a description of the option you are Max = 40 adding to the order.
value Optional See the Type column in Table A-2: Extended This is the value for the key/value pair. Options Key/Value Pairs on page A-1.
The extendedOptions array might look like this: "extendedOptions" : [ { "key" : "callbackEmail", "value" : "[email protected]", } { "key" : "emailNotEditable", "value" : "1" }
]
Key/value pairs for extended options Table A-2: Extended Options Key/Value Pairs
Key Type Description
authType String Allows merchants to specify that a transaction is Authorize Max = 20 Only, where the customer will not be billed until some time in the future. Possible values are: •auth •purchase
callbackEmail String Allows merchants to receive an email that contains the Max = 256 same data they would receive if they were to query the self URL returned from the API.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 A-1 Extended Options December 2014
Table A-2: Extended Options Key/Value Pairs (Continued)
Key Type Description
disableDuplicateMerchantRefCheck Boolean Allows merchants to submit an order using a duplicate merchantRefNum parameter. By default this is set to false.
dupCheckCardMaxAllowed Integer Indicates the number of existing customer profiles that are allowed to contain the same card number. For example, if dupCheckCardMaxAllowed is assigned a value of 2, then the card can be added to two profiles. • In order to enforce complete uniqueness, assign dupCheckCardMaxAllowed a value of 1. •If dupCheckCardMaxAllowed is not included, then the card can be added to an unlimited number of profiles.
merchantAccount String Allows merchants to specify the merchant account ID for Max = 40 which to process the order. This feature should be used if a merchant has more than one merchant account they wish to use within the same integration. This feature must be configured by Optimal Payments before use.
orderTimeout Integer Indicates how many seconds an order remains valid (see Min = 300 Setting up an order on page 1-4). Max = 2592000 Current supported values are from 5 minutes to 30 days (300–2592000 seconds). If a timeout occurs and a customer is directed to the host- ed_payment URI, or if silent post details are submitted, then an error will be raised. Merchants can also specify that customers are returned to the on_timeout URL (see Table 1-10: Redirect Parameters on page 1-13).
recurringIndicator Boolean Allows merchants to specify that the transaction is recurring and does not require the cvdNumber element. See Rebilling on page 1-26 for more information.
silentPost Boolean Allows merchants to submit a Silent Post order. See Making a payment using a silent post on page 1-21.
skip3D Boolean Allows merchants to skip 3D Secure for an order. Possible values are: •true •false
suppressCustomerEmail Boolean Allows merchants to include the customerNotificationEmail parameter in an order but without having Optimal Pay- ments send an email to the customer notifying them of the purchase. This gives merchants the ability to show/capture the cus- tomer’s email address on the payments page but not send an email.
A-2 December 2014 Key/value pairs for extended options
Table A-2: Extended Options Key/Value Pairs (Continued)
Key Type Description
threatMetrixSessionId String This allows silent post merchants to specify their own Max = 128 session_id for use with ThreatMetrix (see Appendix D: ThreatMetrix Silent Post). The value should be unique per request. The ID can be up to 128 characters long It must consist of the following characters only: • Upper and lowercase English letters (a-z, A-Z) • Digits (0-9) • Underscore or hyphen ( _, -)
Optimal Payments Hosted Payments API Reference Guide 1.3.4 A-3 Extended Options December 2014
A-4 APPENDIX B
Return Keys
Callback return keys Table 1: Callback Return Keys
Return Key Description
profile.paymentToken This is the payment token returned by Optimal Payments which can be used to process a repeat payment. See Table 1-4: Profile Parameters on page 1-6.
profile.id This is the customer ID returned by Optimal Payments when a profile was created. See Table 1-4: Profile Parameters on page 1-6.
profile.firstName This is the customer’s first name.
profile.lastName This is the customer’s last name.
customerNotificationEmail This is the consumer’s email address, to which notifications regarding the order request are sent.
transaction.errorCode If an error occurs, this is the error number.
transaction.errorMessage If an error occurs, this is the description of the error.
id This the transaction ID returned in the response to the initial order request.
transaction.confirmationNumber This is the confirmation number returned by Optimal Payments in response to the order request.
transaction.amount This is the amount of the transaction that was processed.
transaction.authCode This is the transaction authorization code.
transaction.authType This is the transaction type.
transaction.status This indicates the status of the transaction.
transaction.currencyCode This is the currency in which the transaction was processed.
transaction.merchantRefNum This is the merchant’s transaction ID, included in the initial transaction request.
transaction.card.brand This is the brand of the card used for the transaction.
transaction.card.country This is the country of origin for the card used for the transaction.
transaction.card.expiry This is the expiry date of the card used for the transaction.
transaction.card.lastDigits This is the last four digits of the card used for the transaction.
transaction.card.threeDEnrolment This indicates the enrollment status in the 3D Secure program of the card used for the transaction.
transaction.card.threeDResult This indicates the outcome of the authentication request for the card used for the transaction.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 B-1 Return Keys December 2014
Table 1: Callback Return Keys (Continued)
Return Key Description
transaction.card.type This is the type of card used for the transaction.
transaction.paymentType This is the type of payment used for the transaction.
transaction.sofortBanking.sofortBankingTxId This is the Sofort Banking transaction ID.
transaction.sofortBanking.internationalTransaction This is the flag for international transactions.
transaction.prepaidcard.lastDigits This is the last four digits of the prepaid card used for the transaction.
Redirect return keys Table 2: Redirect Return Keys
Return Key Description
id This the transaction ID returned in the response to the initial order request.
profile.firstName This is the customer’s first name.
profile.lastName This is the customer’s last name.
customerNotificationEmail This is the consumer’s email address, to which notifications regarding the order request are sent.
transaction.confirmationNumber This is the confirmation number returned by Optimal Payments in response to the order request.
transaction.amount This is the amount of the transaction that was processed.
transaction.authCode This is the transaction authorization code.
transaction.status This indicates the status of the transaction.
transaction.errorCode If an error occurs, this is the error number.
transaction.errorMessage If an error occurs, this is the description of the error.
transaction.riskReasonCode If the transaction has a status of held, these are the reason codes.
B-2 APPENDIX C
Error Responses
If an error occurs when you are attempting your transaction, only an error response will be returned to your system. All errors are returned with the following JSON structure with a non- 200 HTTP status code: { "error": { "code": "123", "message": "Invalid parameter…" } } You should rely primarily on the HTTP status codes to determine the outcome of requests. Appli- cation codes are provided for debugging and for disambiguation where necessary, but may not always be available. Application code will also be provided in the HTTP response header X-Application-Status-Code. The following table describes the error responses you could receive, as well as the action you can take, where applicable.
Table 1: Error Responses
Error Message Action to Take
Request validation failed: mer- You have provided an invalid merchantRefNum parameter with your request. Please chant_ref_num invalid: required verify this parameter and retry the transaction. field
Request validation failed: curren- You have provided an invalid currencyCode parameter with your request. Please verify cy_code invalid: required field this parameter and retry the transaction.
Request validation failed: You have provided an invalid totalAmount parameter with your request. Please verify total_amount invalid: required field this parameter and retry the transaction.
Not authorised Verify that you are including the correct API key, and retry the request.
Invalid ID Verify that you are including the correct ID, and retry the request.
Transaction already processed You are attempting to make a second payment against an existing token. No further action is required.
Cannot update transaction You are attempting to update a transaction that cannot be updated. • If the request is to release a hold then ensure the transaction has the status of held. • If the request is to update a rebill then ensure the dueDate has not passed.
Time for completing payment has You are attempting to complete a payment for which the orderTimeout period has expired expired. See Table A-2: Extended Options Key/Value Pairs on page A-1.
Token expired You are attempting to make a payment against a token that has expired. No further action is required.
Duplicate merchant reference You are attempting a transaction using a merchantRefNum that has already been used. Please provide a different merchantRefNum and retry the transaction.
Duplicate merchant customer ID You are attempting to create a profile using a merchantCustomerId that has already been used. Please provide a different merchantCustomerId and retry the request.
Transaction not yet processed You are attempting to refund is a transaction that has not been processed. Please verify that you are including the correct token. No further action required.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 C-1 Error Responses December 2014
Table 1: Error Responses
Error Message Action to Take
Amount exceeds refundable You are attempting to refund an amount that is greater than the original transaction amount amount (minus the sum of any existing refunds against the transaction). Please verify that the transaction has not already been refunded and that you are including the cor- rect token, and retry the transaction.
Resend callback failed Please verify that you are including the correct token and retry the transaction.
Card number was not provided Please verify that the card number is sent in the cardNum field.
You submitted an expired credit Please verify the cardExpiryYear and cardExpiryMonth parameters and retry the request. card number with your request. If these values were sent correctly, then the card has expired.
Invalid profileId A profile could not be loaded for the profileId provided.
Configuration error An error occurred with your merchant account configuration. Please contact Technical Support.
C-2 APPENDIX D
ThreatMetrix Silent Post
Overview ThreatMetrix is a service that anonymously profiles your website visitor’s computer in real time to determine its unique fingerprint – derived from over 150 attributes obtained from such data as TCP/IP packets, operating system, fonts, language, time zone, operating system, browser, and more, matching it against a global collection of data from previously profiled computers and their transactions. Implementing the ThreatMetrix service provides merchants with an addi- tional layer of protection that reduces lost sales from false negatives, reduces fraud chargebacks and associated fees, and minimizes fraud management expense by reducing the number of transactions sent for manual review.
Implementing ThreatMetrix
To implement ThreatMetrix for a silent post order: 1. Set up an order and retrieve the id from the order response from Optimal Payments (see Table 1-17: Order Response Parameters on page 1-19 to see the id). 2. Insert that id along with the org_id – which Optimal Payments will provide you – in the pro- filing HTML (see HTML on page D-2). 3. Insert this profiling HTML on one or more pages of your e-commerce site.
In order for this profiling HTML to be effective, you must place it on a page on which your customer will stay for at least 3–5 seconds.
4. Configure a Web server URL redirect so that the objects in the profiling code that reside on h.online-metrix.net can be referenced on your local domain. This will enable maximum attrib- ute collection (some browsers will attempt to block third-party domains). See Redirecting the profile server URL on page D-3 for details. 5. When your customer visits the page containing the profiling HTML on your site to make a purchase, the ThreatMetrix process is launched and the resulting profile and score are inte- grated into the Optimal Payments risk assessment of that transaction.
Should you wish to use your own value for the session_id then please see threatMetrixSessionId in Table A-2: Extended Options Key/Value Pairs on page A-1.
Profiling HTML Optimal Payments provides the profiling HTML, below, to insert on your e-commerce site. The code should be placed inside the
section of your HTML pages.Optimal Payments Hosted Payments API Reference Guide 1.3.4 D-1 ThreatMetrix Silent Post December 2014
• If placed at the beginning of the
section, the profiling can begin sooner, but may have a slight impact on your page render time. • If placed at the end of the section, the profiling tags will not affect the render time of your page, but it may take slightly more time to complete the profiling. The profiling HTML contains two dynamic variables: org_id and session_id. The rest of the code is static.Table D-1: Dynamic Variables
Variable Description
org_id The org_id parameter uniquely identifies the Optimal Payments account with ThreatMetrix. Optimal Pay- ments will provide you with the value for this parameter.
session_id For the session_id, use the id you receive in the response to the initial order for which you want to imple- ment ThreatMetrix profiling. See Table 1-17: Order Response Parameters on page 1-19 for details.
HTML This is an example of the HTML you could insert in your e-commerce site, amended as required (e.g., inserting proper values for the org_id and session_id variables).
D-2 December 2014 Redirecting the profile server URL
Redirecting the profile server URL In the sample HTML above, all objects refer to the server h.online-metrix.net. This is the DNS name of the ThreatMetrix profiling server. In your Production environment you should use a local URL and configure your Web server to redirect to h.online-metrix.net. Otherwise, visitors can configure their Web browser to block the third-party h.online-metrix.net domain and disable pro- filing. In addition, many customers prefer that all objects in their Web pages refer only to their own domain. Configuring redirection is Web server–specific. Here are two ways to do that using Apache (tested with Apache 2.2). Both methods will cause the Apache Web server to send an HTTPS REDIRECT reply for any URL path beginning with /fp/ on the host name it is configured for. The calling page remains the same in the customer’s browser; only the URL appearing in the profil- ing HTML is changed. This reply tells the HTTP client to re-fetch the new URL instead of the one embedded in the HTML page. Users who view the source of the HTML page itself will not notice that the links are actually redirected to another server. However, tracing tools will still show that a call was being made to an external server.
RedirectMatch Ensure that mod_alias is enabled in the Apache configuration. To do so, make sure the following line is included in the main Apache configuration file (/etc/httpd/conf/httpd.conf on RHEL5): LoadModule alias_module modules/mod_alias.so On most standard Apache configurations this is the default, in which case no action is required on your part. Add the following line to the relevant VirtualHost: RedirectMatch ^/(fp/.*) https://h.online-metrix.net/$1
Rewrite Module Ensure that mod_rewrite is enabled in the Apache configuration. To do so, make sure the following line is included in the main Apache configuration file (/etc/httpd/conf/httpd.conf on RHEL5): LoadModule rewrite_module modules/mod_rewrite.so On most standard Apache configurations this is the default, in which case no action is required on your part. Add the following to the relevant VirtualHost: RewriteEngine On RewriteRule ^/(fp/.*) https://h.online-metrix.net/$1 [L,R]
Optimal Payments Hosted Payments API Reference Guide 1.3.4 D-3 ThreatMetrix Silent Post December 2014
D-4 APPENDIX E
Order Status Response Parameters
Order status response In addition to the parameters that were part of the original transaction request, the order status response may contain the following parameters.
Table E-1: Order Status Response Parameters
Name Type Description
id String This is the ID provided in the original order status Max = 128 transaction request.
transaction.amount Integer This is the amount of the transaction that was pro- E.g., 999 would cessed. be £9.99
transaction.associatedTransactions Array This returns a JSON array of other transactions associated with the order, e.g., refunds and com- pletions. Each member of the list refers to a specific opera- tion that was executed against the order. For exam- ple, three refunds of £1.00 would show up as three individual associatedTransactions refunds, not as one refund of £3.00. See Associated transactions parameters on page 1-31 for a description of associated parameters.
transaction.authCode String This is the authorization code assigned by the issu- Max = 50 ing bank and returned by Optimal Payments for the transaction.
transaction.authType Enum This is the transaction type. Possible values are: • auth – This is an authorisation-only transaction. • purchase – This is a transaction with immediate billing. • settlement – This transaction is the settlement of a previous authorisation-only transaction. • refund – This is a refund transaction.
transaction.availableToRefund Integer This is the amount available to refund on the initial e.g., 999 would order. be £9.99
Optimal Payments Hosted Payments API Reference Guide 1.3.4 E-1 Order Status Response Parameters December 2014
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.card.brand Enum This is the brand of the card used. Possible values are: • amex (American Express) • cb (Carte Bleue) •discover •diners • international maestro •jcb • mastercard • mastercard debit •maestro •visa •visa debit • visa electron
transaction.card.country String This is the country of origin for the card used. Max = 2 Use ISO 3166-1 alpha-2 country codes.
transaction.card.expiry String This is the expiry date of the card used. Max=7 Format = mm/yyyy
transaction.card.lastDigits String This is the last four digits of the card used. Max = 4
transaction.card.threeDEnrolment Enum This indicates the enrollment status of the card in the 3D Secure program. Possible values are: • Y – Authentication available • N – Cardholder not enrolled • U – Authentication unavailable • E – Error
transaction.card.threeDResult Enum This indicates the outcome of the authentication request. Possible values are: • Y – Cardholder successfully authenticated with their Card Issuer. • A – Cardholder authentication was attempted. • N – Cardholder failed to successfully authenti- cate with their Card Issuer. • U – Authentication with the Card Issuer was unavailable. • E – Error
transaction.card.type Enum This is the type of card used. Possible values are: •debit •credit
transaction.prepaidcard.lastDigits String This is the last four digits of the prepaid card that Max = 4 was used for the transaction.
transaction.cleared Boolean The transaction has been sent to the bank for clear- ing. Possible values are: •true •false
E-2 December 2014 Order status response
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.settled Boolean The authorisation-only transaction has been set- tled. Possible values are: •true •false
transaction.confirmationNumber Integer This is the confirmation number returned by Opti- mal Payments in response to the transaction request.
transaction.currencyCode ISO4217 This is the currency in which the transaction was E.g., GBP or USD processed.
transaction.lastUpdate dateTime UTC This is the date and time of the last change made to the transaction, e.g., a refund.
transaction.merchantRefNum String This is your own transaction ID, included in your Max = 40 initial transaction.
transaction.paymentType String This is the type of payment used for the transac- Max = 20 tion. Value will be set to: •card •giropay •ideal •interac • masterpass • neteller • paynearme •paypal •pingit •poli • prepaidcard • sofortbanking •ukash
transaction.giropay.giropay.TxId String This is the Giropay transaction ID. Please consult Giropay documentation for all Giropay maximum/minimum field values.
transaction.giropay.paymentPurposeLine_1 String This is a Giropay merchant reference.
transaction.giropay.paymentPurposeLine_2 String This is a Giropay merchant reference.
transaction.giropay.transactionId Integer This is a Giropay transaction ID.
transaction.giropay.fullBankResponse String This is the bank response code.
transaction.giropay.authCode String This is a Giropay authorization code.
transaction.giropay.operatorId String This is Giropay’s unique merchant identification.
transaction.giropay.beneficiaryName_1 String This is the first part of the beneficiary’s name.
transaction.giropay.beneficiaryName_2 String This is the second part of the beneficiary’s name.
transaction.giropay.beneficiaryAcctNo Integer This is the beneficiary’s bank account number.
transaction.giropay.beneficiaryBankBlz Integer This is the beneficiary’s bank ID.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 E-3 Order Status Response Parameters December 2014
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.giropay.beneficiaryBic String This is the beneficiary’s international Bank Identi- fier Code.
transaction.giropay.beneficiaryIban String This is the beneficiary’s International Bank Account Number.
transaction.giropay.customerAcctNo Integer This is the customer’s bank account number.
transaction.giropay.customerBankBlz Integer This is the customer’s bank ID.
transaction.giropay.customerBic String This is the customer’s international Bank Identifier Code.
transaction.giropay.customerIban String This is the customer’s International Bank Account Number.
transaction.giropay.transType Integer This is the transaction type ID.
transaction.giropay.email String This is the customer’s email address.
transaction.giropay.currency String This is the 3-character currency code.
transaction.giropay.authResult String This is the result of the authorization.
transaction.giropay.extensionSic Integer This is the expanded status code.
transaction.giropay.rc Integer This is the return code.
transaction.giropay.merchantId String This is the merchant ID.
transaction.giropay.merchantReference String This is the merchant reference ID.
transaction.giropay.amount Integer This is the amount of the payment.
transaction.giropay.merchantNumber Integer This is the merchant number.
transaction.ideal.IdealTxId String This is the iDEAL transaction ID. Max = 27
transaction.paypalToken String This is the PayPal token. Please consult PayPal documentation for all PayPal maximum/minimum field values.
transaction.paypalTransactionId String This is the PayPal transaction reference ID.
transaction.neteller.net_account String This is the NETELLER account ID. Please consult NETELLER documentation for all NETELLER maximum/minimum field values.
transaction.neteller.neteller_type String This is the type of NETELLER payment.
transaction.neteller.fxrate String This is the foreign exchange rate applied (if appli- cable).
transaction.neteller.da_amount String The amount of the transfer that is being withdrawn from the bank account registered with the mem- ber’s NETELLER account. The amount may have decimal places but no currency symbols.
E-4 December 2014 Order status response
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.neteller.total_fee String This is the total fee charged for the transfer if it was a Direct Accept transaction (i.e., fee plus dafee).
transaction.neteller.trans_id String This is the NETELLER transaction ID.
transaction.neteller.dafee String The additional fee charged for the transfer if it was a Direct Accept transaction.
transaction.neteller.client_amount String This is the amount taken from the client’s NETELLER account.
transaction.neteller.client_currency String This is the client’s currency. ISO4217 E.g., GBP or USD
transaction.neteller.merchant_amount String The amount moved to the merchant’s account.
transaction.neteller.merchant_currency String This is the merchant’s currency. ISO4217 E.g., GBP or USD
transaction.poli.poliRef String This is the POLi ID associated with the transaction.
transaction.poli.poliToken String This is an encrypted POLi ID.
transaction.poli.state String This is the state of the transaction.
transaction.sofortBanking.sofortBankingTxId String This is the Sofort Banking transaction ID. Please consult Sofort Banking documentation for all Sofort Banking maximum/minimum field val- ues.
transaction.sofortBanking.internationalTransaction Boolean This is the flag for international transactions.
transaction.ukash.voucherValue String This is the value of the voucher. Please consult Ukash documentation for all Ukash maximum/minimum field values.
transaction.ukash.settleAmount String This is the amount deducted from the voucher.
transaction.ukash.changeVoucherCurrency String This is the currency of the change voucher the cus- tomer receives.
transaction.ukash.changeIssueAmount String This is the amount of the change voucher the cus- tomer receives.
transaction.ukash.amount String This is the amount processed for the transaction request.
transaction.ukash.changeIssueExpDate String This is the expiry date of the change voucher.
transaction.ukash.redemptionType String This is the Ukash redemption type.
transaction.ukash.ukashTransactionId String This is the Ukash transaction ID.
transaction.ukash.voucherNumber String This is the Ukash voucher number.
Optimal Payments Hosted Payments API Reference Guide 1.3.4 E-5 Order Status Response Parameters December 2014
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.refunded Boolean This indicates that the transaction has been either fully or partially refunded. Possible values are: •true •false NOTE: If this value is set to true, then check the value for availableToRefund before attempting to issue a refund request.
transaction.status Enum This indicates the status of the transaction. Possible values are: • success – Transaction has been authorized by bank/Optimal Payments. • cancelled – Transaction has been cancelled. • declined – Transaction has been declined by bank/Optimal Payments. • pending – Transaction has been created and is awaiting consumer interaction. • abandoned – Transaction was abandoned part way through by the consumer. • held – Transaction has been placed on hold due to risk rules results. See transaction.riskReason- Code for the for the reason codes. • errored – An error occurred and the transaction could not be completed. NOTE: Your merchant account must be configured by Optimal Payments to be able to place transac- tions on hold.
transaction.errorCode Integer If an error occurs, this is the error number.
transaction.errorMessage String If an error occurs, this is the error message.
transaction.riskReasonCode Integer If the transaction has a status of held, these are the reason codes.
transaction.zipVerification Enum This is the result of the AVS check received from the bank. Possible values are: • Matched – The zip value provided matches the zip value associated with the card. • Not Matched – The zip value provided does not match the zip value associated with the card. • Not Checked – The zip value was not processed.
transaction.houseNumberVerification Enum This is the result of the AVS check received from the bank. Possible values are: • Matched – The house number value provided matches the house number value associated with the card. • Not Matched – The house number value pro- vided does not match the house number value associated with the card. • Not Checked – The house number value was not processed.
E-6 December 2014 Order status response
Table E-1: Order Status Response Parameters (Continued)
Name Type Description
transaction.cvdVerification Enum This is the result of the CVV check received from the bank. Possible values are: • Matched – The CVD value provided matches the CVD value associated with the card. • Not Matched – The CVD value provided does not match the CVD value associated with the card. • Not Checked – The CVD value was not pro- cessed.
transaction.masterpass.id String This is the MasterPass transaction ID.
transaction.masterpass.reward.id String This is the ID associated with the reward program.
transaction.masterpass.reward.number String This is the consumer’s reward number associated with the reward program
transaction.masterpass.reward.name String This is the name of the reward program.
transaction.masterpass.reward.expiry.month Integer This is the month the reward program expires.
transaction.masterpass.reward.expiry.year Integer This is the year the reward program expires.
profile.paymentToken String This is the payment token returned by Optimal Max = 80 Payments in response to the transaction request. It can be used to process a repeat payment.
profile.id String This is the customer ID of the profile created Max = 80 during the order request.
dueDate Date This is the date the order request will be pro- YYYY-MM-DD cessed. (UTC)
Optimal Payments Hosted Payments API Reference Guide 1.3.4 E-7 Order Status Response Parameters December 2014
E-8