API Reference Guide for Web Services
January 2021 Version 1.0 This manual and accompanying electronic media are proprietary products of Paysafe Holdings UK Limited. They are to be used only by licensed users of the product. © 1999–2019 Paysafe Holdings UK Limited. All rights reserved. The information within this document is subject to change without notice. The software described in this document is provided 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 trans- ferred in any form or by any means without the express written consent of Paysafe Holdings UK Limited. All other names, trademarks, and registered trademarks are the property of their respective owners. Paysafe Holdings UK Limited 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 Pay- safe Holdings UK Limited – www.paysafe.com Contents
1 Paysafe Web Services
What are Paysafe Web Services?...... 1-1 Web Services supported for Direct Debit ...... 1-1 Web Services supported for credit cards ...... 1-2 Web Services supported for Information Lookup Service...... 1-2 System requirements...... 1-3 Accessing the Paysafe WSDLs and links...... 1-3 Direct Debit...... 1-3 Credit card ...... 1-4 Information Lookup Service ...... 1-4 Testing Paysafe Web Services ...... 1-4 Security features ...... 1-4 AVS ...... 1-4 CVD ...... 1-5 Negative database...... 1-6 3D Secure ...... 1-6 Using this guide ...... 1-6 Audience ...... 1-6 Functionality...... 1-6 Symbols ...... 1-7
2 Direct Debit Transactions
Introduction...... 2-1 .NET example ...... 2-2 Building charge or credit requests...... 2-3 charge example – C# ...... 2-3 ddCheckRequestV1 schema ...... 2-5 ddCheckRequestV1 elements ...... 2-6 Special considerations for Direct Debit elements...... 2-11 Building updateShippingInfo requests ...... 2-12 updateShippingInfo example – C# ...... 2-12 ddShippingRequestV1 schema ...... 2-14 ddShippingRequestV1 elements ...... 2-14 Building lookup requests ...... 2-16 Lookup example – C# ...... 2-16 ddLookupRequestV1 schema ...... 2-18 ddLookupRequestV1 elements ...... 2-18 Building BACS mandate requests (UK) ...... 2-19
API Reference Guide for Web Services 1.0 III May 2019
Building SEPA mandate requests ...... 2-20 mandate example – C# ...... 2-20 ddMandateRequestV1 schema...... 2-22 ddMandateRequestV1 elements ...... 2-23 Building change status requests ...... 2-25 Change status example – C#...... 2-26 ddChangeStatusRequest schema ...... 2-27 ddChangeStatusRequestV1 elements ...... 2-27 Building mandate update requests ...... 2-28 Mandate update example – C#...... 2-28 ddUpdateMandateRequestV1 schema ...... 2-29 ddUpdateMandateRequestV1 elements ...... 2-29 Processing the response ...... 2-30
3 Credit/Debit Card Transactions
Introduction ...... 3-1 .NET example ...... 3-3 Building Purchase/Authorization/Verification requests ...... 3-4 Purchase example – C#...... 3-5 ccAuthRequestV1 schema ...... 3-7 ccAuthRequestV1 elements ...... 3-8 addendumData tag/value pairs ...... 3-17 Building Authorization Reversal requests...... 3-18 Authorization Reversal example – C#...... 3-18 ccAuthReversalRequestV1 schema ...... 3-19 ccAuthReversalRequestV1 elements ...... 3-20 Building Settlement/Credit requests ...... 3-21 Settlement example – C# ...... 3-21 ccPostAuthRequestV1 schema...... 3-22 ccPostAuthRequestV1 elements...... 3-23 Building Stored Data Requests ...... 3-25 Stored Data Authorization example – C# ...... 3-25 ccStoredDataRequestV1 schema ...... 3-26 ccStoredDataRequestV1 elements ...... 3-27 Building Cancel requests...... 3-28 Cancel Settle example – C# ...... 3-28 ccCancelRequestV1 schema ...... 3-29 ccCancelRequestV1 elements...... 3-30 Building Payment/Independent Credit requests...... 3-31 Payment example – C# ...... 3-31 ccPaymentRequestV1 schema ...... 3-33 ccPaymentRequestV1 elements ...... 3-33 Building Transaction Lookup requests ...... 3-36 Transaction Lookup example – C# ...... 3-36 ccTxnLookupRequestV1 schema...... 3-38
IV May 2019
ccTxnLookupRequestV1 elements ...... 3-38 Building Enrollment Lookup requests ...... 3-40 Enrollment Lookup example – C# ...... 3-40 ccEnrollmentLookupRequestV1 schema...... 3-41 ccEnrollmentLookupRequestV1 elements...... 3-41 Building Authentication requests ...... 3-43 Authentication example – C# ...... 3-43 ccAuthenticateRequestV1 schema ...... 3-44 ccAuthenticateRequestV1 elements ...... 3-44 Processing the response ...... 3-46 detail tag/value pairs ...... 3-53 addendumResponse tag/value pairs ...... 3-53 Currency codes...... 3-53
4 Information Lookup Service Transactions
Introduction...... 4-1 Paysafe ILS WSDLs and links ...... 4-1 .NET example ...... 4-2 Building ILS requests ...... 4-3 ILS – C# ...... 4-3 ilsLookupRequestV1 schema ...... 4-5 ilsLookupRequestV1 elements ...... 4-5 Processing the response ...... 4-8 ilsLookupResponseV1 schema ...... 4-9 Response element contents ...... 4-12 Authorizations response details...... 4-12 Settlements response details...... 4-12 Credits response details ...... 4-13 Chargebacks response details ...... 4-13 Direct Debit response details ...... 4-14 Reason codes ...... 4-16 Chargeback reason codes ...... 4-16 Retrieval request reason codes ...... 4-17 Discover chargeback and retrieval request reason codes...... 4-18
A Using the HTTP Post Method
Introduction...... A-1 Direct Debit requests ...... A-1 charge/credit ...... A-1 HTML example – charge ...... A-2 updateShippingInfo ...... A-4 HTML example – updateShippingInfo...... A-4 ddLookupRequest ...... A-6 HTML example – lookupRequest ...... A-6
API Reference Guide for Web Services 1.0 V May 2019
Mandate request ...... A-7 HTML example – mandate request ...... A-8 Change status request ...... A-9 HTML example – change status request ...... A-10 Mandate update request ...... A-10 HTML example – mandate update request...... A-11 Credit card requests...... A-12 Purchase/Authorization/Verification ...... A-12 HTML example – Authorization ...... A-13 Authorization Reversal...... A-15 HTML example – Authorization Reversal ...... A-16 Settlement/Credit ...... A-17 HTML example – Settlement ...... A-17 Stored Data Authorization/Purchase ...... A-18 HTML example – Stored Data Authorization...... A-19 Cancel Settle/Credit/Payment/Independent Credit ...... A-20 HTML example – Cancel ...... A-20 Payment request ...... A-21 HTML example – Payment ...... A-22 Credit card Information Lookup...... A-23 HTML example – Information Lookup...... A-24 Enrollment Lookup...... A-25 HTML example – Enrollment Lookup ...... A-26 Authentication ...... A-27 HTML example – Authentication...... A-28 Information Lookup Service requests ...... A-28 HTML example - ILS ...... A-29 Sample HTTP Post...... A-30 Sample HTTP Post responses ...... A-30
B Response Codes
Overview ...... B-1 Response codes ...... B-1 Action codes ...... B-20 Return codes ...... B-21
C Geographical Codes
Province codes ...... C-1 State codes ...... C-2 Country codes ...... C-3
VI CHAPTER 1
Paysafe Web Services
What are Paysafe Web Services? Web Services are a technology that allows applications to communicate with each other in a platform- and programming language–independent manner. A Web Service is a software interface that describes a col- lection of operations that can be accessed over the network through standardized XML messaging. It uses protocols based on the XML language to describe an operation to execute or data to exchange with another Web Service. Web Services are built on open standards such as SOAP and WSDL. Paysafe Web Services offer the following benefits: • Merchants can integrate easily with the Web Service API, using their favourite platform and language. • Merchants can automate operation and avoid manually keying in information via the Paysafe Web page. • Merchants can operate independently of changes and updates to the Paysafe Web site.
Web Services supported for Direct Debit Paysafe currently supports the following Web Services for Direct Debit: Table 1-1: Direct Debit Operations
Operation Description
Charge Allows you to transfer money from a customer’s bank account to your merchant account. This transaction is completed in real time, though the banking network takes 3–5 days to transfer the funds.
Credit Allows you to transfer money from your merchant account directly to a customer’s bank account. This transaction is completed in real time, though the banking network takes 3–5 days to transfer the funds.
Update Shipping Info Allows you to send shipping information, including a tracking number, once you have shipped goods for which you previously processed a charge transaction.
Information Lookup Allows you to run a report through the API over a date range you specify to return data on Direct Debit charge and credit transactions processed through your merchant account.
Mandate Request Allows you to create a mandate for a customer’s bank account and lodge it at their bank, which per- mits you to transfer money from the customer’s bank account to your merchant account. The bank- ing network typically takes 5 days to process the mandate.
Change Status Allows you to change the status of a charge, credit, or mandate transaction.
Update Mandate Allows you to update the information contained within an existing mandate.
Availability of Direct Debit operation types is allotted on a merchant-by-merchant basis, since not all merchant banks support all operations. If you have any questions, contact your account manager.
API Reference Guide for Web Services 1.0 1-1 Paysafe Web Services May 2019
Web Services supported for credit cards Paysafe currently supports the following Web Services for credit cards: Table 1-2: Credit Card Operations
Operation Description
Authorization Allows you to confirm that a credit card exists and has sufficient funds to cover a Purchase, but without settling the funds to your merchant account.
Purchase Both authorizes and settles a requested amount against a credit card.
Verification Allows you to run an AVS and/or CVD check on a credit card without processing a charge against that card.
Authorization Allows you to reverse all or part of an existing authorization, provided no settlements (either full or par- Reversal tial) have been processed against that authorization. This transaction type does not function with pur- chase transactions, but only with authorizations.
Credit Allows you to issue a credit for an amount that was previously settled.
Settlement Allows you to Settle the amount of an existing Authorization, crediting the authorized amount from the credit card to your merchant account.
Stored Data Allows you to authorize an amount on a customer’s credit card using customer data that is stored in our Authorization database. You provide only a minimum of information, saving you time and effort.
Stored Data Allows you to both authorize and settle an amount on a customer’s credit card using customer data that Purchase is stored in our database. You provide only a minimum of information, saving you time and effort.
Cancel Allows you to cancel a Credit, Settlement, Payment, or Independent Credit transaction. You can cancel one of these transactions as long as it is in a Pending state, which typically is before midnight of the day that it is requested. In some cases, you may find older Credit transactions in a Pending state.
Payment Allows you to credit an amount to a customer’s credit card. The Payment transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way.
Independent Allows you to credit an amount to a customer’s credit card. The Independent Credit transaction is not Credit associated with a previously existing authorization, so the amount of the transaction is not restricted in this way.
Information Allows you to run a report through the API over a date range you specify to return data on credit card Lookup transactions processed through your merchant account.
Enrollment Allows you to determine whether a customer’s credit card is enrolled in the 3D Secure program. Lookup NOTE: This operation is supported only for 3D Secure 1.0.2.
Authentication Allows you to send an Authentication request in order for a cardholder enrolled in 3D Secure to authen- ticate their card with the Card Issuer before you process an Authorization. NOTE: This operation is supported only for 3D Secure 1.0.2.
Availability of credit card operation types is allotted on a merchant-by-merchant basis, since not all merchant banks support all operations. If you have any questions, contact your account manager.
Web Services supported for Information Lookup Service Paysafe currently supports the following Web Service:
1-2 May 2019 System requirements
Table 1-3: Information Lookup Service Operation
Operation Description
Information Lookup Service Allows you to run a report through the API over a date range you specify to return data on Authorizations, Settlements, Credits, and Chargebacks processed through a merchant account.
System requirements The SOAP API has been tested with the following client environments: Table 1-4: Client Environments
SOAP Client Programming Environment Operating Environment
Microsoft .NET 1.1 and 2.0 Microsoft Visual Studio .NET 2003 Microsoft Windows Server 2003 and Windows XP Framework
Apache Axis 1.4 Java (J2SE 1.4.X and higher) Linux and Microsoft Windows XP, Server 2003
Apache Axis 2.0 Java (J2SE 1.4.X and 1.5.X) Linux and Microsoft Windows XP, Server 2003
For more information: • J2SE or J2EE 1.3.1 or newer (1.4.X recommended) Sun Microsystems, Inc. http://java.sun.com/downloads/index.html • Apache Axis 1.4, The Apache Software Foundation http://www.apache.org/dyn/closer.cgi/ws/axis/1_4 • Apache Axis2, 1.2, The Apache Software Foundation http://ws.apache.org/axis2/1_2/contents.html • Microsoft .NET Framework Version 1.1/2.0 Microsoft Corporation http://www.microsoft.com/net
Regardless of which SOAP client you adopt, it must support document-style messaging.
Accessing the Paysafe WSDLs and links
Direct Debit WSDL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1?wsdl Web Service: https://webservices.optimalpayments.com/directdebitWS/DirectDebitService/v1 HTTP Post: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
API Reference Guide for Web Services 1.0 1-3 Paysafe Web Services May 2019
Credit card WSDL: https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1?wsdl Web Service: https://webservices.optimalpayments.com/creditcardWS/CreditCardService/v1 HTTP Post: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
Information Lookup Service WSDL: https://webservices.optimalpayments.com/ilsWS/IlsService/v1?wsdl Web Service: https://webservices.optimalpayments.com/ilsWS/IlsService/v1 HTTP Post: https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1
Testing Paysafe Web Services Once you have configured your Web Services–enabled application, please contact our Technical Support team for instructions on how to test your API calls. • Email [email protected] • Telephone 888-709-8753
Security features For some transactions (e.g., Purchase) Paysafe provides additional features to protect the merchant from fraudulent card usage. • Address verification system (AVS) • Card validation data (CVD) • Negative database • 3D Secure
AVS Paysafe supports address verification checks (AVS) wherever the issuing bank supports this feature. AVS verifies whether the address supplied by the customer using a card matches the billing address associated with that card at the issuing bank. This makes it more difficult to use the card fraudulently, since in order to use a stolen card someone must also know the billing address associated with it. In addition, if goods are to be shipped, the merchant can require that they be shipped to the billing address associated with the card. Within Paysafe, each payment method is configured with the acceptable set of AVS return codes. If the bank returns a code that is not acceptable for the payment method, then the request is rejected with an Authorization Failed error. If you get an Authorization Failed error in response to a transaction request, and
1-4 May 2019 CVD
an Authorization number is returned in the response, then the failure was caused by the AVS check. You can look at the AVS code returned to determine exactly why the AVS check failed. Paysafe returns the fol- lowing codes, in the avsResponse element, to the merchant application in response to a transaction request, with A, N, and E indicating AVS failure: Table 1-5: AVS Codes
Code Letter Explanation
A Address matches, but zip code does not.
B AVS not performed for international transaction. Either the postal code has invalid format or address information not provided.
E AVS not supported for this industry. M For international transaction, address and postal code match.
N No part of the address matches.
Q Unknown response from issuer/banknet switch.
R Retry. System unable to process.
S AVS not supported.
U Address information is unavailable.
W Nine-digit zip code matches, but address does not.
X Exact. Nine-digit zip code and address match.
Y Yes. Five-digit zip code and address match.
Z Five-digit zip code matches, but address does not.
When you registered with Paysafe, your account was set up to automatically apply AVS checks. Paysafe accepts only transactions for which the allowable AVS return codes are returned. AVS has three limitations, which may affect the decisions you make with regard to failed AVS checks: • AVS is not always reliable. Bad results can be returned if someone has moved, for instance, or because some people report five-digit zip codes and some report nine-digit zip codes. • AVS does only limited support internationally. If you decide, therefore, to ship only to addresses that return good AVS results, you may exclude otherwise valid transactions. • AVS is supported by many U.S. issuing banks, but not all. So even if you only serve U.S. customers, you may not always be able to depend on AVS being available.
CVD The CVD value is a 3- or 4-digit number printed on the credit card, but which is not present on the mag- netic strip. Therefore, the value is not printed on receipts or statements, reducing the probability of fraud from imprint information. The CVD feature, intended specifically for transactions where a card is not pres- ent, is a requirement of Paysafe. We support the CVD feature wherever the issuing banks do. When customers enter their card and cardholder information, the CVD value is requested at the same time. One of four indicators flag the status of a CVD request: • Not provided – The customer did not provide the CVD value.
API Reference Guide for Web Services 1.0 1-5 Paysafe Web Services May 2019
• Provided – The customer provided the CVD value. When this indicator is selected, the CVD value is provided. • Illegible – The customer claims the CVD value is illegible. • Not present – The customer claims the CVD value is not on the card.
Negative database Paysafe administers a negative database that provides additional protection against misuse of cards and inappropriate transaction requests. Card numbers and email addresses are entered into the negative data- base for the following reasons: • A chargeback associated with the card number or email address has occurred. • The card number or email address was involved in, or suspected to have been involved in, fraudulent activity. Your account is configured to automatically implement this security feature, and any transaction request that attempts to use either a card number or email address that is in the negative database will not be pro- cessed.
3D Secure Paysafe supports 3D Secure, an online cardholder authentication program designed to make Internet pur- chase transactions safer by authenticating a card holder’s identity at the time of purchase, before the mer- chant submits an authorization request. It is currently supported by several card brands, including Visa (Verified by Visa), MasterCard (SecureCode), and American Express (SafeKey). Authorizations pro- cessed using 3D Secure are guaranteed against most common types of chargeback disputes. Paysafe is compliant to 3DS version 2.1.0. • The Enrollment Lookup and Authentication requests in this API support only 3D Secure version 1.0.2. • The Purchase/Authorization requests will accept authentication fields from 3D Secure version 2. See Building Purchase/Authorization/Verification requests on page 3-4 for details. • In order to use 3D Secure 2 authentication fields you must first integrate with the 3D Secure 2 REST API.
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 Paysafe merchants using our Web Services API to process transaction requests with Paysafe.
Functionality This guide may document some features to which you do not have access. Access to such functionality is allotted on a merchant-by-merchant basis. If you have any questions, contact your account manager.
1-6 May 2019 Symbols
Symbols This user guide uses the following symbols to bring important items to your attention: Table 1-6: 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.
This access icon alerts you about functionality that might be available only for certain merchant configura- tions.
API Reference Guide for Web Services 1.0 1-7 Paysafe Web Services May 2019
1-8 CHAPTER 2
Direct Debit Transactions
Introduction This chapter describes how to process Direct Debit transactions via the Paysafe Web Service. The follow- ing operations are supported: Table 2-1: Supported Operations
Operation Description For Request Type
Charge Allows you to transfer money from a customer’s bank • EFT account to your merchant account. This transaction is • ACH completed in real time, though the banking network • BACS takes 2–5 days to transfer the funds, depending on the bank scheme. • SEPA See Building charge or credit requests on page 2-3. Credit Allows you to transfer money from your merchant • EFT account directly to a customer’s bank account. This • ACH transaction is completed in real time, though the • BACS banking network takes 2–5 days to transfer the funds, depending on the bank scheme. • SEPA
Update Shipping Info Allows you to send shipping information, including a • EFT See Building updateShippingInfo tracking number, once you have shipped goods for • ACH requests on page 2-12. which you previously processed a charge transaction. • SEPA
Information Lookup Allows you to run a report through the API over a • EFT See Building lookup requests on date range you specify to return data on Direct Debit • ACH page 2-16. charge and credit transactions processed through • BACS your merchant account. • SEPA
Mandate Request Allows you to create a mandate for a customer’s bank • BACS See Building BACS mandate account and lodge it at their bank, which permits you • SEPA requests (UK) on page 2-19. to transfer money from the customer’s bank account to your merchant account. The banking network typi- cally takes 5 days to process the mandate.
Change Status Allows you to change the status of a charge, credit, or • EFT See Building change status mandate transaction. • ACH requests on page 2-25. • BACS • SEPA
Update Mandate Allows you to update the information contained • SEPA See Building mandate update within an existing mandate. requests on page 2-28.
Availability of Direct Debit operation types is allotted on a merchant-by-merchant basis, since not all merchant banks support all operations. If you have any questions, contact your account manager.
• The charge and credit operations accept a ddCheckRequestV1 document object. • The updateShippingInfo operation accepts a ddShippingRequestV1 document object. • The lookup operation accepts a ddLookupRequestV1 document object. • The mandate request operation accepts a ddMandateRequest document object.
API Reference Guide for Web Services 1.0 2-1 Direct Debit Transactions May 2019
• The change status operation accepts a ddChangeStatusRequest document object. • The mandate update operation accepts a ddUpdateMandateRequest document object. • All operations return a ddCheckResponseV1 response.
.NET example
To build the .NET example: 1. Create a new project.
2. Add a Web Reference.
2-2 May 2019 Building charge or credit requests
3. Enter the WSDL URL and click the Add Reference button.
The Web client is now built.
4. Build a Direct Debit request and process response. • See Building charge or credit requests on page 2-3 • See Building updateShippingInfo requests on page 2-12 • See Processing the response on page 2-30
Building charge or credit requests Charge and credit requests require the ddCheckRequestV1 document object. This section describes the structure of a ddCheckRequestV1 and how to construct one. See Table 2-2: ddCheckRequestV1 Elements on page 2-6 for details on elements required.
charge example – C# The following is a charge example in C#.
API Reference Guide for Web Services 1.0 2-3 Direct Debit Transactions May 2019
To make this a credit request, modify the value “charge” – in the line “DDCheckResponseV1 ddTxnRe- sponse = ddService.charge(ddCheckRequest)” below – to “credit”.
// Prepare the call to the Direct Debit Web Service DDCheckRequestV1 ddCheckRequest = new DDCheckRequestV1(); ddCheckRequest.amount = "10.00"; MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ddCheckRequest.merchantAccount = merchantAccount; CheckV1 check = new CheckV1(); check.routingNum = "123456789"; check.accountNum = "987654321"; check.accountType = BankAccountTypeV1.PC; check.bankName = "Chase"; check.checkNum = 12; check.payee = "ACME Inc."; ddCheckRequest.check = check; BillingDetailsV1 billingDetails = new BillingDetailsV1(); billingDetails.firstName = "Jane"; billingDetails.lastName = "Jones"; billingDetails.street = "123 Main Street"; billingDetails.city = "LA"; billingDetails.country = CountryV1.US; billingDetails.zip = "90210"; billingDetails.phone = "555-555-5555"; billingDetails.checkPayMethod = CheckPayMethodV1.WEB; ddCheckRequest.billingDetails = billingDetails; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest);
// Print out the result String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); }
2-4 May 2019 ddCheckRequestV1 schema
ddCheckRequestV1 schema A ddCheckRequestV1 document object has the following structure:
API Reference Guide for Web Services 1.0 2-5 Direct Debit Transactions May 2019
ddCheckRequestV1 elements
This request is used for Direct Debit transactions for a variety of schemes. Please see Table 2-3: Addi- tional Direct Debit Element Requirements on page 2-11 for variations on certain required elements.
The ddCheckRequestV1 document object may contain the following elements: Table 2-2: ddCheckRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Conditional String This is the unique ID number associated Max = 40 with the original request. The value is cre- ated by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
amount Yes String This is the amount of the transaction request. Max = NOTE: This field requires a leading non- 9999999.99 zero digit and two digits after the decimal place. An exception is made in cases where a leading zero is by itself (e.g., 0.99).
check accountType Optional Enumeration This is the type of checking account used for the transaction. Possible values are: • PC (Personal Checking) • PS (Personal Savings) • PL (Personal Loan) • BC (Business Checking) • BS (Business Savings) • BL (Business Loan) NOTE: If this element is not specified, the value defaults to PC.
bankName Optional String This is the name of the customer’s bank, to Max = 40 which this transaction is posted.
checkNum Yes Long This is the check serial number, provided at Max = 8 the time of the transaction request.
accountNum Yes String This is the customer’s bank account number. Max = 17 For SEPA transactions, this is IBAN (Inter- If IBAN, national Bank Account Number) of the cus- Max = 32 tomer’s bank account. NOTE: This cannot be zero (0) and can con- tain alphanumeric characters only.
2-6 May 2019 ddCheckRequestV1 elements
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
routingNum Yes String For USD accounts, this is the 9-digit routing Min = 6 number of the customer’s bank. Max = 9 For British pound accounts, this is the 6- If BIC, digit sort code of the customer’s bank. Min = 8 For Canadian dollar accounts, this is a com- bination of the 3-digit institution ID Max = 11 followed by the 5-digit transit number of the customer’s bank branch. They must be entered in this order. Do not include spaces or dashes. For SEPA transactions, this is the BIC (Bank Identifier Code) of the customer’s bank account. If you do not have the BIC, you can submit the following case-sensitive value: EMPTYBIC NOTE: This cannot be zero (0) and can con- tain alphanumeric characters only.
payee Conditional String This is the descriptor that will appear on the Max = 81 customer’s bank account. It is required only for credit transactions. If you provide a value for this field, this value will be used as the statement descrip- tor. If you do not provide a value for this field, a default value configured for the mer- chant account will be used.
bankCountry Conditional Enumeration This is the country in which the bank is located. See Country codes on page C-3 for correct codes to use. This is a required ele- ment only for certain countries.
bankCity Conditional String This is the city in which the bank is located. Max = 40 This is a required element only for certain countries.
mandateReference Conditional String This is the mandate reference that allows the Max = 10 account to be charged. This is the value For SEPA, returned for the mandateReference parameter in the response to a Max = 35 ddMandateRequestV1. For BACS, NOTE: This element is mandatory for Max = 10 BACS and SEPA debits only.
billingDetails checkPayMethod Optional Enumeration This is the payment type. Possible values are: • WEB (Personal Check Only) • TEL (Personal Check Only) • PPD (Personal Check Only) • CCD (Business Check Only) NOTE: If this element is not specified, the value defaults to WEB. It cannot be set to WEB or TEL for credit requests.
firstName Conditional String This is the customer’s first name. Max = 40 Required if checkPayMethod is set to WEB or TEL.
lastName Conditional String This is the customer’s last name. Max = 40 Required if accountType is set to PC, PS, or PL.
API Reference Guide for Web Services 1.0 2-7 Direct Debit Transactions May 2019
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
companyName Conditional String This is the company’s name. Max = 50 Required if accountType is set to BC, BS, or BL.
street Yes String This is the first line of the customer’s street Max = 50 address.
street2 Optional String This is the second line of the customer’s Max = 50 street address.
city Yes String This is the city in which the customer Max = 40 resides.
state/region Conditional If state, then This is the state/province/region in which Enumeration the customer resides. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for correct codes to use.
country Yes Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.
zip Optional String This is the customer’s ZIP code if in the Max = 10 U.S.; otherwise, this is the customer’s postal code.
phone Optional String This is the customer’s telephone number. Max = 40
email Optional String This is the customer’s email address. Max = 100
personalID idNumber Optional String This is the number of the ID provided for the Max = 20 idType element.
idType Optional Enumeration This is the type of ID used to identify the owner of the bank account. Possible values are: • DL (Driver’s License) • SS (Government ID) • MI (Military ID) • GN (Generic ID)
state/region Optional If state, then This is the state/province/region in which Enumeration the ID was issued. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for correct codes to use.
country Optional String This is the country in which the ID was Length = 2 issued. Possible values are: • CA (Canada) • US (United States)
expiry Optional The expiry child element has three further child elements.
Child Element of expiry
2-8 May 2019 ddCheckRequestV1 elements
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
day Optional Int This is the day the ID expires. Length = 2
month Optional Int This is the month the ID expires. Length = 2
year Conditional Int This is the year the ID expires. Length = 4 This element is required if the expiry ele- ment is included.
socialSecurityNumber Optional String This is the customer’s Social Security Max = 12 Number.
dateOfBirth Optional This is the customer’s date of birth.
year Conditional String This is the customer’s year of birth. Max = 4 1900–9999
month Conditional String This is the customer’s month of birth. Max = 12
day Conditional String This is the customer’s day of birth. Max = 31
shippingDetails carrier Optional Enumeration 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
trackingNumber Optional String This is the shipping tracking number pro- Max = 50 vided by the carrier.
shipMethod Optional Enumeration This is the method of shipment. Possible values are: • N = Next Day/Overnight • T = Two-Day Service • C = Lowest Cost • O = Other
firstName Optional String This is the recipients’s first name. Max = 40
lastName Optional String This is the recipient’s last name. Max = 40
street Optional String This is the first line of the recipient’s street Max = 50 address.
street2 Optional String This is the second line of the recipient’s Max = 50 street address.
API Reference Guide for Web Services 1.0 2-9 Direct Debit Transactions May 2019
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
city Optional String This is the city in which the recipient Max = 40 resides.
state/region Optional If state, This is the state/province/region in which Enumeration the recipient resides. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for correct codes to use.
country Optional Enumeration This is the country in which the recipient resides. See Country codes on page C-3 for correct codes to use.
zip Optional String This is the recipient’s ZIP code if in the U.S.; Max = 10 otherwise, this is the recipient’s postal code.
phone Optional String This is the recipient’s phone number. Max = 40
email Optional String This is the recipient’s email address. Max = 100
customerIP Optional String This is the customer’s IP address. Max = 50
productType Optional Enumeration This is the type of product sold. Possible values are: • P (Physical Goods) • D (Digital Goods) • C (Digital Content) • G (Gift Certificate/Digital Cash) • S (Shareware) • M (Both Digital and Physical) • R (Account Replenish)
txnAppliedTo No This element is not applicable for Direct Debit transactions.
confirmationNumber Conditional String This is the confirmation number returned by Max = 15 Paysafe in response to the original request. Include this element only if you are using the ddCheckRequestV1 to process a credit request.
targetVirtualAccount No This element is not applicable for Direct Debit transactions.
checkRiskService No This element is not applicable for Direct Debit transactions.
2-10 May 2019 ddCheckRequestV1 elements
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
txnDate Optional dateTime This is the date and time that the transaction took place. For a charge or credit, or for a ddMandateRequestV1, this can be the future date and time when the transaction will take place. For SEPA, this specifies the future collection date. It must be a minimum of 2 business days in the future for all SEPA transaction requests. NOTE: The resulting collection date will be returned in the tag/value pair for the detail element in the response (see Table 2-10: ddCheckResponseV1 Elements on page 2-31).
sdk version Conditional String This is the version of the SDK used, if any. Max = 20 Required if sdk element is provided.
platform Conditional String This is the integration language of the SDK Max = 10 used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional String This is the author of the SDK used. Set to Max = 20 value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
origin Optional Enumeration The is the origin of the request. Possible values are: • Wireless • Wireline
addendumData tag Optional String This is additional data that the merchant can Max = 30 include with the transaction request.
value Optional String This is additional data that the merchant can Max = 1024 include with the transaction request.
Special considerations for Direct Debit elements Some merchants are integrated with downstream processors that have different requirements for manda- tory Direct Debit elements. In such cases, the following holds. Table 2-3: Additional Direct Debit Element Requirements
Element Regular Guaranteed SEPA Transactions Transactions Transactions
check.accountType Optional Required Optional
check.bankName Optional Required Optional
check.checkNum Required Required Optional
check.payee Optional Optional Required
check.bankCountry Conditional Conditional Optional
check.bankCity Conditional Conditional Optional
API Reference Guide for Web Services 1.0 2-11 Direct Debit Transactions May 2019
Table 2-3: Additional Direct Debit Element Requirements (Continued)
Element Regular Guaranteed SEPA Transactions Transactions Transactions
check.mandateReference Conditional Conditional Required for Debits only.
billingDetails.firstName Conditional Required Required
billingDetails.lastName Conditional Required Required
billingDetails.companyName Conditional Conditional Optional
billingDetails.state Conditional Required Optional
billingDetails.zip Optional Required Required
billingDetails.phone Optional Required Optional
billingDetails.email Optional Required Required
customerIP Optional Required Optional
dateOfBirth.year Optional Required Optional
dateOfBirth.month Optional Required Optional
dateOfBirth.day Optional Required Optional
personalID.idNumber Optional Required Optional
personalID.state Optional Required Optional
socialSecurityNumber Optional Required Optional
Your account manager will inform you 1) if you are integrated with this type of downstream processor and 2) if you are eligible for guaranteed Direct Debit processing.
Building updateShippingInfo requests
All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the shipMethod element in the example below.
The updateShippingInfo request requires the ddShippingRequestV1 document object. This section describes the structure of a ddShippingRequestV1 and how to construct one. See Table 2-4: ddShippingRe- questV1 Elements on page 2-14 for details on elements required.
updateShippingInfo example – C# The following is an updateShippingInfo example in C#.
// Prepare the call to the Direct Debit Web Service DDShippingRequestV1 ddShippingRequest = new DDShippingRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePwd";
2-12 May 2019 updateShippingInfo example – C#
ddShippingRequest.merchantAccount = merchantAccount; ddShippingRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous settle auth or purchase ddShippingRequest.carrier = CarrierV1.FEX; // Fedex ddShippingRequest.shipMethod = ShipMethodV1.T; ddShippingRequest.shipMethodSpecified = true; ddShippingRequest.trackingNumber = "555666888999"; ddShippingRequest.firstName = "Jane"; ddShippingRequest.lastName = "Jones"; ddShippingRequest.street = "123 Main Street"; ddShippingRequest.city = "LA"; ddShippingRequest.country = CountryV1.US; ddShippingRequest.countrySpecified = true; ddShippingRequest.zip = "90210"; ddShippingRequest.email = "[email protected]"; // optional email address
//Perform the Web Services call to update the shipping info DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse = ddService.updateShippingInfo(ddShippingRequest); // Print out the result String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); }
API Reference Guide for Web Services 1.0 2-13 Direct Debit Transactions May 2019
ddShippingRequestV1 schema A ddShippingRequestV1 document object has the following structure:
ddShippingRequestV1 elements The ddShippingRequestV1 document object may contain the following elements: Table 2-4: ddShippingRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
2-14 May 2019 ddShippingRequestV1 elements
Table 2-4: ddShippingRequestV1 Elements (Continued)
Element Child Element Required Type Description
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
carrier Yes Enumeration 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
trackingNumber Yes String This is the shipping tracking number provided Max = 50 by the carrier.
confirmationNumber Yes String This is the confirmation number returned by Max = 15 Paysafe.
shipMethod Optional Enumeration This is the method of shipment. Possible values are: • N = Next Day/Overnight • T = Two-Day Service • C = Lowest Cost • O = Other
firstName Optional String This is the customer’s first name. Max = 40
lastName Optional String This is the customer’s last name. Max = 40
street Optional String This is the first line of the customer’s street Max = 50 address.
street2 Optional String This is the second line of the customer’s street Max = 50 address.
city Optional String This is the city in which the customer resides. Max = 40
state/region Optional If state, then This is the state/province/region in which the Enumeration customer resides. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for cor- rect codes to use.
country Optional Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.
API Reference Guide for Web Services 1.0 2-15 Direct Debit Transactions May 2019
Table 2-4: ddShippingRequestV1 Elements (Continued)
Element Child Element Required Type Description
zip Optional String This is the customer’s ZIP code if in the U.S.; Max = 10 otherwise, this is the customer’s postal code.
phone Optional String This is the customer’s telephone number. Max = 40
email Optional String This is the customer’s email address. Max = 100
Building lookup requests The Direct Debit lookup request allows you to run a report, over a date range you specify, to return data on Direct Debit charge and credit transactions processed through your merchant account.
Lookup example – C# The following is a ddLookupRequest example in C#.
// Prepare the call to the Direct Debit Web Service DDLookupRequestV1 ddLookupRequest = new DDLookupRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ddLookupRequest.merchantAccount = merchantAccount; ddLookupRequest.confirmationNumber = "123456789"; DateV1 startDate = new DateV1(); startDate.year = "2012"; startDate.month = "08"; startDate.day = "15"; startDate.hour = "11"; startDate.minute = "00"; startDate.second = "00"; ddLookupRequest.startDate = startDate; ddLookupRequest.startDateSpecified = true; DateV1 endDate = new DateV1(); endDate.year = "2012"; endDate.month = "08"; endDate.day = "15"; endDate.hour = "14"; endDate.minute = "00"; endDate.second = "00"; ddLookupRequest.endDate = endDate; ddLookupRequest.endDateSpecified = true;
//Perform the Web Services call to process the charge DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddCheckResponse = ddService.lookup(ddLookupRequest); // Print out the result String responseTxt = ddCheckResponse.code + " - " + ddCheckResponse.decision; responseTxt += "Transactions:" + Environment.NewLine; if (ddCheckResponse.transaction != null) { for (int i = 0; i < ddCheckResponse.transaction.Length; i++)
2-16 May 2019 Lookup example – C#
{ responseTxt += " - confirmationNumber: " + ddCheckResponse.transaction[i].confirmationNumber + Environment.NewLine; responseTxt += " - merchantRefNum: " + ddCheckResponse.transaction[i].merchantRefNum + Environment.NewLine; responseTxt += " - txnTime: " + ddCheckResponse.transaction[i].txnTime + Environment.NewLine; responseTxt += " - amount: " + ddCheckResponse.transaction[i].amount + Environment.NewLine; StatusV1 status = ddCheckResponse.transaction[i].status; if (status != null){ responseTxt += " - status: " + status.code + Environment.NewLine; responseTxt += " - status effective date:" + status.effectiveDate + Environment.NewLine; } responseTxt += Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddCheckResponse.decision)) { System.Console.WriteLine("Transaction Found."); } else { System.Console.WriteLine("Transaction Failed or Not Found with decision: " + ddCheckResponse.decision); }
API Reference Guide for Web Services 1.0 2-17 Direct Debit Transactions May 2019
ddLookupRequestV1 schema A ddLookupRequestV1 document object has the following structure:
ddLookupRequestV1 elements The ddLookupRequestV1 document object may contain the following elements: Table 2-5: ddLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
confirmationNumber Optional String This is the confirmation number returned by Max = 15 Paysafe in response to the original request. Include this element only if you want to search using this field. This field takes precedence over the merchantRefNum field.
merchantRefNum Conditional String This is a unique ID number associated with the Max = 40 original request. The value is created by the merchant and submitted as part of the request.
2-18 May 2019 Building BACS mandate requests (UK)
Table 2-5: ddLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
startDate year Required Int This is the year set for the search start. Max = 9999
month Required Int This is the month set for the search start. Min = 1 Max = 12
day Required Int This is the day set for the search start. Min = 1 Max = 31
hour Required Int This is the hour set for the search start. Min = 0 Max = 23
minute Required Int This is the minute set for the search start. Min = 0 Max = 59
second Required Int This is the second set for the search start. Min = 0 Max = 59
endDate year Required Int This is the year set for the search end. Max = 9999
month Required Int This is the month set for the search end. Min = 1 Max = 12
day Required Int This is the day set for the search end. Min = 1 Max = 31
hour Required Int This is the hour set for the search end. Min = 0 Max = 23
minute Required Int This is the minute set for the search end. Min = 0 Max = 59
second Required Int This is the second set for the search end. Min = 0 Max = 59
Building BACS mandate requests (UK) The Direct Debit mandate allows you to create a mandate for a customer’s bank account and lodge it at their bank, which is required before you can perform a charge operation to transfer money from that cus- tomer’s bank account to your merchant account. When you submit a ddMandateRequestV1, Paysafe will return a value for the mandateReference element in the response. This value is either based on the value you send in the request, or it is automatically gen- erated by the Paysafe system. You will use this value in the mandateReference element (which is a child
API Reference Guide for Web Services 1.0 2-19 Direct Debit Transactions May 2019
element of the check element) when you process future charge requests against the customer’s bank account using the ddCheckRequestV1. The mandateReference is 10 characters in length. If you send a request with a value of fewer than 10 char- acters, Paysafe will pre-fill the reference with 0’s to make up 10 characters. For example, a requested value of “ABCDEFG” will return a value of “000ABCDEFG”. If no value is passed, Paysafe will create the value for you and return it within the response. Initially, the status of the mandate is set to W (Pending), followed by C (Completed) when it has been batched – at this point the mandate cannot yet be used for Direct Debit transactions. The banking network typically takes 5 days to process the mandate, so 5 days after the mandate has been batched, Paysafe changes the status of the mandate to AP (Active). At that point it can be used to authorize Direct Debit transactions on the bank account for which it was set up. Note that if the charge is postdated by setting the txnDate in the ddCheckRequestV1 request, then the mandate may be used while it is not yet active, pro- vided the txnDate is set to a minimum of 5 working days in the future to allow the mandate time to become active. To assist this process, the date a mandate will become active is returned in the effectiveDate element of the response to the ddMandateRequestV1. Mandates are automatically batched the next working day unless the autoSend value is not set to Y, in which case the mandate will remain in a PCA (Pending Customer Approval) state. This optional interme- diate state before W allows you to perform extra checks on the customer, or for the customer to review the information having received the mandateReference, before proceeding. The mandate may then be turned from a PCA to W state by using either the changeStatus request or the Paysafe merchant back office.
Building SEPA mandate requests In order to process a SEPA Direct Debit transaction, you will need to pre-establish a mandate agreement with your customer and send your mandate reference ID in the mandateReference element. Please note that your mandate reference ID can have up to 35 characters.
Mandates are not required for SEPA credits.
SEPA Direct Debit mandates are active as soon they are created by the merchant, so you can immediately follow up the ddMandateRequest request with a ddCheckRequest. The SEPA Direct Debit Merchant Implementation Guide contains more information about the business logic and processes surrounding the SEPA Direct Debit transaction.
mandate example – C# The following is a ddMandateRequest example in C#.
// Prepare the call to the Direct Debit Web Service DDMandateRequestV1 ddMandateRequest = new DDMandateRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ddCheckRequest.merchantAccount = merchantAccount; CheckV1 check = new CheckV1(); check.routingNum = "123456789"; check.accountNum = "987654321"; check.bankName = "Chase"; check.payee = "ACME Inc."; ddMandateRequest.check = check; BillingDetailsV1 billingDetails = new BillingDetailsV1();
2-20 May 2019 mandate example – C#
billingDetails.firstName = "Jane"; billingDetails.lastName = "Jones"; billingDetails.street = "123 Main Street"; billingDetails.city = "Cambridge"; billingDetails.country = CountryV1.UK; billingDetails.zip = "CB12345"; billingDetails.phone = "1222 444000"; billingDetails.checkPayMethod = CheckPayMethodV1.WEB; ddMandateRequest.billingDetails = billingDetails; ddMandateRequest.autoSend = "Y"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse = ddService.mandate(ddCheckRequest);
// Print out the result String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); }
API Reference Guide for Web Services 1.0 2-21 Direct Debit Transactions May 2019
ddMandateRequestV1 schema A ddMandateRequestV1 document object has the following structure:
2-22 May 2019 ddMandateRequestV1 elements
ddMandateRequestV1 elements The ddMandateRequestV1 document object may contain the following elements: Table 2-6: ddMandateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
merchantRefNum Conditional String This is the unique ID number associated with Max = 40 the original request. The value is created by the merchant and submitted as part of the orig- inal request.
check accountType Optional Enumeration This is the type of checking account used for the transaction. Possible values are: • PC (Personal Checking) • PS (Personal Savings) • PL (Personal Loan) • BC (Business Checking) • BS (Business Savings) • BL (Business Loan) NOTE: If this element is not specified, the value defaults to PC.
bankName Optional String This is the name of the customer’s bank, to Max = 40 which this transaction is posted.
checkNum Optional Long This is the check serial number, provided at Max = 8 the time of the transaction request.
accountNum Yes String This is the customer’s bank account number. Max = 17 For SEPA transactions, this is IBAN (Interna- tional Bank Account Number) of the cus- tomer’s bank account.
routingNum Yes String For British pound accounts, this is the 6-digit Min = 6 sort code of the customer’s bank. Max = 9 For SEPA transactions, this is the BIC (Bank If BIC, Identifier Code) of the customer’s bank account. If you do not have the BIC, you can Min = 8 submit the following case-sensitive value: Max = 11 EMPTYBIC
payee Optional String This is the descriptor that will appear on the Max = 81 customer’s bank account. It is required only for credit transactions. If you provide a value for this field, this value will be used as the statement descriptor. If you do not provide a value for this field, a default value configured for the merchant account will be used.
API Reference Guide for Web Services 1.0 2-23 Direct Debit Transactions May 2019
Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description
bankCountry Conditional Enumeration This is the country in which the bank is located. See Country codes on page C-3 for correct codes to use. This is a required element only for certain countries.
bankCity Conditional String This is the city in which the bank is located. Max = 40 This is a required element only for certain countries.
mandateReference Conditional String This is the mandate reference that allows the Max = 10 account to be charged. You may optionally set For SEPA, the value of the mandateReference yourself when making the request. If you do not supply Max = 35 a value here then it will be set by Paysafe and returned in the response. For SEPA, this element is mandatory, and the merchant creates their own mandateReference.
billingDetails checkPayMethod Optional Enumeration This is the payment type. Possible values are: • WEB (Personal Check Only) • TEL (Personal Check Only) • PPD (Personal Check Only) • CCD (Business Check Only) NOTE: If this element is not specified, the value defaults to WEB.
firstName Conditional String This is the customer’s first name. Max = 40 Required if checkPayMethod is set to WEB or TEL.
lastName Conditional String This is the customer’s last name. Max = 40 Required if accountType is set to PC, PS, or PL.
companyName Conditional String This is the company’s name. Max = 50 Required if accountType is set to BC, BS, or BL.
street Optional String This is the first line of the customer’s street Max = 50 address.
street2 Optional String This is the second line of the customer’s street Max = 50 address.
city Optional String This is the city in which the customer resides. Max = 40
state/region Conditional If state, then This is the state/province/region in which the Enumeration customer resides. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for cor- rect codes to use.
country Optional Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.
zip Optional String This is the customer’s ZIP code if in the U.S.; Max = 10 otherwise, this is the customer’s postal code.
2-24 May 2019 Building change status requests
Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description
phone Optional String This is the customer’s telephone number. Max = 40
email Optional String This is the customer’s email address. Max = 100
customerIP Optional String This is the customer’s IP address. Max = 50
txnDate Optional dateTime This is the date and time that the transaction took place. For a charge or credit, or for a ddMandateRe- questV1, this can be the future date and time when the transaction will take place.
autoSend Optional Boolean This controls when the mandate is sent to the bank. Possible values are: • Y = The mandate will be set to W (Pending) status, ready to be batched and then sent to the bank • N = The mandate will remain with the status of PCA (Pending Customer Approval), and will not be sent to the bank. If the autoSend status is set to N, the mandate can later be changed to a status of W by using the changeStatus request, at which point the mandate will then be sent to the bank at the next batching time (see Building change status requests on page 2-25). NOTE: For SEPA, this must be set to Y, and the mandate will be set to AP (Active).
addendumData tag Optional String This is additional data that the merchant can Max = 30 include with the transaction request.
value Optional String This is additional data that the merchant can Max = 1024 include with the transaction request.
Building change status requests A change status request allows you to change the status of some Direct Debit transactions. You can make the following status changes: Table 2-7: Status Changes
Solution Request Type Initial Status Resulting Status
UK Direct Debit (BACS) • Mandate • PCA – Pending Customer Approval • W – Pending • X – Cancelled
UK Direct Debit (BACS) • Charge • W – Pending • X – Cancelled • Credit • Mandate
API Reference Guide for Web Services 1.0 2-25 Direct Debit Transactions May 2019
Table 2-7: Status Changes (Continued)
Solution Request Type Initial Status Resulting Status
UK Direct Debit • Charge • C – Completed • RE – Returned (gateway merchants) • Credit • CL – Cleared NOTE: Use only when your • Mandate sponsoring bank has rejected the transaction and no BACS report has been produced. Allow 5 working days from the completed date and then contact Technical Support before making this change request.
EFT/ACH • Charge • C – Completed • X – Cancelled • Credit NOTE: Only possible where the request has not yet been sent to the bank.
SEPA Direct Debit • Mandate • AP – Active • X – Cancelled
SEPA Direct Debit • Charge • W – Pending • X – Cancelled • C – Completed NOTE: SEPA Direct Debit transactions can be cancelled only before their execution date.
Paysafe responds to your change status request with the ddCheckResponseV1. In this response, the confir- mationNumber identifies the request that was updated (charge, credit, or mandateRequest), and you can confirm the new status of the transaction you updated. See Processing the response on page 2-30 for details.
Change status example – C# The following is a ddChangeStatusRequest example in C#.
// Prepare the call to the Direct Debit Web Service DDChangeStatusRequestV1 ddChangeStatusRequest = new DDChangeStatusRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ddChangeStatusRequest.merchantAccount = merchantAccount; ddChangeStatusRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous mandate or echeck; ddChangeStatusRequest.status = "C"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse = ddService.changeStatus(ddCheckRequest);
// Print out the result String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine;
2-26 May 2019 ddChangeStatusRequest schema
} } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); }
ddChangeStatusRequest schema A ddChangeStatusRequestV1 document object has the following structure:
ddChangeStatusRequestV1 elements The ddChangeStatusRequestV1 document object may contain the following elements: Table 2-8: ddChangeStatusRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
API Reference Guide for Web Services 1.0 2-27 Direct Debit Transactions May 2019
Table 2-8: ddChangeStatusRequestV1 Elements (Continued)
Element Child Element Required Type Description
confirmationNumber Optional String This value identifies the transaction whose status Max = 15 you want to change. This is the confirmationNumber returned by Pay- safe in response to the original transaction request.
status Required Enumeration This is the new status code for the transaction. Possible values are: • C – Completed • RE – Returned • W – Pending • X – Cancelled
addendumData tag Optional String This is additional data that the merchant can Max = 30 include with the transaction request.
value Optional String This is additional data that the merchant can Max = 1024 include with the transaction request.
Building mandate update requests
Only merchants processing SEPA Direct Debits can use this request type.
A mandate update request allows you to update an existing mandate. Effectively, you are creating a new mandate based on the information contained in the existing mandate, but with some updated information (e.g., a customer’s bank account number might change). When you submit a ddUpdateMandateRequestV1, Paysafe sets the status of the mandate to T (Trans- ferred). A new mandate is created, copying the data from the existing mandate, except for any of the fol- lowing three values that may have been specified in the mandate update request: • mandateReference • accountNum • routingNum Any new values that were specified in the request for these elements will be used in the new mandate. The new mandate will have a status of either PCA (Pending Customer Approval) or AP (Active) as per the existing mandate. The new mandate will be linked to the existing mandate, so the system knows that the existing mandate was transferred to the new mandate. Paysafe responds to your update mandate request with the ddCheckResponseV1. In this response, the con- firmationNumber identifies the new mandate that has been created.
Mandate update example – C# The following is a ddUpdateMandateRequest example in C#.
// Prepare the call to the Direct Debit Web Service DDUpdateMandateRequestV1 ddUpdateMandateRequest = new DDUpdateMandateRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID";
2-28 May 2019 ddUpdateMandateRequestV1 schema
merchantAccount.storePwd = "myStorePWD"; ddUpdateMandateRequest.merchantAccount = merchantAccount; ddUpdateMandateRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous mandate or echeck; ddUpdateMandateRequest.mandateReference = "NL95ZZZ999999991458_TEST7A"; //Perform the Web Services call to process the charge DirectDebitServiceV1 ddService = new DirectDebitServiceV1(); DDCheckResponseV1 ddTxnResponse = ddService.updateMandate(ddCheckRequest);
// Print out the result String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); }
ddUpdateMandateRequestV1 schema A ddUpdateMandateRequestV1 document object has the following structure:
ddUpdateMandateRequestV1 elements The ddUpdateMandateRequestV1 document object may contain the following elements:
API Reference Guide for Web Services 1.0 2-29 Direct Debit Transactions May 2019
Table 2-9: ddUpdateMandateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
confirmationNumber Optional String This value identifies the mandate that you want Max = 15 to update. This is the confirmationNumber returned by Pay- safe in response to the original transaction request.
mandateReference Conditional String This is the mandate reference that allows the Max = 10 account to be charged. This is the value returned For SEPA, for the mandateReference parameter in the response to a ddMandateRequestV1. Max = 35 You might need to update the mandateReference, e.g., if the billing terms have changed but all other mandate information remains the same.
accountNum Conditional String For SEPA transactions, this is the IBAN Max = 17 (International Bank Account Number) of the cus- If IBAN, tomer’s bank account. Max = 32 You might need to update the accountNum, e.g., if the customer is now going to be billed out of a different account but from the same bank (i.e., where there is no need to change the BIC).
routingNum Conditional String For SEPA transactions, this is the BIC (Bank Min = 6 Identifier Code) of the customer’s bank account. Max = 9 If you do not have the BIC, you can submit the following case-sensitive value: EMPTYBIC If BIC, You would need to update the routingNum, e.g., Min = 8 if the customer has changed banks, in which case Max = 11 the accountNum would also have to be updated.
* At least one of these three elements must be included in the request: mandateReference, accountNum, and routingNum.
Processing the response A ddCheckResponseV1 has the following structure:
2-30 May 2019 Processing the response
The following elements are relevant for a ddCheckResponseV1: Table 2-10: ddCheckResponseV1 Elements
Element Child Element Required Type Description
requestId Optional This is the unique ID number returned by Paysafe for a record if it was processed in a batch file.
confirmationNumber Yes String This is the confirmation number returned Max = 15 by Paysafe. If this is returned in response to a ddUpdateMandateRequestV1, this identi- fies the new mandate that has been cre- ated.
merchantRefNum Optional String This is the unique ID number associated Max = 40 with the original request. The value is created by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
API Reference Guide for Web Services 1.0 2-31 Direct Debit Transactions May 2019
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
mandateReference Yes String This is the mandate reference returned by Max = 20 Paysafe. It is either the value echoed back from the request, or if it was not specified correctly in the request, then it is gener- ated by Paysafe. For SEPA, this is the mandate reference created by the merchant in the request.
decision Yes Enumeration This is the status of the transaction. One of the following is returned: • Accepted – the transaction was pro- cessed. • Error – the transaction was attempted, but failed for some reason. • Declined – the transaction was declined before it was sent for process- ing. • Not Found – the transaction lookup did not find any matches.
code Yes Int This is a numeric code that categorizes the response. See Response codes on page B-1.
actionCode Optional Enumeration This indicates what action to take. The following values are possible: • C = Consumer Parameter Error. The consumer has provided incorrect infor- mation. Ask the customer to correct the information. • D = Do Not Retry. Further attempts will fail. • M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R = Retry. The problem is temporary. Retrying the request will likely suc- ceed.
description Optional String This is a human readable description of Max = 100 the code element.
detail tag Optional String This is the classification of the detail ele- Max = 1024 ment.
value Optional String This is the description of the detail. Max = 30
txnTime Yes dateTime This is the date and time the transaction was processed by Paysafe.
2-32 May 2019 Processing the response
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
status Optional
code Conditional Enumeration This is the status of the first transaction that matches a lookup request. Possible values are: • AP – Active • C – Complete batch • CB – Clawed back • CL – Cleared transaction • DE – Declined • DI – Disputed • E – Error batch • EX – Expired • F – Failed • GR – Good for reversal • MI – Manual intervention required • PCA – Pending customer approval • PR1 – Re-Presented 1 • PR2 – Re-Presented 2 • PX – Pending cancel • RE – Returned • REF – Rejected final • RV – Reversed • T – Transferred • UM – Unauthorized mandate • W – Pending • X – Cancelled
effectiveDate Conditional dateTime • This is the date and time at which the status of the lookup request is in effect. • When included in the tag/value pair for the detail element for a response to a mandate request, this is the date the mandate will become active with the bank (counting 5 working days from batching time). You may submit a charge request from midnight on this date, or postdate your charge with a txnTime that has a value of this date or later. If you submit a charge with a date before the mandate effectiveDate, you will receive an error.
currency Optional String The value will be one of the currency codes in Table 3-15: Currency Codes on page 3-51. This value is returned only in response to lookup requests.
amount Optional String This is the amount of the first transaction Max = that matches a lookup request. 9999999.99
transaction Optional This is returned only in response to a lookup request. All transactions that match the lookup request are returned here.
API Reference Guide for Web Services 1.0 2-33 Direct Debit Transactions May 2019
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
confirmationNumber Conditional String This is the confirmation number returned Max = 15 by Paysafe for a previous transaction.
merchantRefNum Optional String This is the unique ID number associated Max = 255 with the original request. The value is created by the merchant and submitted as part of the original request. This is returned only in response to a lookup request.
txnTime Conditional dateTime This is the date and time the transaction was processed by Paysafe.
status Conditional This contains code and effectiveDate ele- ments for the transaction. See the status element above in this table for details.
amount Conditional String This is the amount of the transaction. Max = 9999999.99
To process the response: 1. Get the response details, which are available via get() methods of the response.
String responseTxt = ddTxnResponse.code + " - " + ddTxnResponse.decision + " - " + ddTxnResponse.description; responseTxt += "Details:" + Environment.NewLine; if (ddTxnResponse.detail != null) { for (int i = 0; i < ddTxnResponse.detail.Length; i++) { responseTxt += " - " + ddTxnResponse.detail[i].tag + " - " + ddTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ddTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ddTxnResponse.decision); } 2. Process based on the decision element. You would insert handling code appropriate to your applica- tion. You can also look at the code element to provide more fine-grained control for your application. See Response codes on page B-1 for more details.
2-34 CHAPTER 3
Credit/Debit Card Transactions
Introduction This chapter describes how to process credit and debit card transactions via the Paysafe Web Service. The following operations are supported: Table 3-1: Supported Operations
Operation Description Request Type
Authorization Allows you to authorize an amount on a customer’s credit/ debit card. The authorized amount must be settled in a subsequent set- tlement transaction.
Purchase Allows you to both authorize and settle an amount on a cus- See Building Purchase/Authorization/Ver- tomer’s credit/debit card in a single transaction. ification requests on page 3-4.
Verification Allows you to run an AVS and/or CVD check on a customer’s credit card without processing a charge against that card.
Authorization Allows you to reverse all or part of an existing authorization, See Building Authorization Reversal Reversal provided no settlements (either full or partial) have been pro- requests on page 3-17. cessed against that authorization. This transaction type does not function with purchase transactions, but only with authoriza- tions.
Credit Allows you to credit back to a customer’s credit/debit card an amount that has previously been settled. You can credit all or part of an existing settlement. See Building Settlement/Credit requests on page 3-20. Settlement Allows you to settle an amount that was previously authorized on a customer’s credit/debit card. You can settle all or part of an existing authorization.
Stored Data Allows you to authorize an amount on a customer’s credit/debit Authorization card using customer data that is stored in our database. You pro- vide only a minimum of information, saving you time and effort. See Building Stored Data Requests on Stored Data Allows you to both authorize and settle an amount on a cus- page 3-23. Purchase tomer’s credit/debit card using customer data that is stored in our database. You provide only a minimum of information, sav- ing you time and effort.
Cancel Allows you to cancel a Credit, Settlement, Payment, or Independent Credit transaction. You can cancel one of these transactions as long as it is in a Pending state, which typically is See Building Cancel requests on page before midnight of the day that it is requested. In some cases, 3-27. you may find older Credit transactions in a Pending state.
Payment Allows you to credit an amount to a customer’s credit card. The Payment transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way. See Building Payment/Independent Credit requests on page 3-29. Independent Allows you to credit an amount to a customer’s credit card. The Credit Independent Credit transaction is not associated with a previ- ously existing authorization, so the amount of the transaction is not restricted in this way.
API Reference Guide for Web Services 1.0 3-1 Credit/Debit Card Transactions May 2019
Table 3-1: Supported Operations
Operation Description Request Type
Information Allows you to run a report through the API over a date range you See Building Transaction Lookup requests Lookup specify to return data on credit card transactions processed on page 3-34. through your merchant account.
Enrollment Allows you to determine whether a customer’s credit card is See Building Enrollment Lookup requests Lookup enrolled in the 3D Secure program. on page 3-38. NOTE: This operation is supported only for 3D Secure 1.0.2.
Authentication Allows you to send an Authentication request, in order to vali- See Building Authentication requests on date a cardholder’s password for credit cards enrolled in the 3D page 3-41. Secure program. NOTE: This operation is supported only for 3D Secure 1.0.2.
Availability of credit card operation types is allotted on a merchant-by-merchant basis, since not all merchant banks support all operations. If you have any questions, contact your account manager.
• The Authorization, Purchase, and Verification operations accept a ccAuthRequestV1 document object. • The Authorization Reversal operation accepts a ccAuthReversalRequestV1 document object. • The Settlement and Credit operations accept a ccPostAuthRequestV1 document object. • The Stored Data operations accept a ccStoredDataRequestV1 document object. • The Cancel Settle, Cancel Credit, and Cancel Payment operations accept a ccCancelRequestV1 docu- ment object. • The Payment and Independent Credit operations accept a ccPaymentRequestV1 document object. • The Information Lookup operation accepts a ccTxnLookupRequestV1 document object. • The Enrollment Lookup operation accepts a ccEnrollmentLookupRequestV1 document object. • The Authentication operation accepts a ccAuthenticateRequestV1 document object. • All operations return a ccTxnResponseV1 response.
3-2 May 2019 .NET example
.NET example
To build the .NET example: 1. Create a new project.
2. Add a Web Reference.
API Reference Guide for Web Services 1.0 3-3 Credit/Debit Card Transactions May 2019
3. Enter the WSDL URL and click the Add Reference button.
The Web client is now built.
4. Build the request and process response: • See Building Purchase/Authorization/Verification requests on page 3-4 • See Building Authorization Reversal requests on page 3-17 • See Building Settlement/Credit requests on page 3-20 • See Building Stored Data Requests on page 3-23 • See Building Cancel requests on page 3-27 • See Building Payment/Independent Credit requests on page 3-29 • See Building Enrollment Lookup requests on page 3-38 • See Building Authentication requests on page 3-41 • See Processing the response on page 3-44
Building Purchase/Authorization/Verification requests Purchase, Authorization, and Verification requests require the ccAuthRequestV1 document object. This section describes the structure of a ccAuthRequestV1 and how to construct one. See Table 3-2: ccAuthRe- questV1 Elements on page 3-8 for details on the elements required.
3-4 May 2019 Purchase example – C#
Purchase example – C#
All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the cardType element in the exam- ple below.
The following is a Purchase example in C#.
To make this an Authorize or Verification request, modify the value “ccPurchase” – in the line “CCTx- nResponseV1 ccTxnResponse = ccService.ccPurchase(ccAuthRequest);” below – to “ccAuthorize” or “ccVerification”, respectively.
//Prepare the call to the Credit Card Web Service CCAuthRequestV1 ccAuthRequest = new CCAuthRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ccAuthRequest.merchantAccount = merchantAccount; ccAuthRequest.merchantRefNum = "Ref-12345"; ccAuthRequest.amount = "10.00"; CardV1 card = new CardV1(); card.cardNum = "4653111111111111"; CardExpiryV1 cardExpiry = new CardExpiryV1(); cardExpiry.month = 11; cardExpiry.year = 2006; card.cardExpiry = cardExpiry; card.cardType = CardTypeV1.VI; card.cardTypeSpecified = true; card.cvdIndicator = 1; card.cvdIndicatorSpecified = true; card.cvd = "111"; ccAuthRequest.card = card; BillingDetailsV1 billingDetails = new BillingDetailsV1(); billingDetails.firstName = "Jane"; billingDetails.lastName = "Jones"; billingDetails.street = "123 Main Street"; billingDetails.city = "LA"; billingDetails.Item = (object) StateV1.CA; // California billingDetails.country = CountryV1.US; // United States billingDetails.countrySpecified = true; billingDetails.zip = "90210"; billingDetails.phone = "555-555-5555"; billingDetails.email = "[email protected]"; ccAuthRequest.billingDetails = billingDetails; ccAuthRequest.customerIP = "127.0.0.1"; ccAuthRequest.productType = ProductTypeV1.M; //M = Both Digital and Physical(e.g., software downloaded followed by media shipment) ccAuthRequest.productTypeSpecified = true;
// Perform the Web Services call for the purchase CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccPurchase(ccAuthRequest);
// Print out the result String responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision + " - "
API Reference Guide for Web Services 1.0 3-5 Credit/Debit Card Transactions May 2019
+ ccTxnResponse.description + Environment.NewLine;
if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
3-6 May 2019 ccAuthRequestV1 schema
ccAuthRequestV1 schema A ccAuthRequestV1 has the following structure:
API Reference Guide for Web Services 1.0 3-7 Credit/Debit Card Transactions May 2019
ccAuthRequestV1 elements The ccAuthRequestV1 document object may contain the following elements: Table 3-2: ccAuthRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used Max = 80 to authenticate the request. It is defined by Paysafe and provided to the mer- chant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used Max = 20 to authenticate the request. It is defined by Paysafe and provided to the mer- chant as part of the integration process.
merchantRefNum Yes String This is a unique ID number associated Max = 255 with each request. The value is created by the merchant and submitted as part of the request.
customerTokenId For internal use only.
amount Yes String This is amount of the transaction Max= request. 999999999.99 NOTE: Though mandatory, this value will be ignored for the ccVerification transaction.
card cardNum Yes String This is the card number used for the Min = 8 transaction. Max = 20
cardExpiry Yes The cardExpiry child element has two further child elements – month and year.
Child Element of cardExpiry
month Yes Int This is the month the credit card Max = 2 expires.
year Yes Int This is the year the credit card expires. Length = 4
cardType Optional Enumeration This is the type of card used for the transaction. Possible values are: • AM – American Express • DC – Diners Club • DI – Discover • JC – JCB • MC – Mastercard • MD – Maestro • SF – Swiff • SO – Solo • VD – Visa Debit • VE – Visa Electron • VI – Visa
3-8 May 2019 ccAuthRequestV1 elements
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
issueNum Optional Integer The 1- or 2-digit number located on the Max = 2 front of the card, following the card number. NOTE: The issueNum element can be used only when the cardType is MD (Maestro), or SO (Solo).
cvdIndicator Optional Integer This is the status of CVD value infor- Length = 1 mation. Possible values are: • 0 – The customer did not provide a value. • 1 – The customer provided a value. • 2 – The value is illegible. • 3 – The value is not on the card. NOTE: The cvdIndicator element is mandatory for the ccVerification trans- action. Also note that even though this element is optional, it is required for several risk-related checks and we strongly advise you to include it to avoid failed transactions.
cvd Conditional String The 3- or 4-digit security code that Length = 3 or 4 appears on the card following the card number. This code does not appear on imprints. NOTE: The cvd element is mandatory when the cvdIndicator element value = 1.
authentication indicator Optional Integer This is the Electronic Commerce Indi- NOTE: Use this element Value = 1 cator code, a 2-digit value that gets with ccAuthorize or returned by the card issuer indicating ccPurchase requests whether the cardholder was success- only. fully authenticated. Possible values are: Visa / Amex / JCB • 05 – Identifies a successfully authen- ticated transaction. • 06 – Identifies an attempted authenti- cated transaction. • 07 – Identifies a non-authenticated transaction. Mastercard • 01 – Identifies a non-authenticated transaction. • 02 – Identifies a successfully authen- ticated transaction. This value is returned in the eci child element of the tdsAuthenticateResponse element in the ccTxnResponseV1 to your ccAuthenticateRequestV1 request.
cavv Optional String This is the Cardholder Authentication Max = 80 Verification Value. This value is returned in the cavv child element of the tdsAuthenticateResponse element in the ccTxnResponseV1 to your ccAuthenti- cateRequestV1 request.
API Reference Guide for Web Services 1.0 3-9 Credit/Debit Card Transactions May 2019
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
xid Optional String This is the transaction identifier Max = 80 returned by the card issuer. This value is returned in the xid child element of the tdsAuthenticateResponse element in the ccTxnResponseV1 to your ccAuthenti- cateRequestV1 request. NOTE: This exists only for 3D Secure 1.0.2.
enrollmentStatus Optional Enumeration This indicates whether 3D Secure authentication is available for the card- holder. Possible values are: • Y – Authentication available • N – Cardholder not enrolled • U – Authentication unavailable • E – Error NOTE: This exists only for 3D Secure 1.0.2.
authenticationStatus Optional Enumeration This indicates the authentication out- come. Possible values are: • Y – Cardholder successfully authen- ticated with their Card Issuer. • A – Cardholder authentication was attempted. • N – Cardholder failed to successfully authenticate with their Card Issuer. • U – Authentication with the Card Issuer was unavailable. • E – Error • R – Rejected transaction NOTE: The value R exists only for 3D Secure 2.|
directoryServerTransactionId Optional String This is the unique directory server Max = 36 transaction ID required for Mastercard. NOTE: This exists only for 3D Secure 2 and is required only for the Master- card brand.
threeDSecureVersion Optional String This is the 3D Secure protocol version. Min = 5 NOTE: If no version is specified in the Max = 8 request, value defaults to 1.0.2. and is echoed in the response.
authCode Optional String This is the Authorization code assigned Max = 50 by the issuing bank and returned by Paysafe for a previous transaction. NOTE: Include this element only when instructed to do so by Paysafe.
firstName Optional String This is the customer’s first name. Max = 40
lastName Optional String This is the customer’s last name. Max = 40
3-10 May 2019 ccAuthRequestV1 elements
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
street Optional String This is the first line of the customer’s Max = 50 street address. NOTE: the street element is mandatory if you are processing a ccVerification transaction.
street2 Optional String This is the second line of the customer’s Max = 50 street address.
city Optional String This is the city in which the customer Max = 40 resides.
state/region Optional If state, This is the state/province/region in Enumeration which the customer resides. If region, then Provide state if within U.S./Canada. string Provide region if outside of U.S./Can- Max = 40 ada. See Appendix C: Geographical Codes for correct codes to use.
country Optional Enumeration This is the country in which the cus- tomer resides. See Country codes on page C-3 for correct codes to use.
zip Mandatory String This is the customer’s ZIP code if in the Max = 10 U.S.; otherwise, this is the customer’s postal code.
phone Optional String This is the customer’s telephone num- Max = 40 ber.
email Optional String This is the customer’s email address. Max = 100
shippingDetails carrier Optional Enumeration 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 Enumeration The method of shipment. Possible values are: • N – Next Day/Overnight • T – Two-Day Service • C – Lowest Cost • O – Other
firstName Optional String This is the recipient’s first name. Max = 40
lastName Optional String This is the recipient’s last name. Max = 40
API Reference Guide for Web Services 1.0 3-11 Credit/Debit Card Transactions May 2019
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
street Optional String This is the first line of the recipient’s Max = 50 street address.
street2 Optional String This is the second line of the recipient’s Max = 50 street address.
city Optional String This is the city in which the recipient Max = 40 resides.
state/region Optional If state, This is the state/province/region in Enumeration which the recipient resides. If region, then Provide state if within U.S./Canada. string Provide region if outside of U.S./Can- Max = 40 ada. See Appendix C: Geographical Codes for correct codes to use.
country Optional Enumeration This is the country in which the recipi- ent resides.
zip Optional String This is the recipient’s ZIP code if in the Max = 10 U.S.; otherwise, this is the recipient’s postal code.
phone Optional String This is the recipient’s phone number. Max = 40
email Optional String This is the recipient’s email address. Max = 100
recurring Optional NOTE: You cannot include both the recurring element and the storedCre- dential element in the same authoriza- tion request. Paysafe recommends using storedCredential.
recurringIndicator Conditional Enumeration Use this parameter to indicate whether a transaction is an initial or a repeat trans- action for a specific customer for whom you will be processing recurring trans- actions. Depending on which processing gate- way is used, if the value for a repeat transaction is set to R, the gateway may be more lenient regarding certain requirements such as CVD data and address information, authorizing the request without this data. Possible values are: • I – Initial Recurring • R – Subsequent Recurring
originalConfirmation Conditional String If this is a recurring transaction, this is Number Max = 15 the confirmation number returned by Paysafe for the initial transaction in the series. If you include this value, Paysafe will be able to more precisely identify an Authorization to Settle or a Settle- ment to Credit, should either of those transactions be required in the future.
3-12 May 2019 ccAuthRequestV1 elements
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
previousConfirmation Conditional String If this is a recurring transaction, this is Number Max = 15 the confirmation number returned by Paysafe for the most recent transaction in the series. If you include this value, Paysafe will be able to more precisely identify an Authorization to Settle or a Settlement to Credit, should either of those transactions be required in the future.
storedCredential Optional The storedCredential element is used to identify authorization requests that use credit card numbers that are stored by merchants, in order to improve authori- zation rates and reduce fraud. NOTE: You cannot include both the recurring element and the storedCre- dential element in the same authoriza- tion request. Paysafe recommends using storedCredential. If you are not sending this element and are sending the recurringIndicator ele- ment with the value R, type will be defaulted to RECURRING and occur- rence will be defaulted to SUBSE- QUENT. If recurringIndicator is sent with the value I, type will be defaulted to RECURRING and occurrence will be defaulted to INITIAL.
type Optional Enumeration This specifies the type of request being made. Possible values are: • ADHOC – Ad hoc consumer-initi- ated request • TOPUP – Unscheduled merchant- initiated request when a consumer balance is below a set limit • RECURRING – Scheduled, mer- chant-initiated recurring request
occurrence Optional Enumeration This specifies whether this stored cre- dential request is initial or recurring. Possible values are: • INITIAL – Used when this is the first time the consumer uses this credit card • RECURRING – Used when the con- sumer uses this credit card for subse- quent requests NOTE: The card cvd value is required when this is set to INITIAL.
customerIP Optional String This is the customer’s IP address. Max = 50
API Reference Guide for Web Services 1.0 3-13 Credit/Debit Card Transactions May 2019
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
productType Optional Enumeration This is the type of product sold. Possible values are: • P – Physical Goods • D – Digital Goods • C – Digital Content) • G – Gift Certificate/Digital Cash • S – Shareware • M – Both Digital and Physical • R – Account Replenish
targetVirtualAccount No This element is not applicable for credit card transactions.
cardRiskService For internal use only.
dupeCheck Optional Boolean This validates that this request is not a duplicate. A request is considered a duplicate if the cardNum, amount, and merchantRefNum are the same.
sdk version Conditional String This is the version of the SDK used, if Max = 20 any. Required if sdk element is provided.
platform Conditional String This is the integration language of the Max = 10 SDK used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional String This is the author of the SDK used. Set Max = 20 to value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
addendumData tag Optional String This is additional data that can be Max = 30 included with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be Max = 1024 included with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
merchantDescriptor dynamicDescriptor Optional String This is a merchant descriptor that will NOTE: Not all process- Max = 25 be displayed on a customer’s credit card ing gateways support this statement. parameter. Contact your account manager for phone Optional String This is the merchant’s phone number, more information. Max = 13 which will be appended to the merchant descriptor on a customer’s credit card statement.
accordD financingType Conditional Enumeration This is the type of financing offered. NOTE: Include this ele- Possible values are: ment only when • D – Deferred payment financing instructed to do so by • E – Equal payment financing Paysafe.
plan Conditional String This is the plan number for this financ- Max = 3 ing transaction.
3-14 May 2019 ccAuthRequestV1 elements
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
gracePeriod Optional Integer This is the grace period, in months, Max = 2 associated with deferred payment trans- actions.
term Optional Integer This is the number of payments, in Max = 2 months, for equal payment transactions.
description Optional String This is a description of the transaction, Max = 255 provided by the merchant.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional String This is the latitude of the mobile trans- Max = 24 action (e.g., 44.903889).
longitude Conditional String This is the longitude of the mobile Max = 24 transaction (e.g., -77.255123).
walletTransactionId Internal use only.
profile dateOfBirth Conditional This field allows you to record the card- holder’s date of birth, if you have it. It may be used to assist in authenticating the customer’s identity with a third- party validation service.
Child Element of dateOfBirth
day Mandatory Integer This is the customer‘s day of birth. Min = 1 Max = 31
month Mandatory Integer This is the customer‘s month of birth. Min = 1 Max = 12
year Mandatory Integer This is the customer‘s year of birth. Min = 1900 Max = 9999
visaAdditionalAuthData NOTE: This element is supported for both Visa and Mastercard. The recipient is deemed to be the person or party who has the contractual relationship with the merchant/ financial institution. This may be different from the cardholder, e.g., in the case of a parent topping up a child’s savings account. Therefore, the fields should not be collected on the same page as cardholder information, but instead be passed in the background from the mer- chant’s records. Include this element if your Merchant Category Code is 6012 and your registered trading address is in the United Kingdom. If you have any questions, contact your account manager. All fields are optional, however scheme fines may apply if data is consistently not supplied and chargebacks persist.
recipientDateOfBirth Optional
Child Element of recipientDateOfBirth
day Conditional Integer This is the recipient’s day of birth. Min = 1 Max = 31
API Reference Guide for Web Services 1.0 3-15 Credit/Debit Card Transactions May 2019
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
month Conditional Integer This is the recipient’s month of birth. Min = 1 Max = 12
year Conditional Integer This is the recipient’s year of birth. Min = 1900 Max = 9999
recipientZip Optional String This is the recipient‘s postcode. Max = 10 NOTE: The last 3 characters are not sent to the banking network.
recipientLastName Optional String This is the recipient‘s last name or sur- Max = 40 name. NOTE: Only the first 6 characters are sent to the banking network.
recipientAccountNumber Optional String This is the recipient‘s account number, Max = 25 e.g., a loan agreement number or cus- tomer ID. In the case where the recipi- ent account is a prepaid card, the card number may be sent in full. NOTE: Only the first 6 and last 4 char- acters are sent to the banking network and will be masked accordingly within the back office and any other reports, to comply with PCI regulations.
entryMode Optional Enumeration This is how the transaction has been ini- tiated and will affect the way it will be processed. Possible values are:
• MOTO - Mail Order/Telephone Order NOTE: Include this element only when instructed to do so by Paysafe.
addendumData tag/value pairs
Not all processing gateways support all addendumData tag/value pairs. Contact your account manager for more information
The following table contains the tag/value pairs supported for the addendumData element. Table 3-3: addendumData Tag/Value Pairs
Tag Value
CUST_ACCT_OPEN_DATE This is the date the merchant account opened. Format = yyyymmdd
CUSTOMER_ID This is an ID used by the merchant. Maximum of 64 numeric characters.
3-16 May 2019 Building Authorization Reversal requests
Table 3-3: addendumData Tag/Value Pairs (Continued)
Tag Value
CUSTOMER_SESSION_ID This string is used to initiate a lookup call with a device profiler. It must be the same string you use as the session identifier in the profiling JavaScript on the HTML page you present to your customer for device profiling. Accepted characters are: [a-z][A-Z][_][-]
INCLUDE_PRA_RESPONSE Include this tag/value pair in the Credit transaction request in order to have the Purchase Return Authorization response returned in the Credit transaction response.
Possible values: • true • false Note: It is applicable only if acquirer/processor supports it.
KEYWORD This value can be any text the merchant wants to use, e.g., used for reporting pur- poses in the Paysafe merchant back office. For example, you can use this as a tag to identify the transaction or the product purchased at your site. • Maximum of 255 alphanumeric characters. • Can be specified more than once, with a different value each time. • Valid for CCAuthRequestV1 and CCStoredDataRequestV1 objects.
MERCHANT_COUNTRY_CODE This is a two-character country code. Value is not validated.
MERCHANT_SIC_CODE This is the ISO Standard Industry Code (SIC) for the merchant. This is a 4-char- acter numerical string.
MERCHANT_ZIP_CODE Maximum of 10 alphanumeric characters.
PRODUCT_TYPE This is the type of product purchased. Possible values are: • P – Physical goods • D – Digital goods • C – Digital content • G – Gift certificate/digital cash • S – Shareware • M – Digital and physical • R – Account replenish (e.g., subscription renewal)
PRODUCT_CODE This is the product code of the item purchased. Maximum of 18 alphanumeric characters.
SERVICE_REQUEST_CURRENCY Include this tag/value pair in order to have the merchant account’s currency NOTE: This tag/value pair can be included returned in the transaction response. with the ccAuthRequestV1 document object Possible values: only (i.e., for Authorization, Purchase, and Ver- • on ification card transaction requests). • off
USER_DATA_04 This is a user-defined field. Maximum of 255 alphanumeric characters.
USER_DATA_05 This is a user-defined field. Maximum of 255 alphanumeric characters.
USER_DATA_06 This is a user-defined field. Maximum of 255 alphanumeric characters.
Building Authorization Reversal requests Authorization Reversal requests allow you to reverse all or part of an existing authorization, provided no settlements (either full or partial) have been processed against that authorization.
API Reference Guide for Web Services 1.0 3-17 Credit/Debit Card Transactions May 2019
You can use Authorization Reversal transactions to reverse Authorizations only. You cannot reverse Purchase transactions.
Authorization Reversal requests require the ccAuthReversalRequestV1 document object. This section describes the structure of a ccAuthReversalRequestV1 and how to construct one. See Table 3-4: ccAuthRe- versalRequestV1 Elements on page 3-19 for details on the elements required.
Authorization Reversal example – C# The following is an Authorization Reversal example in C#.
//Prepare the call to the Credit Card Web Service CCAuthReversalRequestV1 authReversalRequest = new CCAuthReversalRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; authReversalRequest.merchantAccount = merchantAccount;
authReversalRequest.confirmationNumber = "115147689"; authReversalRequest.merchantRefNum = "AR2"; authReversalRequest.reversalAmount = "18.00";
// Perform the Web Services call for the Auth Reversal CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccAuthorizeReversal(authReversalRequest);
// Print out the result String responseTxt = ccTxnResponse.confirmationNumber + " - " + ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description; responseTxt += Environment.NewLine; responseTxt += "Details:" + Environment.NewLine; if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); consoleTextBox.Text = responseTxt; if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
3-18 May 2019 ccAuthReversalRequestV1 schema
ccAuthReversalRequestV1 schema A ccAuthReversalRequestV1 has the following structure:
ccAuthReversalRequestV1 elements The ccAuthReversalRequestV1 document object contains the following elements: Table 3-4: ccAuthReversalRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the inte- gration process.
confirmationNumber Yes String This is the confirmation number returned by Pay- Max = 15 safe for the Authorization you want to reverse.
merchantRefNum Yes String This is a unique ID number associated with each Max = 255 request. The value is created by the merchant and submitted as part of the request.
API Reference Guide for Web Services 1.0 3-19 Credit/Debit Card Transactions May 2019
Table 3-4: ccAuthReversalRequestV1 Elements (Continued)
Element Child Element Required Type Description
reversalAmount Optional String This is amount of the original authorization that Max= you want to reverse. If you omit this element, the 999999999.99 full amount of the original authorization will be reversed. NOTE: Not all processing gateways support par- tial authorization reversals. Contact your account manager for more information.
addendumData tag Optional String This is additional data that can be included with Max = 30 the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be included with Max = 1024 the transaction request. See addendumData tag/value pairs on page 3-16 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional String This is the latitude of the mobile transaction (e.g., Max = 24 44.903889).
longitude Conditional String This is the longitude of the mobile transaction Max = 24 (e.g., -77.255123).
Building Settlement/Credit requests Settlement and Credit requests require the ccPostAuthRequestV1 document object. This section describes the structure of a ccPostAuthRequestV1 and how to construct one. See Table 3-5: ccPostAuthRequestV1 Elements on page 3-22 for details on the elements required.
Settlement example – C# The following is a Settlement example in C#.
To make this a Credit request, just modify the value “ccSettlement” – in the line “CCTxnResponseV1 ccTxnResponse = ccService.ccSettlement(ccPostAuthRequest);” below – to “ccCredit”.
//Prepare the call to the Credit Card Web Service CCPostAuthRequestV1 ccPostAuthRequest = new CCPostAuthRequestV1(); ccPostAuthRequest.confirmationNumber = "123456"; MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID= "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ccPostAuthRequest.merchantAccount = merchantAccount; ccPostAuthRequest.merchantRefNum = "Ref-12345"; ccPostAuthRequest.amount = "10.00";
// Perform the Web Service call for the Settlement CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccSettlement(ccPostAuthRequest);
// Print out the result
3-20 May 2019 ccPostAuthRequestV1 schema
String responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description ; responseTxt += "Details:" + Environment.NewLine;
if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt);
if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
ccPostAuthRequestV1 schema A ccPostAuthRequestV1 document object has the following structure:
API Reference Guide for Web Services 1.0 3-21 Credit/Debit Card Transactions May 2019
ccPostAuthRequestV1 elements The ccPostAuthRequestV1 document object may contain the following elements: Table 3-5: ccPostAuthRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
confirmationNumber Yes String This is the confirmation number returned by Max = 15 Paysafe for the original request.
merchantRefNum Yes String This is a unique ID number associated with Max = 40 each request. The value is created by the mer- chant and submitted as part of the request.
amount Optional String This is amount of the transaction request. Max= You can Settle all or part of an Authorization. 999999999.99 You can Credit all or part of a Settlement.
origMerchantTxn Conditional String This is the merchant transaction ID from a Max = 255 Settlement that was processed via the Direct Payment API and that is now being credited via the Web Services API.
dupeCheck Optional Boolean This validates that this request is not a dupli- cate. A request is considered a duplicate if the cardNum, amount, and merchantRefNum are the same.
sdk version Conditional String This is the version of the SDK used, if any. Max = 20 Required if sdk element is provided.
platform Conditional String This is the integration language of the SDK Max = 10 used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional String This is the author of the SDK used. Set to Max = 20 value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
addendumData tag Optional String This is additional data that can be included Max = 30 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be included Max = 1024 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
3-22 May 2019 Building Stored Data Requests
Table 3-5: ccPostAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
latitude Conditional String This is the latitude of the mobile transaction Max = 24 (e.g., 44.903889).
longitude Conditional String This is the longitude of the mobile transac- Max = 24 tion (e.g., -77.255123).
accordD Optional You can include the accordD element only if NOTE: Include this you have already provided it in the authoriza- element only when tion request you are now settling and you instructed to do so by want to change one or more of the terms Paysafe. It cannot be specified in the child elements. used for credit requests.
financingType Conditional Enumeration This is the type of financing offered. Possible values are: • D – Deferred payment financing • E – Equal payment financing
plan Conditional String This is the plan number for this financing Max = 3 transaction.
gracePeriod Optional Integer This is the grace period, in months, associ- Max = 2 ated with deferred payment transactions.
term Optional Integer This is the number of payments, in months, Max = 2 for equal payment transactions.
Building Stored Data Requests Stored Data Authorization/Purchase requests require the ccStoredDataRequestV1 document object. This section describes the structure of a ccStoredDataRequestV1 and how to construct one. See Table 3-6: ccStoredDataRequestV1 Elements on page 3-25 for details on the elements required. Stored Data requests allow you to perform credit card Authorizations and Purchases by providing a mini- mum of customer information. The Stored Data request requires a Confirmation Number from a previous Authorization or Purchase.
The Confirmation Number can be a maximum of 24 months old.
This Confirmation Number allows Paysafe to access from its database most of the data required for the transaction.
If you are processing a Stored Data request using a Confirmation Number from a transaction that included the visaAdditionalAuthData element (see Table 3-2: ccAuthRequestV1 Elements on page 3-8), then this information will be included in the new request. However, if you add the visaAdditionalAuthData element separately to the new Stored Data request, it will overwrite any simi- lar data associated with the Confirmation Number, for that request only.
Stored Data Authorization example – C# The following is a Stored Data Authorization example in C#.
API Reference Guide for Web Services 1.0 3-23 Credit/Debit Card Transactions May 2019
To make this a Stored Data Purchase request, just modify the value “ccStoredDataAuthorize” – in the line “CCTxnResponseV1 ccTxnResponse = ccService.ccStoredDataAuthorize(ccStoredDataRequest);” below – to “ccStoredDataPurchase”.
//Prepare the call to the Credit Card Web Service MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD";
CCStoredDataRequestV1 ccStoredDataRequest = new CCStoredDataRequestV1(); ccStoredDataRequest.confirmationNumber = "111374429"; ccStoredDataRequest.amount = "97.97"; ccStoredDataRequest.merchantRefNum = "jim55"; ccStoredDataRequest.merchantAccount = merchantAccount;
// Perform the Web Service call for the Stored Data Transaction CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccStoredDataAuthorize(ccStoredDataRequest); String responseTxt = "";
// Print out the result if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
ccStoredDataRequestV1 schema A ccStoredDataRequestV1 document object has the following structure:
3-24 May 2019 ccStoredDataRequestV1 elements
ccStoredDataRequestV1 elements The ccStoredDataRequestV1 document object may contain the following elements: Table 3-6: ccStoredDataRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Required String This is the merchant account number. Max = 10
storeID Required String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Required String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
merchantRefNum Required String This is a unique ID number associated with Max = 255 each request. The value is created by the mer- chant and submitted as part of the request.
confirmationNumber Required String This is the confirmation number returned by Max = 15 Paysafe for the original request. NOTE: The confirmationNumber can be a maximum of 24 months old.
amount Required String This is amount of the transaction request. Max= 999999999.99
API Reference Guide for Web Services 1.0 3-25 Credit/Debit Card Transactions May 2019
Table 3-6: ccStoredDataRequestV1 Elements (Continued)
Element Child Element Required Type Description
cardExpiry month Optional Int This is the month the credit card expires. Max = 2 Use this element to include updated card expiry date information, if required, to be included with the rest of the transaction data.
year Optional Int This is the year the credit card expires. Length = 4 Use this element to include updated card expiry date information, if required, to be included with the rest of the transaction data.
cvdIndicator Optional Integer This is the status of CVD value information. Length = 1 Possible values are: • 0 – The customer did not provide a value. • 1 – The customer provided a value. • 2 – The value is illegible. • 3 – The value is not on the card.
cvd Conditional String The 3- or 4-digit security code that appears on Length = 3 or 4 the card following the card number. This code does not appear on imprints. When you provide the CVD for a Stored Data request, the transaction benefits from full CVD protection. However, you must never store the CVD information, but instead have the consumer pass it in with the request. NOTE: The cvd element is mandatory when the cvdIndicator element value = 1.
storedCredential Optional The storedCredential element is used to iden- tify stored data requests that use credit card information stored by Paysafe. In this case, it would be card information associated with a confirmation number returned in the response to a previously successful authorization.
type Optional Enumeration This specifies the type of request being made. Possible values are: • ADHOC – Ad hoc consumer-initiated request • TOPUP – Unscheduled merchant-initiated request when a consumer balance is below a set limit • RECURRING – Scheduled, merchant-initi- ated recurring request NOTE: Default value is ADHOC.
occurrence Optional Enumeration This specifies whether this stored credential request is initial or recurring. Possible values are: • INITIAL – Used when this is the first time the consumer uses this credit card • SUBSEQUENT – Used when the consumer uses this credit card for subsequent requests NOTE: Default value is SUBSEQUENT. The card cvd value is required when this is set to INITIAL.
3-26 May 2019 Building Cancel requests
Table 3-6: ccStoredDataRequestV1 Elements (Continued)
Element Child Element Required Type Description
merchantDescriptor dynamicDescriptor Optional String This is a merchant descriptor that will be dis- NOTE: Not all pro- Max = 25 played on a customer’s credit card statement. cessing gateways sup- port this parameter. phone Optional String This is the merchant’s phone number, which Contact your account Max = 13 will be appended to the merchant descriptor on manager for more a customer’s credit card statement. information.
addendumData tag Optional String This is additional data that can be included Max = 30 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be included Max = 1024 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
Building Cancel requests Use the ccCancelRequestV1 document object to cancel Settle, Credit, Payment, and Independent Credit transactions. This section describes the structure of a ccCancelRequestV1 and how to construct one. See Table 3-7: ccCancelRequestV1 Elements on page 3-28 for details on the elements required.
Cancel Settle example – C# The following is a Cancel Settle example in C#.
To make this a request to cancel a Credit, Payment, or an Independent Credit, just modify the value “ccCancelSettle” – in the line “CCTxnResponseV1 ccTxnResponse = ccService.ccCancelSet- tle(ccCancelRequest);” below – to “ccCancelCredit”, “ccCancelPayment”, or “ccCancelIndependentCredit”, respectively.
//Prepare the call to the Credit Card Web Service CCCancelRequestV1 ccCancelRequest = new CCCancelRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID= "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ccCancelRequest.merchantAccount = merchantAccount; ccCancelRequest.confirmationNumber = "123456";
// Perform the Web Services call for the cancel settle CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccCancelSettle(ccCancelRequest);
// Print out the result String responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description ; responseTxt += "Details:" + Environment.NewLine; if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) {
API Reference Guide for Web Services 1.0 3-27 Credit/Debit Card Transactions May 2019
responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt);
if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
ccCancelRequestV1 schema A ccCancelRequestV1 document object has the following structure:
ccCancelRequestV1 elements The ccCancelRequestV1 document object may contain the following elements: Table 3-7: ccCancelRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
3-28 May 2019 Building Payment/Independent Credit requests
Table 3-7: ccCancelRequestV1 Elements (Continued)
Element Child Element Required Type Description
storeID Yes String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
confirmationNumber Yes String This is the confirmation number returned by Max = 15 Paysafe for the original Settlement or Credit request.
sdk version Conditional String This is the version of the SDK used, if any. Max = 20 Required if sdk element is provided.
platform Conditional String This is the integration language of the SDK Max = 10 used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional String This is the author of the SDK used. Set to Max = 20 value “op” when the SDK is provided by Pay- safe. Required if sdk element is provided.
addendumData tag Optional String This is additional data that can be included Max = 30 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be included Max = 1024 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional String This is the latitude of the mobile transaction Max = 24 (e.g., 44.903889).
longitude Conditional String This is the longitude of the mobile transaction Max = 24 (e.g., -77.255123).
Building Payment/Independent Credit requests Payments and Independent Credits require the ccPaymentRequestV1 document object. This section describes the structure of a ccPaymentRequestV1 and how to construct one. See Table 3-8: ccPaymentRe- questV1 Elements on page 3-32 for details on the elements required.
Payment example – C#
All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the cardType element in the exam- ple below.
API Reference Guide for Web Services 1.0 3-29 Credit/Debit Card Transactions May 2019
The following is a Payment example in C#.
To make this an Independent Credit request, just modify the value “ccPayment” – in the line “CCTxn- ResponseV1 ccTxnResponse = ccService.ccPayment(ccPaymentRequest);” below – to “ccIndependentCredit”.
//Prepare the call to the Credit Card Web Service CCPaymentRequestV1 ccPaymentRequest = new CCPaymentRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ccPaymentRequest.merchantAccount = merchantAccount; ccPaymentRequest.merchantRefNum = "Ref-12345"; ccPaymentRequest.amount = "10.00"; CardV1 card = new CardV1(); card.cardNum = "4653111111111111"; CardExpiryV1 cardExpiry = new CardExpiryV1(); cardExpiry.month = 11; cardExpiry.year = 2006; card.cardExpiry = cardExpiry; card.cardType = CardTypeV1.VI; card.cardTypeSpecified = true; card.cvdIndicator = 1; card.cvdIndicatorSpecified = true; card.cvd = "111"; ccPaymentRequest.card = card; BillingDetailsV1 billingDetails = new BillingDetailsV1(); billingDetails.firstName = "Jane"; billingDetails.lastName = "Jones"; billingDetails.street = "123 Main Street"; billingDetails.city = "LA"; billingDetails.Item = (object)StateV1.CA; // California billingDetails.country = CountryV1.US; // United States billingDetails.countrySpecified = true; billingDetails.zip = "90210"; billingDetails.phone = "555-555-5555"; billingDetails.email = "[email protected]"; ccPaymentRequest.billingDetails = billingDetails;
// Perform the Web Services call for the payment request CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccPayment(ccPaymentRequest);
// Print out the result String responseTxt ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description ;
responseTxt += "Details:" + Environment.NewLine;
if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; }
3-30 May 2019 ccPaymentRequestV1 schema
} responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); } } catch (WebException we) { consoleTextBox.Text += we.Message.ToString(); consoleTextBox.Refresh(); }
ccPaymentRequestV1 schema A ccPaymentRequestV1 has the following structure:
ccPaymentRequestV1 elements The ccPaymentRequestV1 document object may contain the following elements:
API Reference Guide for Web Services 1.0 3-31 Credit/Debit Card Transactions May 2019
Table 3-8: ccPaymentRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 80 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Yes String This is a unique ID number associated with Max = 40 each request. The value is created by the merchant and submitted as part of the request.
customerTokenId For internal use only.
amount Yes String This is amount of the transaction request. The amount maximum is configured on a merchant-by-merchant basis. It applies to each transaction and to the daily maximum per credit card. Contact your account man- ager for details.
card cardNum Yes String This is the card number used for the transac- Min = 8 tion. Max = 20
cardExpiry Yes The cardExpiry child element has two fur- ther child elements – month and year.
Child Element of cardExpiry
month Yes Int This is the month the credit card expires. Max = 2
year Yes Int This is the year the credit card expires. Length = 4
cardType Optional Enumeration This is the type of card used for the transac- tion. Possible values are: • AM – American Express • DC – Diners Club • DI – Discover • JC – JCB • MC – Mastercard • MD – Maestro • SO – Solo • VD – Visa Debit • VE – Visa Electron • VI – Visa
issueNum Optional Integer The 1- or 2-digit number located on the front Max = 2 of the card, following the card number. NOTE: The issueNum element can be used only when the cardType is MD (Maestro), or SO (Solo).
3-32 May 2019 ccPaymentRequestV1 elements
Table 3-8: ccPaymentRequestV1 Elements (Continued)
Element Child Element Required Type Description
cvdIndicator Optional Integer This is the status of CVD value information. Length = 1 Possible values are: • 0 – The customer did not provide a value. • 1 – The customer provided a value. • 2 – The value is illegible. • 3 – The value is not on the card. NOTE: Even though this element is optional, it is required for several risk- related checks and we strongly advise you to include it to avoid failed transactions.
cvd Conditional String The 3- or 4-digit security code that appears Length = 3 or on the card following the card number. This 4 code does not appear on imprints. NOTE: The cvd element is mandatory when the cvdIndicator element value = 1.
firstName Optional String This is the customer’s first name. Max = 40
lastName Optional String This is the customer’s last name. Max = 40
street Optional String This is the first line of the customer’s street Max = 50 address.
street2 Optional String This is the second line of the customer’s Max = 50 street address.
city Optional String This is the city in which the customer Max = 40 resides.
state/region Optional If state, This is the state/province/region in which Enumeration the customer resides. If region, then Provide state if within U.S./Canada. Provide string region if outside of U.S./Canada. Max = 40 See Appendix C: Geographical Codes for correct codes to use.
country Optional Enumeration This is the country in which the customer resides. See Country codes on page C-3 for correct codes to use.
zip Mandatory String This is the customer’s ZIP code if in the Max = 10 U.S.; otherwise, this is the customer’s postal code.
phone Optional String This is the customer’s telephone number. Max = 40
email Optional String This is the customer’s email address. Max = 100
sdk version Conditional String This is the version of the SDK used, if any. Max = 20 Required if sdk element is provided.
platform Conditional String This is the integration language of the SDK Max = 10 used (e.g., Java, .NET). Required if sdk element is provided.
API Reference Guide for Web Services 1.0 3-33 Credit/Debit Card Transactions May 2019
Table 3-8: ccPaymentRequestV1 Elements (Continued)
Element Child Element Required Type Description
provider Conditional String This is the author of the SDK used. Set to Max = 20 value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
authcode Optional String This is the Authorization code assigned by Max = 50 the issuing bank and returned by Paysafe for a previous transaction. NOTE: Include this element only when instructed to do so by Paysafe.
previousConfirmation- Optional String This is the confirmation number of a previ- Number Max = 20 ously processed authorization. NOTE: Include this element only when instructed to do so by Paysafe.
addendumData tag Optional String This is additional data that can be included Max = 30 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
value Optional String This is additional data that can be included Max = 1024 with the transaction request. See addendumData tag/value pairs on page 3-16 for details.
Building Transaction Lookup requests The credit card Transaction Lookup request allows you to run a report, over a date range you specify, to return data for credit card transactions processed through your merchant account. For example, you might want to determine the result of a transaction that timed out, with no response returned, or the result of a batched transaction that gets declined at a later date. You can look up the following transaction types: • Authorization • Purchase • Settlement • Credit • Payment/Independent Credit
Transaction Lookup example – C# The following is a ccTxnLookupRequest example in C#.
// Prepare the call to the Credit Card Web Service CCTxnLookupRequestV1 ccTxnLookupRequest = new CCTxnLookupRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; ccTxnLookupRequest.merchantAccount = merchantAccount; ccTxnLookupRequest.merchantRefNum = "123456789";
DateV1 startDate = new DateV1();
3-34 May 2019 Transaction Lookup example – C#
startDate.year = "2012"; startDate.month = "08"; startDate.day = "15"; startDate.hour = "11"; startDate.minute = "00"; startDate.second = "00"; ccTxnLookupRequest.startDate = startDate;
DateV1 endDate = new DateV1(); endDate.year = "2012"; endDate.month = "08"; endDate.day = "15"; endDate.hour = "14"; endDate.minute = "00"; endDate.second = "00"; ccTxnLookupRequest.endDate = endDate;
//Perform the Web Services call to process the request CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccTxnLookup(ccTxnLookupRequest); // Print out the result String responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision; responseTxt += "Transactions:" + Environment.NewLine; if (ccTxnResponse.transaction != null) { for (int i = 0; i < ccTxnResponse.txnLookupResult.length; i++) { responseTxt += " - confirmationNumber: " + ccTxnResponse.txnLookupResult[i].confirmationNumber + Environment.NewLine; responseTxt += " - decison: " + ccTxnResponse.txnLookupResult[i].decision + Environment.NewLine; responseTxt += " - code: " + ccTxnResponse.txnLookupResult[i].code + Environment.NewLine; responseTxt += " - transaction type: " + ccTxnResponse.txnLookupResult[i].tranType + Environment.NewLine; responseTxt += " - transaction time: " + ccTxnResponse.txnLookupResult[i].txnTime + Environment.NewLine; responseTxt += " - merchantRefNum: " + ccTxnResponse.txnLookupResult[i].merchantRefNum + Environment.NewLine; responseTxt += " - card ending: " + ccTxnResponse.txnLookupResult[i].cardEnding + Environment.NewLine; responseTxt += " - card ending: " + ccTxnResponse.txnLookupResult[i].cardEnding + Environment.NewLine;
CardExpiryV1 expiry = ccTxnResponse.txnLookupResult[i].cardExpiry; responseTxt += " - card expiry: " + expiry.month + "/" + expiry.year + Environment.NewLine;
responseTxt += Environment.NewLine + Environment.NewLine; }
System.Console.WriteLine(responseTxt); }
API Reference Guide for Web Services 1.0 3-35 Credit/Debit Card Transactions May 2019
ccTxnLookupRequestV1 schema A ccTxnLookupRequestV1 has the following structure:
ccTxnLookupRequestV1 elements The ccTxnLookupRequestV1 document object may contain the following elements: Table 3-9: ccTxnLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
confirmationNumber Optional String This is the confirmation number returned by Max = 15 Paysafe in response to the original request. Include this element only if you want to search using this field. This field takes precedence over the merchantRefNum field. NOTE: If you include this element, you do not have to specify the startDate or endDate elements.
3-36 May 2019 ccTxnLookupRequestV1 elements
Table 3-9: ccTxnLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
netbanxReference Optional String This is a transaction ID used to identify certain Max = 18 legacy transactions. NOTE: If you include this element, you must specify the startDate and endDate elements.
merchantRefNum Optional String This is a unique ID number associated with the Max = 255 original request. The value is created by the merchant and submitted as part of the request. NOTE: If you include this element, you must specify the startDate and endDate elements.
startDate year Conditional Int This is the year set for the search start. Max = 9999
month Conditional Int This is the month set for the search start. Min = 1 Max = 12
day Conditional Int This is the day set for the search start. Min = 1 Max = 31
hour Conditional Int This is the hour set for the search start. Min = 0 Max = 23
minute Conditional Int This is the minute set for the search start. Min = 0 Max = 59
second Conditional Int This is the second set for the search start. Min = 0 Max = 59
endDate year Conditional Int This is the year set for the search end. Max = 9999
month Conditional Int This is the month set for the search end. Min = 1 Max = 12
day Conditional Int This is the day set for the search end. Min = 1 Max = 31
hour Conditional Int This is the hour set for the search end. Min = 0 Max = 23
minute Conditional Int This is the minute set for the search end. Min = 0 Max = 59
second Conditional Int This is the second set for the search end. Min = 0 Max = 59
API Reference Guide for Web Services 1.0 3-37 Credit/Debit Card Transactions May 2019
Building Enrollment Lookup requests Use the Enrollment Lookup request to determine whether a cardholder’s credit card is enrolled in the 3D Secure program. Enrollment Lookup requests require the ccEnrollmentLookupRequestV1 document object. This section describes the structure of a ccEnrollmentLookupRequestV1 and how to construct one. See Table 3-10: ccEnrollmentLookupRequestV1 Elements on page 3-40 for details on the elements required.
This operation is supported only for 3D Secure 1.0.2. See https://developer.paysafe.com/en/rest-apis/3d-secure-2/getting-started/introduction-to-3d-secure- 2/ for information about using 3D Secure 2.
Enrollment Lookup example – C# The following is an Enrollment Lookup example in C#.
All optional elements that take non-nullable data types (e.g., int or enum) must have their specified attribute set to true when setting values for those elements. See the cardType element in the exam- ple below.
//Prepare the call to the Credit Card Web Service CCEnrollmentLookupRequestV1 enrollmentLookupRequest = new CCEnrollmentLookupRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; enrollmentLookupRequest.merchantAccount = merchantAccount;
enrollmentLookupRequest.merchantRefNum = "Ref-12345"; enrollmentLookupRequest.amount = "97.97";
CardV1 card = new CardV1(); card.cardNum = "4653111111111111"; CardExpiryV1 cardExpiry = new CardExpiryV1(); cardExpiry.month = 11; cardExpiry.year = 2013; card.cardExpiry = cardExpiry; card.cardType = CardTypeV1.VI; card.cardTypeSpecified = true; enrollmentLookupRequest.card = card;
// Perform the Web Services call for the TDS Enrollment Lookup CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccTDSLookup(enrollmentLookupRequest);
// Print out the result String responseTxt = ccTxnResponse.confirmationNumber + " - " + ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description; responseTxt += Environment.NewLine; responseTxt += "Details:" + Environment.NewLine; if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++)
3-38 May 2019 ccEnrollmentLookupRequestV1 schema
{ responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt += "TDSResponse:" + Environment.NewLine; if (ccTxnResponse.tdsResponse != null) { responseTxt += " - " + ccTxnResponse.tdsResponse.acsURL + Environment.NewLine; responseTxt += " - " + ccTxnResponse.tdsResponse.paymentRequest + Environment.NewLine; responseTxt += " - " + ccTxnResponse.tdsResponse.enrollmentStatus + Environment.NewLine; responseTxt += " - " + ccTxnResponse.tdsResponse.eci + Environment.NewLine; } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt); consoleTextBox.Text = responseTxt; if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
ccEnrollmentLookupRequestV1 schema A ccEnrollmentLookupRequestV1 has the following structure:
ccEnrollmentLookupRequestV1 elements The ccEnrollmentLookupRequestV1 document object may contain the following elements:
API Reference Guide for Web Services 1.0 3-39 Credit/Debit Card Transactions May 2019
Table 3-10: ccEnrollmentLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
merchantRefNum Yes String This is a unique ID number associated with Max = 255 each request. The value is created by the mer- chant and submitted as part of the request.
amount Yes String This is amount of the transaction request. Max= NOTE: Though the amount element is manda- 999999999.99 tory for the Enrollment Lookup transaction, no amount is actually processed against the credit card.
card cardNum Yes String This is the card number used for the transac- Min = 8 tion. Max = 20
cardExpiry Yes The cardExpiry child element has two further child elements – month and year.
Child Element of cardExpiry
month Yes Int This is the month the credit card expires. Max = 2
year Yes Int This is the year the credit card expires. Length = 4
cardType Optional Enumeration This is the type of card used for the transaction. Possible values are: • JC – JCB • MC – Mastercard • VI – Visa
issueNum Optional Integer The 1- or 2-digit number located on the front of Max = 2 the card, following the card number. NOTE: The issueNum element is not used for this request type.
cvdIndicator Optional Integer This is the status of CVD value information. Length = 1 Possible values are: • 0 – The customer did not provide a value. • 1 – The customer provided a value. • 2 – The value is illegible. • 3 – The value is not on the card. NOTE: the cvdIndicator element is not used for this request type.
3-40 May 2019 Building Authentication requests
Table 3-10: ccEnrollmentLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
cvd Conditional String The 3- or 4-digit security code that appears on Length = 3 or 4 the card following the card number. This code does not appear on imprints. NOTE: The cvd element is not used for this request type.
Building Authentication requests Use the Authentication request to allow a cardholder to authenticate their card at the issuer and to retrieve the values required for the authentication element of a ccAuthRequestV1 transaction. Authentication requests require the ccAuthenticateRequestV1 document object. This section describes the structure of a ccAuthenticateRequestV1 and how to construct one. See Table 3-11: ccAuthenticateRequestV1 Elements on page 3-42 for details on the elements required.
This operation is supported only for 3D Secure 1.0.2. See https://developer.paysafe.com/en/rest-apis/3d-secure-2/getting-started/introduction-to-3d-secure- 2/ for information about using 3D Secure 2.
Authentication example – C# The following is an Authentication example in C#.
//Prepare the call to the Credit Card Web Service CCAuthenticateRequestV1 authenticateRequest = new CCAuthenticateRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD"; authenticateRequest.merchantAccount = merchantAccount; authenticateRequest.confirmationNumber = "myConfirmationNumber"; authenticateRequest.paymentResponse = "myPaymentResponse";
// Perform the Web Services call for the authentication CreditCardServiceV1 ccService = new CreditCardServiceV1(); CCTxnResponseV1 ccTxnResponse = ccService.ccTDSAuthenticate(authenticateRequest);
// Print out the result String responseTxt = ccTxnResponse.confirmationNumber + " - " + ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description; responseTxt += Environment.NewLine; responseTxt += "Details:" + Environment.NewLine; if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt);
API Reference Guide for Web Services 1.0 3-41 Credit/Debit Card Transactions May 2019
consoleTextBox.Text = responseTxt;
if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision); }
ccAuthenticateRequestV1 schema A ccAuthenticateRequestV1 has the following structure:
ccAuthenticateRequestV1 elements The ccAuthenticateRequestV1 document object may contain the following elements: Table 3-11: ccAuthenticateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to Max = 20 authenticate the request. It is defined by Pay- safe and provided to the merchant as part of the integration process.
confirmationNumber Yes String This is the confirmation number in the ccTxn- Max = 15 ResponseV1 returned by Paysafe in response to the ccEnrollmentLookupRequestV1.
3-42 May 2019 ccAuthenticateRequestV1 elements
Table 3-11: ccAuthenticateRequestV1 Elements (Continued)
Element Child Element Required Type Description
paymentResponse Yes String This is the Payment Authentication Response that is returned from the issuing bank via your customer’s Web browser once your customer has provided their authentication information. It is an encoded response generated by the Issuer ACS software. Its digital signature will be verified through Paysafe to ensure it was generated by a legitimate Issuer.
merchantRefNum Optional String This is a unique ID number associated with Max = 255 each request. The value is created by the mer- chant and submitted as part of the request.
API Reference Guide for Web Services 1.0 3-43 Credit/Debit Card Transactions May 2019
Processing the response A ccTxnResponseV1 has the following structure:
3-44 May 2019 Processing the response
The following elements are relevant for a ccTxnResponseV1: Table 3-12: ccTxnResponseV1
Element Child Element Required Type Description
confirmationNumber Yes String This is the confirmation number Max = 15 returned by Paysafe.
merchantRefNum Optional String This is a unique ID number that was Max = 255 created by the merchant and submitted as part of the request.
childAccountNum Optional String This is the child merchant account Max = 10 number, and provided only if the trans- action was processed via a master account.
decision Yes Enumeration This is the status of the transaction. One of the following is returned: • Accepted – the transaction was pro- cessed. • Error – the transaction was attempted, but failed for some rea- son. • Declined – the transaction was declined before it was sent for pro- cessing. • Held – the transaction has been placed on hold due to risk considerations.
code Yes Int This is a numeric code that categorizes the response. See Response codes on page B-1.
actionCode Optional Enumeration This indicates what action the caller should take. Possible values are: • C – Consumer Parameter Error. The consumer has provided incorrect information. Ask the customer to correct the information. • D – Do Not Retry. Further attempts will fail. • M – Merchant Parameter Error. Your application has provided incorrect information. Verify your information. • R – Retry. The problem is tempo- rary. Retrying the request will likely succeed.
description Yes String This is a human readable description Max = 1024 of the code element.
authCode Optional String This is the Authorization code Max = 20 assigned by the issuing bank and returned by Paysafe.
API Reference Guide for Web Services 1.0 3-45 Credit/Debit Card Transactions May 2019
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
avsResponse Optional Enumeration This is the AVS response from the card issuer. Possible values are: • X – Exact. Nine-digit zip code and address match. • Y – Yes. Five-digit zip code and address match. • A – Address matches, but zip code does not. • W – Nine-digit zip code matches, but address does not. • Z – Five-digit zip code matches, but address does not. • N – No part of the address matches. • U – Address information is unavail- able. • R – Retry. System unable to process. • S – AVS not supported. • E – AVS not supported for this industry. • B – AVS not performed. • Q – Unknown response from issuer/banknet switch.
cvdResponse Optional Enumeration This is the response to the cvdValue submitted with the transaction request. Possible values are: • M (Match) – The CVD value pro- vided matches the CVD value asso- ciated with the card. • N (No Match) – The CVD value provided does not match the CVD value associated with the card. • P (Not Processed) – The CVD value was not processed. • Q (Unknown Response) – No results were received concerning the CVD value. • S (Not Present) – CVD should be on the card. However, the cardholder indicated it was not present. • U – Issuer is not certified and/or has not provided Visa encryption keys.
detail tag Optional String This is the tag/value pair returned as Max = 30 part of the detail element. See detail tag/value pairs on page 3-51 for value Optional String details. Max = 1024
txnTime Yes dateTime This is the date and time the transac- tion was processed by Paysafe.
duplicateFound Yes Boolean This indicates if this transaction is a duplicate transaction, if a duplicate check was requested.
3-46 May 2019 Processing the response
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
duplicateTransactionResponse Optional CCTxnRe- If a duplicate record was found, this sponseV1 element contains the details of that record.
tdsResponse acsURL Optional String This is a fully qualified URL to redi- This element and its child ele- Max = 255 rect the consumer to complete the Pay- ments are returned only in ment Authentication Request response to the transaction. ccEnrollmentLookupRequestV1 transaction request.
paymentRequest Optional String This is an encoded Payment Authenti- cation Request generated by the mer- chant authentication processing system (MAPS).
enrollmentStatus Yes Enumeration This indicates whether or not the card- holder is enrolled in 3-D Secure. Possible values are: • Y – Authentication available • N – Cardholder not enrolled • U – Authentication unavailable • E – Error
eci Optional Enumeration Visa/JCB • 05 – Identifies a successfully authenticated transaction. • 06 – Identifies an attempted authen- ticated transaction. • 07 – Identifies a non-authenticated transaction. Mastercard • 01 – Identifies a non-authenticated transaction. • 02 – Identifies a successfully authenticated transaction. If the cardholder is not enrolled in 3D Secure, you can use this E-Commerce Indicator value for the indicator child element of the authentication element in your ccAuthRequestV1 Authorization/Purchase request. However, if the cardholder is enrolled in 3D Secure, use the eci value in the tdsAuthenticateResponse element below.
tdsAuthenticateResponse status Yes Enumeration This indicates the outcome of the This element and its child ele- authentication request. ments are returned only in Possible values are: response to the • Y – Cardholder successfully authen- ccAuthenticateRequestV1 trans- ticated with their Card Issuer. action request. • A – Cardholder authentication was attempted. • N – Cardholder failed to success- fully authenticate with their Card Issuer. • U – Authentication with the Card Issuer was unavailable. • E – Error
API Reference Guide for Web Services 1.0 3-47 Credit/Debit Card Transactions May 2019
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
cavv Optional String This is the Cardholder Authentication Max = 80 Verification Value returned by the card issuer. Use this value for the indicator child element of the authentication element in a ccAuthRequestV1.
signature Yes Enumeration This indicates whether the Verification paymentResponse element that was submitted with the Authentication request passed integrity checks. Possible values are: • Y – All transaction and signature checks satisfied • N – At least one transaction or sig- nature check failed.
xid Optional String This is the transaction identifier Max = 80 returned in response to a ccAuthentica- teRequestV1 Authentication request.
eci Optional Enumeration Use this E-Commerce Indicator value for the indicator child element of the authentication element in your ccAu- thRequestV1 Authorization/Purchase request. Visa/JCB • 05 – Identifies a successfully authenticated transaction. • 06 – Identifies an attempted authen- ticated transaction. • 07 – Identifies a non-authenticated transaction. Mastercard • 01 – Identifies a non-authenticated transaction. • 02 – Identifies a successfully authenticated transaction.
lbCascading Optional This element provides information on transactions that were retried due to load balancing.
retryCount Condi- Int This is the number of times Paysafe tional retried the transaction.
originalCode Condi- Int The original response code returned by tional the system that caused Paysafe to retry the transaction.
addendumResponse Optional This element allows Paysafe to return certain gateway-specific response val- ues to the merchant.
service Condi- String This is the service provider who pro- tional Max = 50 vides the values for the tag/value pair.
detail Condi- There may be multiple detail elements, tional if required.
Child Element of detail
3-48 May 2019 Processing the response
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
tag Condi- String This is the tag/value pair returned as tional Max = 30 part of the addendumResponse. See addendumResponse tag/value pairs on value Condi- String page 3-51 for details. tional Max = 30
amount Optional String This is amount of the transaction Max= request. 999999999.99
tranType Optional Enumeration This is the type of transaction that was NOTE: The tranType element is looked up. Possible values are: returned only in response to a • A – Authorization ccTxnLookupRequestV1. • S – Settlement • P – Purchase • CR – Credit • PY – Payment • N – Independent Credit
cardEnding Optional String This is the last four digits of the card NOTE: The cardEnding ele- Max = 4 associated with this transaction. ment is returned only in response to a ccTxnLookupRe- questV1.
cardExpiry Optional NOTE: The cardExpiry ele- ment is returned only in month Condi- Int This is the month the credit card response to a ccTxnLookupRe- tional Max = 2 expires. questV1. year Condi- Int This is the year the credit card expires. tional Length = 4
netbanxReference Optional String This is a transaction ID that identifies NOTE: The netbanxReference Max = 18 certain legacy transactions. element is returned only in response to a ccTxnLookupRequestV1.
txnLookupResult Condi- This contains all the elements con- NOTE: The txnLookupResult tional tained in the standard ccTxnRespon- element is returned only in seV1 that would have been returned for response to a ccTxnLookupRe- the initial request, in addition to the questV1. elements in this table that are identi- fied as being returned only in response to a ccTxnLookupRequestV1 (e.g., tranType).
profile id Optional String This is an internal ID returned in the Max = 50 response to the profile request, used to identify a customer.
card Condi- tional
Child Element of card
id Condi- String This is the card ID returned by Paysafe tional Max = 50 to identify the profile card.
lastFourDigits Condi- Integer This is the last 4 digits of the card tional number associated with the profile.
API Reference Guide for Web Services 1.0 3-49 Credit/Debit Card Transactions May 2019
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
paymentToken Condi- String This is a token generated by Paysafe tional Max = 50 that represents the card.
purchaseReturnAuthoriza- confirmation- Yes String This is the confirmation number tion Number Max = 15 returned by Paysafe. Note: Purchase Return Authori- zation is performed only if the acquirer/processor supports it. Although the Purchase Return Authorization is performed for all configured accounts, it will be returned in the response only if element with tag INCLUDE_PRA_RESPONSE and value 'true' has been included in the addendumData of the Credit transaction request.
merchantRef- Yes String This is a unique ID number that was Num Max = 255 created by the merchant and submitted as part of the request.
txnTime Yes dateTime This is the date and time the transac- tion was processed by Paysafe.
authCode Optional String This is the Authorization code Max = 20 assigned by the issuing bank and returned by Paysafe.
amount Yes String This is amount of the transaction Max = request 999999999.99
To process the response: 1. Get the response details, which are available via get() methods of the response.
String responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision + " - " + ccTxnResponse.description ; responseTxt += "Details:" + Environment.NewLine; if (ccTxnResponse.detail != null) { for (int i = 0; i < ccTxnResponse.detail.Length; i++) { responseTxt += " - " + ccTxnResponse.detail[i].tag + " - " + ccTxnResponse.detail[i].value + Environment.NewLine; } } responseTxt = responseTxt.Replace("\n", Environment.NewLine); System.Console.WriteLine(responseTxt);
if (DecisionV1.ACCEPTED.Equals(ccTxnResponse.decision)) { System.Console.WriteLine("Transaction Successful."); } else { System.Console.WriteLine("Transaction Failed with decision: " + ccTxnResponse.decision);
3-50 May 2019 detail tag/value pairs
} 2. Process based on the decision element. You would insert handling code appropriate to your applica- tion. You can also look at the code element to provide more fine-grained control for your application. See Response codes on page B-1 for more details.
detail tag/value pairs
Not all processing gateways support all detail tag/value pairs. Contact your account manager for more information.
The following table contains the tag/value pairs supported for the data element. Table 3-13: detail Tag/Value Pairs
Tag Value
CurrencyCode This value is returned if the addendumData tag element of the original transaction was set to SERVICE_REQUEST_CURRENCY. The value will be one of the currency codes in Table 3-15: Currency Codes on page 3-51.
BalanceResponse This value is the balance remaining on a gift card, if a gift card was used for the original transaction. Note that decimal is implied for currency, so, for example, “16500” in dollars = $165.00.
addendumResponse tag/value pairs
Not all processing gateways support all addendumResponse tag/value pairs. Contact your account manager for more information.
The following table contains the tag/value pairs supported for the addendumResponse element. Table 3-14: addendumResponse Tag/Value Pairs
Tag Service Value
BATCH_NUMBER DJN This is your batch number.
EFFECTIVE_DATE DJN This is the date of the bank deposit associated with the transaction. Format = YYMMDD
SEQ_NUMBER DJN This is your sequence number.
TERMINAL_ID DJN This is your terminal ID.
Currency codes Table 3-15: Currency Codes
Code Currency
ARS Argentine Peso
AUD Australian Dollar
API Reference Guide for Web Services 1.0 3-51 Credit/Debit Card Transactions May 2019
Table 3-15: Currency Codes (Continued)
Code Currency
BGN Bulgarian Lev
BRL Brazilian Real
CAD Canadian Dollar
CHF Swiss Franc
CZK Czech Koruna
DKK Danish Krone
EUR Euro
GBP Pound Sterling
HKD Hong Kong Dollar
HUF Forint
ILS New Israeli Sheqel
ISK Iceland Krona
JPY Yen
MXN Mexican Peso
NOK Norwegian Krone
NZD New Zealand Dollar
PLN Zloty
RON New Leu
SEK Swedish Krona
SGD Singapore Dollar
THB Baht
TWD New Taiwan Dollar
USD US Dollar
ZAR Rand
3-52 CHAPTER 4
Information Lookup Service Transactions
Introduction The Information Lookup Service (ILS) operation allows you to run a report through the API over a date range you specify to return data on Authorizations, Settlements, Credits, and Chargebacks processed through a merchant account. You can use the type element to combine one or more transaction types in a single request. See Table 4-1: ilsLookupRequestV1 Elements on page 4-5 for more information on the type element. This chapter describes how to process the ILS operation via the Paysafe Web Service. • The ILS operation accepts an ilsLookupRequestV1 document object. • The ILS operation returns an ilsLookupResponseV1 response.
The maximum range for most ILS requests is 24 hours.
Paysafe ILS WSDLs and links WSDL: https://webservices.optimalpayments.com/ilsWS/IlsService/v1?wsdl Web Service: https://webservices.optimalpayments.com/ilsWS/IlsService/v1 HTTP Post: https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1
API Reference Guide for Web Services 1.0 4-1 Information Lookup Service Transactions May 2019
.NET example
To build the .NET example: 1. Create a new project.
2. Add a Web Reference.
4-2 May 2019 Building ILS requests
3. Enter the WSDL URL and click the Add Reference button.
The Web client is now built.
4. Build the request and process response. See Building ILS requests on page 4-3.
Building ILS requests ILS requests require the ilsLookupRequestV1 document object. This section describes the structure of an ilsLookupRequestV1 and how to construct one. See Table 4-1: ilsLookupRequestV1 Elements on page 4-5 for details on the elements required.
ILS – C# The following is an ILS example in C#:
//Prepare the call to the Credit Card Web Service ILSLookupRequestV1 ilsLookupRequest = new ILSLookupRequestV1(); MerchantAccountV1 merchantAccount = new MerchantAccountV1(); merchantAccount.accountNum = "12345678"; merchantAccount.storeID = "myStoreID"; merchantAccount.storePwd = "myStorePWD";
API Reference Guide for Web Services 1.0 4-3 Information Lookup Service Transactions May 2019
DateV1 startDate = new DateV1(); startDate.year = 2008; startDate.month = 11; startDate.day = 3; startDate.hour = 0; startDate.minute = 0; startDate.second = 0;
DateV1 endDate = new DateV1(); endDate.year = 2008; endDate.month = 11; endDate.day = 3; endDate.hour = 14; endDate.minute = 40; endDate.second = 59;
RequestTypeV1[] txnTypes = new RequestTypeV1[1]; txnTypes[0] = RequestTypeV1.settlements;
IlsLookupRequestV1 req = new IlsLookupRequestV1(); req.merchantAccount = merchantAccount; req.startDate = startDate; req.endDate = endDate; req.type = txnTypes;
System.Console.WriteLine("Sending request...");
IlsServiceV1 ilsService = new IlsServiceV1(); IlsLookupResponseV1 response = null;
response = ilsService.ilsLookup( req );
System.Console.WriteLine("Response received: "); String responseTxt = "";
if( response != null ) { responseTxt += "Decision: " + response.decision + Environment.NewLine; responseTxt += "Description: " + response.description + Environment.NewLine;
if( response.decision == DecisionV1.ACCEPTED ) { responseTxt += "Authorizations: " + response.transactions.authorizations + Environment.NewLine; responseTxt += "Settlements: " + response.transactions.settlements + Environment.NewLine; responseTxt += "Chargebacks: " + response.transactions.chargebacks + Environment.NewLine; responseTxt += "Credits: " + response.transactions.credits + Environment.NewLine; } }
System.Console.WriteLine( responseTxt );
4-4 May 2019 ilsLookupRequestV1 schema
ilsLookupRequestV1 schema An ilsLookupRequestV1 has the following structure:
ilsLookupRequestV1 elements The ilsLookupRequestV1 document object contains the following elements: Table 4-1: ilsLookupRequestV1 Elements
Element Child Required Type Description Element
merchantAccount accountNum Yes String This is the merchant account number. Max = 10
storeID Yes String This is the Paysafe store identifier, used to authenti- Max = 80 cate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes String This is the Paysafe store password, used to authenti- Max = 20 cate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
startDate year Yes Int This is the year set for the search start. Max = 9999
API Reference Guide for Web Services 1.0 4-5 Information Lookup Service Transactions May 2019
Table 4-1: ilsLookupRequestV1 Elements (Continued)
Element Child Required Type Description Element
month Yes Int This is the month set for the search start. Min = 1 Max = 12
day Yes Int This is the day set for the search start. Min = 1 Max = 31
hour Yes Int This is the hour set for the search start. Min = 0 Max = 23
minute Yes Int This is the minute set for the search start. Min = 0 Max = 59
second Yes Int This is the second set for the search start. Min = 0 Max = 59
endDate year Yes Int This is the year set for the search end. Max = 9999
month Yes Int This is the month set for the search end. Min = 1 Max = 12
day Yes Int This is the day set for the search end. Min = 1 Max = 31
hour Yes Int This is the hour set for the search end. Min = 0 Max = 23
minute Yes Int This is the minute set for the search end. Min = 0 Max = 59
second Yes Int This is the second set for the search end. Min = 0 Max = 59
4-6 May 2019 ilsLookupRequestV1 elements
Table 4-1: ilsLookupRequestV1 Elements (Continued)
Element Child Required Type Description Element
type Yes Enumeration This is the type of transaction for which you are look- ing for data. Possible values are: • authorizations • settlements • credits • chargebacks • dd-charge • dd-credit • dd-charge-bacs (returns mandateReference ele- ment) • dd-credit-bacs (returns mandateReference element) • dd-mandate-bacs (returns mandateReference and effectiveDate elements)
ccOptions Optional Enumeration For internal use only.
ddOptions Optional
dateType Optional Enumeration This specifies the nature of the transaction status that will searched for. • initiation – The search will be conducted on all checks that were presented during the time period specified. If the dateType is not specified, this is the default setting. • status_change – The search will be conducted on all checks whose status changed during the time period specified.
status Optional Enumeration The lookup request will return only those transactions with the status specified here. When combined with a status_change element, only those records that had the specified status during that date range are returned. If this element is not specified then transactions of all statuses are returned. Possible values are: • Presented • Represented • Returned • Pending Customer Approval • Pending • Active • Declined • Cancelled • Failed • Cleared
The maximum range for an ILS request is 24 hours.
API Reference Guide for Web Services 1.0 4-7 Information Lookup Service Transactions May 2019
Processing the response The following is an example of a typical ilsLookupResponseV1 for a successful transaction. See Table 4-2: ilsLookupResponseV1 Elements on page 4-9 for a description of the parameters returned.
authorizations
settlements
credits
chargebacks
4-8 May 2019 ilsLookupResponseV1 schema
The following is an example of a typical ilsLookupResponseV1 for a rejected transaction. In this example, an invalid merchant ID or password was submitted.
ilsLookupResponseV1 schema An ilsLookupResponseV1 has the following structure:
The following elements are relevant for an ilsLookupResponseV1: Table 4-2: ilsLookupResponseV1 Elements
Element Child Element Required Type Description
decision Yes Enumeration This is the status of the transaction. One of the following is returned: • Accepted – the transaction was pro- cessed. • Error – the transaction was attempted, but failed for some reason. • Rejected – the request was rejected, e.g., due to invalid merchant creden- tials.
description Yes String If the decision returned is Error or Max = 1024 Rejected, this is a description of the error.
merchantAccount Yes String This is the merchant account number. Max = 10
currency Yes String This is the currency of the merchant Length = 3 account.
API Reference Guide for Web Services 1.0 4-9 Information Lookup Service Transactions May 2019
Table 4-2: ilsLookupResponseV1 Elements (Continued)
Element Child Element Required Type Description
startDate year Yes Int This is the year set for the search start Max = 9999 date.
month Yes Int This is the month set for the search start Min = 1 date. Max = 12
day Yes Int This is the day set for the search start Min = 1 date. Max = 31
hour Yes Int This is the hour set for the search start Min = 0 date. Max = 23
minute Yes Int This is the minute set for the search start Min = 0 date. Max = 59
second Yes Int This is the second set for the search start Min = 0 date. Max = 59
endDate year Yes Int This is the year set for the search end Max = 9999 date.
month Yes Int This is the month set for the search end Min = 1 date. Max = 12
day Yes Int This is the day set for the search end date. Min = 1 Max = 31
hour Yes Int This is the hour set for the search end Min = 0 date. Max = 23
minute Yes Int This is the minute set for the search end Min = 0 date. Max = 59
second Yes Int This is the second set for the search end Min = 0 date. Max = 59
4-10 May 2019 ilsLookupResponseV1 schema
Table 4-2: ilsLookupResponseV1 Elements (Continued)
Element Child Element Required Type Description
txnType code Yes String This is the type of transaction for which you searched for data. Possible values are: • authorizations • settlements • credits • chargebacks • dd-charge • dd-credit • dd-charge-bacs (includes mandateReference element) • dd-credit-bacs (includes mandateReference element) • dd-mandate-bacs (includes mandateReference and effectiveDate elements)
count Yes Int This is the number of the transaction type returned in the code element above. Each code element returned has its own count.
transactions Optional
Attribute of transactions
childFma Conditional String This is the child merchant account num- Max = 10 ber, and provided only if the account pro- vided for the merchantAccount element is a master account.
authorizations Optional String Each instance of authorizations contains further details. See Authorizations response details on page 4-12 for a description.
settlements Optional String Each instance of settlements contains fur- ther details. See Settlements response details on page 4-12 for a description.
credits Optional String Each instance of credits contains further details. See Credits response details on page 4-13 for a description.
chargebacks Optional String Each instance of chargebacks contains further details. See Chargebacks response details on page 4-13 for a description.
dd-charge Optional String Each instance of dd-charge, dd-credit, dd-charge-bacs, dd-credit-bacs, and dd- dd-credit Optional String mandate-bacs contains further details. See Direct Debit response details on page dd-charge-bacs Optional String 4-14 for a description.
dd-credit-bacs Optional String
dd-mandate-bacs Optional String
API Reference Guide for Web Services 1.0 4-11 Information Lookup Service Transactions May 2019
Response element contents Paysafe may without warning, when necessary, add additional detail elements to each of the transaction response types documented below (authorizations, settlements, credits, and chargebacks). These additional detail elements will be added at the end of the current pipe-separated element list, as in the example below.
It is the merchant’s responsibility to ensure that their integration for the ilsLookupRequestV1 is not adversely affected by the addition of extra detail elements by Paysafe.
Authorizations response details The following details may returned for authorizations: Table 4-3: Authorizations Response Details
Parameter Description
Record Sequence This is the confirmation number assigned by Paysafe to the transaction.
Authorization Status This is the status of the Authorization. Possible values are: • A – Authorized • FS – Fully Settled • AS – Partially Settled
Transaction Date/Time This is the date and time the Authorization was processed.
Merchant Transaction ID This is the transaction ID assigned by the merchant to the Authorization.
Amount This is the amount of the Authorization.
Settlements response details The following details may be returned for settlements: Table 4-4: Settlements Response Details
Parameter Description
Record Sequence This is the confirmation number assigned by Paysafe to the transaction.
4-12 May 2019 Response element contents
Table 4-4: Settlements Response Details (Continued)
Parameter Description
Settlement Status This is the current status of the Settlement transaction. Possible values are: • B – Batched • E – Error • P – Pending • C – Complete • K – Cancelled • HO – Hold • DE – Declined • MI – Manual
Transaction Date/Time This is the date and time the Settlement was processed.
Merchant Transaction ID This is the transaction ID assigned by the merchant to the Settlement.
Amount This is the amount of the Settlement.
Credits response details The following details may be returned for credits: Table 4-5: Credits Response Details
Parameter Description
Record Sequence This is the confirmation number assigned by Paysafe to the transaction.
Credit Status This is the status of the Settlement that is being credited. Possible values are: • B – Batched • E – Error • P – Pending • C – Complete • K – Cancelled • HO – Hold • DE – Declined • MI – Manual
Transaction Date/Time This is the date and time the Credit was processed.
Merchant Transaction ID This is the transaction ID assigned by the merchant to the Credit.
Amount This is the amount of the Credit.
Settlement Record Sequence This the confirmation number originally assigned to the Settlement that was credited.
Chargebacks response details The following details may be returned for chargebacks: Table 4-6: Chargebacks Response Details
Parameter Description
Chargeback ID This is the Record ID in our Dispute Management system. Each chargeback has a unique Record ID to identify it.
Authorization Transaction ID This is the transaction ID assigned by Paysafe to the original Authorization.
Authorization Merchant Transaction ID This is the transaction ID assigned by the merchant to the original Authorization.
API Reference Guide for Web Services 1.0 4-13 Information Lookup Service Transactions May 2019
Table 4-6: Chargebacks Response Details (Continued)
Parameter Description
Settlement Merchant Transaction ID This is the transaction ID assigned by the merchant to the Settlement that was charged back.
Card Ending This is the last 4 digits of the credit card used for the original Authorization.
Original Settlement Date This is the date of the Settlement of the original Authorization. Format = yyyy-mm-dd
Original Settlement Amount This is the amount that was settled against the original Authorization.
Currency Code This is the currency of the merchant account.
Chargeback Amount This is the amount that is being charged back against the Settlement.
Reason Code This is the reason the transaction was charged back. See Reason codes on page 4-16 for an explanation of the codes.
ARN This is the Acquirer’s Reference Number, a unique identification reference number assigned to each settlement transaction by the acquirer.
Original Authorization Code This is the authorization code assigned by the issuing bank and returned by Paysafe if the transaction was process via the Direct Payment protocol.
CBTY Code This is the type of chargeback. Possible values are: • 1 – Chargeback • 2 – Chargeback Reversal • C – Risk Only Notice • D – Denied/Lost Representment • RET – Retrieval Request
Disputed Flag This flag indicates whether a transaction is being disputed. Possible values are: • Null • Yes
FMA Posting Date This is the date the chargeback was posted to the merchant account. Format = yyyy-mm-dd
Direct Debit response details The following details may be returned for Direct Debit transactions: Table 4-7: Direct Debit Response Details
Parameter Description
Echeck ID This is the confirmation number assigned by Paysafe to the transaction.
4-14 May 2019 Response element contents
Table 4-7: Direct Debit Response Details (Continued)
Parameter Description
Echeck Status This is the current status of the Direct Debit transaction. Possible values are: • AP – Approved mandate • C – Complete batch • CL – Cleared transaction • DE – Declined • E – Error batch • F – Failed • PR1 – Presented 1 • PR2 – Presented 2 • RE – Rejected • REF – Rejected final • RF – Refunded • RV – Reversed • W – Waiting to be batched • X – Cancelled
Presentation Date This is the date and time the transaction was processed.
Merchant Transaction ID This is the transaction ID assigned by the merchant to the transaction.
Amount This is the amount of the transaction. This value will be 0.0 when the txnType was set to dd-man- date-bacs.
Filtered Status When the dateType child element of ddOptions is set to “initiation” (default), this value is the same as the Echeck Status value, above in this table. When the dateType child element of ddOptions is set to “status_change”, this is the status that was used for the search. Here are the statuses returned in each of the search scenarios. Presented • C Represented • PR1 • PR2 Returned • RE • REF
Latest Status Update Time This is the date and time of the latest status update.
Return Code This is the return code if the mandate or transaction has been returned by the banking network. NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.
Bank Reference This is the full reference used to send to the banking network. • For dd-mandate-bacs, this will be the 10-character mandateReference. • For dd-charge-bacs, this will be 18 characters comprising the 10-character mandateReference and 8 characters for the echeck ID of the transaction (charge). NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.
Effective Date This is returned for dd-mandate-bacs requests only. It is the date the mandate will become active with the bank. Transactions may not be requested against this mandate before the effective date. Once the mandate becomes active, the value returned for this field will be null. NOTE: This field is returned only for dd-charge-bacs, dd-credit-bacs, and dd-mandate-bacs.
API Reference Guide for Web Services 1.0 4-15 Information Lookup Service Transactions May 2019
Reason codes
Chargeback reason codes One of the following chargeback reason codes may be returned with a chargebacks response: Table 4-8: Visa/MasterCard Chargeback Reason Codes
Card Code Description Brand
MC 01 Requested Transaction Data Not Received
MC 02 Requested item illegible
MC 07 Warning Bulletin File
MC 08 Requested/Required Authorization Not Obtained
MC 12 Account Number Not on File
VI 30 Services Not Provided or Merchandise Not Received
MC 31 Transaction Amount Differs
MC 34 Duplicate Processing
MC 35 Card Not Valid or Expired
MC 37 Fraudulent Mail/Phone Order Transaction
MC 40 Fraudulent Processing of Transaction
MC 41 Canceled Recurring Transaction
VI 41 Canceled Recurring Transaction
MC 42 Late Presentment
MC 47 Exceeds Floor Limit, Not Authorized, and Fraudulent Transaction
MC 49 Questionable Merchant Activity
MC 50 Credit Posted as a Debit
MC 53 Cardholder Dispute Defective/Not as Described
VI 53 Not as Described/Defective Merchandise
MC 54 Cardholder Dispute - Not Elsewhere classified (US Only)
MC 55 Non-Receipt of Merchandise
VI 57 Fraudulent Multiple Transactions
MC 59 Services Not Rendered
MC 60 Credit Not Processed
VI 60 Requested Copy Illegible
MC 62 Counterfeit Transaction Magnetic Stripe POS Fraud
VI 62 Counterfeit Transaction
4-16 May 2019 Retrieval request reason codes
Table 4-8: Visa/MasterCard Chargeback Reason Codes (Continued)
Card Code Description Brand
MC 63 Cardholder Does Not Recognize – Potential Fraud
VI 71 Authorization Request Declined/Declined Authorization
VI 72 No Authorization / Transaction Exceeds Floor Limit
VI 73 Expired Card
VI 74 Late Presentment
VI 75 Cardholder Does Not Recognize the Transaction
VI 76 Incorrect Transaction Code
VI 77 Non-Matching Account Number
VI 79 Requested Transaction Information Not Received
VI 80 Incorrect transaction amount or account number
VI 81 Fraudulent transaction – Card Present Environment
VI 82 Duplicate Processing
VI 83 Fraudulent Transaction – Card Absent Environment
VI 85 Credit Not Processed
VI 86 Paid by Other Means
Retrieval request reason codes One of the following retrieval request reason codes may be returned with a chargebacks response: Table 4-9: Visa/MasterCard Retrieval Request Reason Codes
Card Code Description Brand
MC 05 Chargeback Support – Card Holder Does Not Agree with Amount Billed
MC 21 Cardholder Inquiry – Does Not Recognize Transaction (Merchant Name, City, State or Date)
MC 22 Cardholder Inquiry – Disagrees With Billing
MC 23 Cardholder Inquiry – Needs for Personal Records
MC 24 Cardholder Inquiry – No Reason Code
VI 28 Cardholder Requests Copy Bearing Signature
VI 29 Request for T&E Documents
VI 30 Cardholder Dispute, Cardholder Request Draft
VI 33 Legal Process or Fraud Analysis
VI 34 Repeat Request for Copy
API Reference Guide for Web Services 1.0 4-17 Information Lookup Service Transactions May 2019
Table 4-9: Visa/MasterCard Retrieval Request Reason Codes (Continued)
Card Code Description Brand
MC 41 Legal/Fraud Analysis – Signature Verification
MC 42 Potential Chargeback or Compliance Documentation
MC 43 Legal/Fraud – Imprint Verification
Discover chargeback and retrieval request reason codes One of the following chargeback or retrieval request reason codes may be returned with a chargebacks response: Table 4-10: Discover Chargeback and Retrieval Request Codes
Code Description
AL Cardholder challenges the validity of an airline card sale.
AP Cardholder challenges the validity of multiple recurring payments card sales after expiration or cancel- lation of the recurring payments plan agreement.
AW Incorrect transaction amount or account number/transaction amount differs.
CA Cardholder challenges the validity of a cash advance or cash over transaction, other than a Discover ATM transaction.
CD Cardholder challenges the validity of a card transaction because the transaction should have resulted in a credit rather than a card sale.
RG Cardholder challenges the validity of a card sale due to non-receipt of goods and/or services.
UA11 Swiped card transaction – No cardholder signature obtained.
UA12 Swiped card transaction – Invalid cardholder signature obtained.
UA18 Swiped card transaction – Illegible copy of transaction receipt.
UA21 Keyed card transaction – No cardholder signature obtained.
UA22 Keyed card transaction – Invalid cardholder signature obtained.
UA23 Keyed card transaction – Invalid card imprint.
UA28 Keyed card transaction – Illegible copy of transaction documentation.
RN1, Cardholder alleges that an expected credit from the merchant was not received or was insufficient in RN2 amount.
DP Cardholder alleges that a single card sale was posted more than once to the cardholder’s account.
RM Cardholder challenges the validity of a card sale because the goods or services delivered by the mer- chant were not of the quality or condition agreed upon.
NA Issuer disputes a card sale because the merchant did not obtain a positive authorization response for the amount of the card transaction that is subject to dispute, as represented in sales data.
UA01 Cardholder or issuer challenges the validity of a card sale because no authorization request was attempted by the merchant.
CR Cardholder challenges the validity of a card transaction because the cardholder cancelled the underlying reservation with the merchant.
4-18 May 2019 Discover chargeback and retrieval request reason codes
Table 4-10: Discover Chargeback and Retrieval Request Codes (Continued)
Code Description
NC Cardholder challenges the validity of a card sale and no other reason code applies.
DA Issuer challenges the validity of a card sale because the merchant received a declined authorization response and the issuer cannot collect the card sale amount from the cardholder.
EX Cardholder or issuer challenges the validity of a card sale because the card had expired on or before the card transaction date and the merchant did not obtain a positive authorization response.
IC Cardholder or issuer disputes a card sale because the transaction documentation received in response to a ticket retrieval request is either illegible or is missing a valid, legible card imprint (if required).
IN Issuer disputes a card transaction because the card number provided by the merchant is not valid.
IS Cardholder or issuer disputes a card sale because transaction documentation received in response to a ticket retrieval request does not include a valid, legible cardholder signature where required for the card transaction.
LP Cardholder or issuer disputes a card sale because the acquirer or merchant submitted sales data for the card sale more than 30 calendar days after the authorization request and the card sale was not for a delayed delivery card sale.
SV Cardholder or issuer disputes a prepaid gift card transaction because the merchant did not obtain a pos- itive authorization response for the amount of the card sale subject to dispute.
TF Discover initiates a chargeback of a card transaction because the acquirer or merchant did not comply with the applicable operating regulations.
UA10 Request transaction receipt for swiped card transaction.
UA20 Request transaction documentation for keyed card transaction.
UA30 Request transaction documentation for card not present card transaction.
UA31 Card not present card transaction – Invalid proof of delivery obtained by acquirer or merchant.
UA38 Card Not present card transaction – Illegible copy of transaction documentation.
UA02 Cardholder or issuer challenges the validity of a card sale because the issuer provided a declined autho- rization response.
UA03 Cardholder or issuer challenges the validity of a card sale because the amount billed to the cardholder exceeds amount authorized by the issuer.
UA32 Cardholder or issuer challenges the validity of a card not present card transaction because the acquirer or merchant did not obtain address verification or did not obtain and submit the CID with the authori- zation request.
UA99 Cardholder or issuer challenges the validity of a card sale and the acquirer or merchant did not comply with the applicable operating regulations in connection with the card sale.
R2 Credit not processed.
A Cardholder dispute, cardholder request draft.
API Reference Guide for Web Services 1.0 4-19 Information Lookup Service Transactions May 2019
4-20 APPENDIX A
Using the HTTP Post Method
Introduction In addition to a standard Web Service–based call, you can also use the HTTP Post method to post transac- tion requests to Paysafe. Note that the URLs in the examples below point to the Paysafe Production environment. In order to test your integration, please contact Technical Support to obtain Test URLs and Test merchant account param- eters. • Email [email protected] • Telephone 1-888-709-8753
All transactions sent using the HTTP Post method must be URL encoded using the application/x-www-form-urlencoded format. Otherwise, they run the risk of failing because any reserved characters (e.g., slashes, ampersands, etc.) are stripped from requests that are not properly URL encoded.
Direct Debit requests
charge/credit For more information on these request types, see Building charge or credit requests on page 2-3.
To send a charge or credit request via HTTP Post: 1. Create a transaction request like the following example:
API Reference Guide for Web Services 1.0 A-1 Using the HTTP Post Method May 2019
See Table 2-2: ddCheckRequestV1 Elements on page 2-6 for a list and description of param- eters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – charge on page A-2). This HTTP Post must include two parameters: • txnMode – charge or credit • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – charge This example shows a form version of a charge/credit request – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
API Reference Guide for Web Services 1.0 A-3 Using the HTTP Post Method May 2019
updateShippingInfo For more information on this request type, see Building updateShippingInfo requests on page 2-12.
To send an updateShippingInfo request via HTTP Post: 1. Create a transaction request like the following example:
See Table 2-4: ddShippingRequestV1 Elements on page 2-14 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – updateShippingInfo on page A-4). This HTTP Post must include two parameters: • txnMode – updateShippingInfo • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – updateShippingInfo This example shows a form version of an updateShippingInfo request – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
API Reference Guide for Web Services 1.0 A-5 Using the HTTP Post Method May 2019
ddLookupRequest For more information on this request type, see Building lookup requests on page 2-16.
To send a ddLookupRequest via HTTP Post: 1. Create a transaction request like the following example:
See Table 2-5: ddLookupRequestV1 Elements on page 2-18 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – lookupRequest on page A-6). This HTTP Post must include two parameters: • txnMode – lookup • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – lookupRequest This example shows a form version of a lookupRequest – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Mandate request For more information on this request type, see Building BACS mandate requests (UK) on page 2-19.
To send a mandate request via HTTP Post: 1. Create a transaction request like the following example:
API Reference Guide for Web Services 1.0 A-7 Using the HTTP Post Method May 2019
See Table 2-6: ddMandateRequestV1 Elements on page 2-23 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – mandate request on page A-8). This HTTP Post must include two parameters: • txnMode – mandate • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – mandate request This example shows a form version of a mandate request – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Change status request For more information on this request type, see Building change status requests on page 2-25.
To send a change status request via HTTP Post: 1. Create a transaction request like the following example:
See Table 2-8: ddChangeStatusRequestV1 Elements on page 2-27 for a list and description of parameters to include in this request.
API Reference Guide for Web Services 1.0 A-9 Using the HTTP Post Method May 2019
2. Include this transaction request in an HTTP Post (see HTML example – change status request on page A-10). This HTTP Post must include two parameters: • txnMode – changeStatus • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – change status request This example shows a form version of a change status request – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Mandate update request For more information on this request type, see Building mandate update requests on page 2-28.
A-10 May 2019 Mandate update request
To send a mandate update request via HTTP Post: 1. Create a transaction request like the following example:
See Table 2-9: ddUpdateMandateRequestV1 Elements on page 2-30 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – mandate update request on page A-11). This HTTP Post must include two parameters: • txnMode – updateMandate • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1
HTML example – mandate update request This example shows a form version of a mandate update request – containing the example above – that you could post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Credit card requests
Purchase/Authorization/Verification For more information on these request types, see Building Purchase/Authorization/Verification requests on page 3-4.
To send a credit card Purchase/Authorization/Verification transaction request via HTTP Post: 1. Create a transaction request like the following example:
A-12 May 2019 Purchase/Authorization/Verification
See Table 3-2: ccAuthRequestV1 Elements on page 3-8 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Authorization on page A-13). This HTTP Post must include two parameters: • txnMode – ccAuthorize, ccPurchase, or ccVerification • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Authorization This example shows a form version of a credit card Authorization request – containing the example above – that you could post to Paysafe.
To make this a Purchase or Verification request, just modify the txnMode value “ccAuthorize” – in the line “” below – to “ccPurchase” or “ccVerification”, respectively.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Authorization Reversal For more information on these request types, see Building Authorization Reversal requests on page 3-17.
To send a credit card Authorization Reversal transaction request via HTTP Post: 1. Create a transaction request like the following example:
See Table 3-4: ccAuthReversalRequestV1 Elements on page 3-19 for a list and description of parame- ters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Authorization Reversal on page A-15). This HTTP Post must include two parameters: • txnMode – ccAuthorizeReversal • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Authorization Reversal This example shows a form version of a credit card Authorization Reversal request – containing the exam- ple above – that you could post to Paysafe.
API Reference Guide for Web Services 1.0 A-15 Using the HTTP Post Method May 2019
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Settlement/Credit For more information on these request types, see Building Settlement/Credit requests on page 3-20.
To send a credit card Settlement/Credit transaction request via HTTP Post: 1. Create a transaction request like the following example:
A-16 May 2019 Settlement/Credit
See Table 3-5: ccPostAuthRequestV1 Elements on page 3-22 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Settlement on page A-17). This HTTP Post must include two parameters: • txnMode – ccSettlement or ccCredit • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Settlement This example shows a form version of a credit card Settlement request – containing the example above – that you could post to Paysafe.
To make this a Credit request, just modify the txnMode value “ccSettlement” – in the line “” below – to “ccCredit”.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Stored Data Authorization/Purchase For more information on these request types, see Building Stored Data Requests on page 3-23.
To send a Stored Data Authorization/Purchase transaction request via HTTP Post: 1. Create a transaction request like the following example:
See Table 3-6: ccStoredDataRequestV1 Elements on page 3-25 or a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Stored Data Authorization on page A-18). This HTTP Post must include two parameters: • txnMode – ccStoredDataAuthorize or ccStoredDataPurchase • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Stored Data Authorization This example shows a form version of a credit card Stored Data Authorization request – containing the example above – that you could post to Paysafe.
A-18 May 2019 Cancel Settle/Credit/Payment/Independent Credit
To make this a Stored Data Purchase request, just modify the txnMode value “ccStoredDataAuthorize” – in the line “” below – to “ccStoredDataPurchase”.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Cancel Settle/Credit/Payment/Independent Credit For more information on these request types, see Building Cancel requests on page 3-27.
To cancel a credit card Settle/Credit/Payment/Independent Credit request via HTTP Post: 1. Create a transaction request like the following example:
API Reference Guide for Web Services 1.0 A-19 Using the HTTP Post Method May 2019
See Table 3-7: ccCancelRequestV1 Elements on page 3-28 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Cancel on page A-20). This HTTP Post must include two parameters: • txnMode – ccCancelSettle, ccCancelCredit, ccCancelPayment, or ccCancelIndependentCredit • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Cancel This example shows a form version of a credit card Cancel request – containing the example above – that you could post to Paysafe to cancel a Settle transaction.
To make this a Cancel Credit, Cancel Payment, or Cancel Independent Credit request, just modify the txnMode value “ccCancelSettle” – in the line “” below – to “ccCancelCredit”, “ccCancelPayment”, or “ccCancelIndependentCredit”, respectively.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Payment request For more information on this request type, see Building Payment/Independent Credit requests on page 3-29.
To make a Payment request via HTTP Post: 1. Create a transaction request like the following example:
See Table 3-8: ccPaymentRequestV1 Elements on page 3-32 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Payment on page A-22). This HTTP Post must include two parameters: • txnMode – ccPayment or ccIndependentCredit • txnRequest – the transaction request above
API Reference Guide for Web Services 1.0 A-21 Using the HTTP Post Method May 2019
3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Payment This example shows a form version of a credit card Payment request – containing the example above – that you could post to Paysafe.
To make this an Indpendent Credit request, just modify the txnMode value “ccPayment” – in the line “” below – to “ccIndependent Credit”.
Credit Card Webservice Tester
A-22 May 2019 Credit card Information Lookup
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Sample HTTP Post on page A-29 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Credit card Information Lookup For more information on this request type, see Building Transaction Lookup requests on page 3-34.
To send a credit card Information Lookup transaction request via HTTP Post: 1. Create a transaction request like the following example:
See Table 3-9: ccTxnLookupRequestV1 Elements on page 3-36 for a list and description of parameters to include in this request.
2. Include this transaction request in an HTTP Post (see HTML example – Information Lookup on page A-24). This HTTP Post must include two parameters: • txnMode – ccTxnLookup • txnRequest – the transaction request above 3. Send the HTTP Post to the following URL: https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
API Reference Guide for Web Services 1.0 A-23 Using the HTTP Post Method May 2019
HTML example – Information Lookup