api reference guide for web servicessupport.netbanx.com/repository/webservices_api_1.0.pdf · web...
TRANSCRIPT
API Reference Guidefor Web Services
May 2019
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 transferred 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 Paysafe Holdings UK Limited – www.paysafe.com
Contents
1 Paysafe Web ServicesWhat are Paysafe Web Services?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Web Services supported for Direct Debit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Web Services supported for credit cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Web Services supported for Information Lookup Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Accessing the Paysafe WSDLs and links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Direct Debit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Credit card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Information Lookup Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Testing Paysafe Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
AVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4CVD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Negative database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-63D Secure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Using this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
2 Direct Debit TransactionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1.NET example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Building charge or credit requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
charge example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3ddCheckRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5ddCheckRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Special considerations for Direct Debit elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11Building updateShippingInfo requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
updateShippingInfo example – C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12ddShippingRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14ddShippingRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Building lookup requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16Lookup example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16ddLookupRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18ddLookupRequestV1 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-20mandate example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20ddMandateRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22ddMandateRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Building change status requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25Change status example – C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26ddChangeStatusRequest schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27ddChangeStatusRequestV1 elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Building mandate update requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28Mandate update example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28ddUpdateMandateRequestV1 schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29ddUpdateMandateRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
3 Credit/Debit Card TransactionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1.NET example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Building Purchase/Authorization/Verification requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Purchase example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5ccAuthRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7ccAuthRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8addendumData tag/value pairs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Building Authorization Reversal requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Authorization Reversal example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18ccAuthReversalRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19ccAuthReversalRequestV1 elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
Building Settlement/Credit requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21Settlement example – C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21ccPostAuthRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22ccPostAuthRequestV1 elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Building Stored Data Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25Stored Data Authorization example – C#. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25ccStoredDataRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26ccStoredDataRequestV1 elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27
Building Cancel requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28Cancel Settle example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28ccCancelRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29ccCancelRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Building Payment/Independent Credit requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31Payment example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31ccPaymentRequestV1 schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33ccPaymentRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Building Transaction Lookup requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36Transaction Lookup example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36ccTxnLookupRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38
IV
May 2019
ccTxnLookupRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38Building Enrollment Lookup requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
Enrollment Lookup example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40ccEnrollmentLookupRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-41ccEnrollmentLookupRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-41
Building Authentication requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43Authentication example – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43ccAuthenticateRequestV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-44ccAuthenticateRequestV1 elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-44
Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46detail tag/value pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53addendumResponse tag/value pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53Currency codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53
4 Information Lookup Service TransactionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Paysafe ILS WSDLs and links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1.NET example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Building ILS requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
ILS – C# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3ilsLookupRequestV1 schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5ilsLookupRequestV1 elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Processing the response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8ilsLookupResponseV1 schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Response element contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Authorizations response details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Settlements response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Credits response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Chargebacks response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Direct Debit response details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Chargeback reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16Retrieval request reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Discover chargeback and retrieval request reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
A Using the HTTP Post MethodIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1Direct Debit requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
charge/credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1HTML example – charge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
updateShippingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4HTML example – updateShippingInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
ddLookupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6HTML example – lookupRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
API Reference Guide for Web Services 1.0 V
May 2019
Mandate request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7HTML example – mandate request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Change status request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9HTML example – change status request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Mandate update request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10HTML example – mandate update request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Credit card requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12Purchase/Authorization/Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
HTML example – Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13Authorization Reversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15
HTML example – Authorization Reversal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16Settlement/Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17
HTML example – Settlement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17Stored Data Authorization/Purchase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18
HTML example – Stored Data Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19Cancel Settle/Credit/Payment/Independent Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20
HTML example – Cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20Payment request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-21
HTML example – Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-22Credit card Information Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-23
HTML example – Information Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24Enrollment Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-25
HTML example – Enrollment Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27
HTML example – Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-28Information Lookup Service requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-28
HTML example - ILS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-29Sample HTTP Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
Sample HTTP Post responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
B Response CodesOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Response codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1Action codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20Return codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21
C Geographical CodesProvince codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1State codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2Country 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 collection 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 lan-guage.
• 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 DebitPaysafe 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 permits you to transfer money from the customer’s bank account to your merchant account. The banking 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 cardsPaysafe currently supports the following Web Services for credit cards:
Web Services supported for Information Lookup ServicePaysafe currently supports the following Web Service:
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 with-out 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 Reversal
Allows you to reverse all or part of an existing authorization, provided no settlements (either full or partial) have been processed against that authorization. This transaction type does not function with purchase 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 Authorization
Allows you to authorize an amount on a customer’s credit card using customer data that is stored in our database. You provide only a minimum of information, saving you time and effort.
Stored Data Purchase
Allows you to both authorize and settle an amount on a customer’s credit card using customer data that 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 can-cel 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 Credit
Allows you to credit an amount to a customer’s credit card. The Independent Credit transaction is not associated with a previously existing authorization, so the amount of the transaction is not restricted in this way.
Information Lookup
Allows you to run a report through the API over a date range you specify to return data on credit card transactions processed through your merchant account.
Enrollment Lookup
Allows you to determine whether a customer’s credit card is enrolled in the 3D Secure program.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 authenticate 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.
1-2
May 2019 System requirements
System requirementsThe SOAP API has been tested with the following client environments:
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 Foundationhttp://ws.apache.org/axis2/1_2/contents.html
• Microsoft .NET Framework Version 1.1/2.0 Microsoft Corporation http://www.microsoft.com/net
Accessing the Paysafe WSDLs and links
Direct DebitWSDL:
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
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 pro-cessed through a merchant account.
Table 1-4: Client Environments
SOAP Client Programming Environment Operating Environment
Microsoft .NET 1.1 and 2.0 Framework
Microsoft Visual Studio .NET 2003 Microsoft Windows Server 2003 and Windows XP
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
Regardless of which SOAP client you adopt, it must support document-style messaging.
API Reference Guide for Web Services 1.0 1-3
Paysafe Web Services May 2019
Credit cardWSDL:
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 ServiceWSDL:
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 ServicesOnce you have configured your Web Services–enabled application, please contact our Technical Sup-port 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
AVSPaysafe 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
1-4
May 2019 CVD
Authorization Failed error. If you get an Authorization Failed error in response to a transaction request, and 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 following codes, in the avsResponse element, to the merchant application in response to a transac-tion request, with A, N, and E indicating AVS failure:
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.
CVDThe 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 present, 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.
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.
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 databasePaysafe 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 nega-tive database 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, fraudu-lent 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 processed.
3D SecurePaysafe supports 3D Secure, an online cardholder authentication program designed to make Internet purchase transactions safer by authenticating a card holder’s identity at the time of purchase, before the merchant submits an authorization request. It is currently supported by several card brands, including Visa (Verified by Visa), MasterCard (SecureCode), and American Express (SafeKey). Authoriza-tions processed 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.
AudienceThis user’s guide is intended for Paysafe merchants using our Web Services API to process transaction requests with Paysafe.
FunctionalityThis 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
SymbolsThis 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
IntroductionThis chapter describes how to process Direct Debit transactions via the Paysafe Web Service. The fol-lowing operations are supported:
• 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.
Table 2-1: Supported Operations
Operation Description For Request Type
Charge Allows you to transfer money from a customer’s bank account to your merchant account. This trans-action is completed in real time, though the bank-ing network takes 2–5 days to transfer the funds, depending on the bank scheme.
• EFT• ACH• BACS• SEPA
See Building charge or credit requests on page 2-3.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 2–5 days to transfer the funds, depending on the bank scheme.
• EFT• ACH• BACS• SEPA
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 trans-action.
• EFT• ACH• SEPA
See Building updateShippingInfo requests on page 2-12.
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.
• EFT• ACH• BACS• SEPA
See Building lookup requests on page 2-16.
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.
• BACS• SEPA
See Building BACS mandate requests (UK) on page 2-19.
Change Status Allows you to change the status of a charge, credit, or mandate transaction.
• EFT• ACH• BACS• SEPA
See Building change status requests on page 2-25.
Update Mandate Allows you to update the information contained within an existing mandate.
• SEPA See Building mandate update 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.
API Reference Guide for Web Services 1.0 2-1
Direct Debit Transactions May 2019
• The mandate request operation accepts a ddMandateRequest document object.
• 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 requestsCharge 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
// Prepare the call to the Direct Debit Web ServiceDDCheckRequestV1 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 chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.charge(ddCheckRequest);
// Print out the resultString 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);
}
To make this a credit request, modify the value “charge” – in the line “DDCheckResponseV1 ddTxnRe-sponse = ddService.charge(ddCheckRequest)” below – to “credit”.
2-4
May 2019 ddCheckRequestV1 schema
ddCheckRequestV1 schemaA ddCheckRequestV1 document object has the following structure:
API Reference Guide for Web Services 1.0 2-5
Direct Debit Transactions May 2019
ddCheckRequestV1 elements
The ddCheckRequestV1 document object may contain the following 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.
Table 2-2: ddCheckRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Conditional StringMax = 40
This is the unique ID number associated 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 StringMax =9999999.99
This is the amount of the transaction request. NOTE: This field requires a leading non-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 Max = 40
This is the name of the customer’s bank, to which this transaction is posted.
checkNum Yes LongMax = 8
This is the check serial number, provided at the time of the transaction request.
accountNum Yes StringMax = 17If IBAN, Max = 32
This is the customer’s bank account num-ber.For SEPA transactions, this is IBAN (Inter-national Bank Account Number) of the cus-tomer’s bank account.NOTE: This cannot be zero (0) and can con-tain alphanumeric characters only.
2-6
May 2019 ddCheckRequestV1 elements
routingNum Yes StringMin = 6Max = 9If BIC, Min = 8Max = 11
For USD accounts, this is the 9-digit routing number of the customer’s bank. For British pound accounts, this is the 6-digit sort code of the customer’s bank.For Canadian dollar accounts, this is a combination of the 3-digit institution ID 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: EMPTYBICNOTE: This cannot be zero (0) and can con-tain alphanumeric characters only.
payee Conditional StringMax = 81
This is the descriptor that will appear on the 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.
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 StringMax = 40
This is the city in which the bank is located. This is a required element only for certain countries.
mandateRefer-ence
Conditional StringMax = 10For SEPA, Max = 35For BACS,Max = 10
This is the mandate reference that allows the account to be charged. This is the value returned for the mandateReference parameter in the response to a ddMandateRequestV1. NOTE: This element is mandatory for 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 StringMax = 40
This is the customer’s first name. Required if checkPayMethod is set to WEB or TEL.
lastName Conditional String Max = 40
This is the customer’s last name.Required if accountType is set to PC, PS, or PL.
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-7
Direct Debit Transactions May 2019
companyName Conditional StringMax = 50
This is the company’s name. Required if accountType is set to BC, BS, or BL.
street Yes StringMax = 50
This is the first line of the customer’s street address.
street2 Optional StringMax = 50
This is the second line of the customer’s street address.
city Yes StringMax = 40
This is the city in which the customer resides.
state/region Conditional If state, then EnumerationIf region, then stringMax = 40
This is the state/province/region in which the customer resides. Provide state if within U.S./Canada. Pro-vide region if outside of U.S./Canada. 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 StringMax = 10
This is the customer’s ZIP code if in the U.S.; otherwise, this is the customer’s postal code.
phone Optional StringMax = 40
This is the customer’s telephone number.
email Optional StringMax = 100
This is the customer’s email address.
personalID idNumber Optional StringMax = 20
This is the number of the ID provided for the 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 EnumerationIf region, then stringMax = 40
This is the state/province/region in which the ID was issued. Provide state if within U.S./Canada. Pro-vide region if outside of U.S./Canada. See Appendix C: Geographical Codes for correct codes to use.
country Optional StringLength = 2
This is the country in which the ID was issued. Possible values are:• CA (Canada)• US (United States)
expiry Optional The expiry child element has three further child elements.
Child Element of expiry
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
2-8
May 2019 ddCheckRequestV1 elements
day Optional Int Length = 2
This is the day the ID expires.
month Optional Int Length = 2
This is the month the ID expires.
year Conditional Int Length = 4
This is the year the ID expires.This element is required if the expiry ele-ment is included.
socialSecurityNumber Optional StringMax = 12
This is the customer’s Social Security Number.
dateOfBirth Optional This is the customer’s date of birth.
year Conditional StringMax = 41900–9999
This is the customer’s year of birth.
month Conditional StringMax = 12
This is the customer’s month of birth.
day Conditional StringMax = 31
This is the customer’s day of birth.
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 StringMax = 50
This is the shipping tracking number pro-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 StringMax = 40
This is the recipients’s first name.
lastName Optional StringMax = 40
This is the recipient’s last name.
street Optional StringMax = 50
This is the first line of the recipient’s street address.
street2 Optional String Max = 50
This is the second line of the recipient’s street address.
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-9
Direct Debit Transactions May 2019
city Optional StringMax = 40
This is the city in which the recipient resides.
state/region Optional If state, EnumerationIf region, then stringMax = 40
This is the state/province/region in which the recipient resides. Provide state if within U.S./Canada. Pro-vide region if outside of U.S./Canada. 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 StringMax = 10
This is the recipient’s ZIP code if in the U.S.; otherwise, this is the recipient’s postal code.
phone Optional StringMax = 40
This is the recipient’s phone number.
email Optional StringMax = 100
This is the recipient’s email address.
customerIP Optional StringMax = 50
This is the customer’s IP address.
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 StringMax = 15
This is the confirmation number returned by 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.
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
2-10
May 2019 ddCheckRequestV1 elements
Special considerations for Direct Debit elementsSome merchants are integrated with downstream processors that have different requirements for mandatory Direct Debit elements. In such cases, the following holds.
txnDate Optional dateTime This is the date and time that the transac-tion 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 collec-tion date. It must be a minimum of 2 busi-ness 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 StringMax = 20
This is the version of the SDK used, if any.Required if sdk element is provided.
platform Conditional StringMax = 10
This is the integration language of the SDK used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional StringMax = 20
This is the author of the SDK used. Set to 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 StringMax = 30
This is additional data that the merchant can include with the transaction request.
value Optional StringMax = 1024
This is additional data that the merchant can include with the transaction request.
Table 2-3: Additional Direct Debit Element Requirements
Element Regular
Transactions
Guaranteed
Transactions
SEPA 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
Table 2-2: ddCheckRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-11
Direct Debit Transactions May 2019
Building updateShippingInfo requests
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: ddShippin-gRequestV1 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 ServiceDDShippingRequestV1 ddShippingRequest = new DDShippingRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";merchantAccount.storePwd = "myStorePwd";
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.
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 exam-ple below.
Table 2-3: Additional Direct Debit Element Requirements (Continued)
Element Regular
Transactions
Guaranteed
Transactions
SEPA Transactions
2-12
May 2019 updateShippingInfo example – C#
ddShippingRequest.merchantAccount = merchantAccount;ddShippingRequest.confirmationNumber = "123456"; // A valid confirmation number from a previous settle auth or purchaseddShippingRequest.carrier = CarrierV1.FEX; // FedexddShippingRequest.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 infoDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse =ddService.updateShippingInfo(ddShippingRequest);// Print out the resultString 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 schemaA ddShippingRequestV1 document object has the following structure:
ddShippingRequestV1 elementsThe ddShippingRequestV1 document object may contain the following elements:
Table 2-4: ddShippingRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
2-14
May 2019 ddShippingRequestV1 elements
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe 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 StringMax = 50
This is the shipping tracking number pro-vided by the carrier.
confirmationNumber Yes StringMax = 15
This is the confirmation number returned by 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 StringMax = 40
This is the customer’s first name.
lastName Optional String Max = 40
This is the customer’s last name.
street Optional StringMax = 50
This is the first line of the customer’s street address.
street2 Optional StringMax = 50
This is the second line of the customer’s street address.
city Optional StringMax = 40
This is the city in which the customer resides.
state/region Optional If state, then EnumerationIf region, then stringMax = 40
This is the state/province/region in which the customer resides. Provide state if within U.S./Canada. Provide region if outside of U.S./Canada. 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.
Table 2-4: ddShippingRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-15
Direct Debit Transactions May 2019
Building lookup requestsThe 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 ServiceDDLookupRequestV1 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 chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddCheckResponse = ddService.lookup(ddLookupRequest);// Print out the resultString responseTxt = ddCheckResponse.code + " - " + ddCheckResponse.decision;responseTxt += "Transactions:" + Environment.NewLine;if (ddCheckResponse.transaction != null){ for (int i = 0; i < ddCheckResponse.transaction.Length; i++)
zip Optional StringMax = 10
This is the customer’s ZIP code if in the U.S.; otherwise, this is the customer’s postal code.
phone Optional StringMax = 40
This is the customer’s telephone number.
email Optional StringMax = 100
This is the customer’s email address.
Table 2-4: ddShippingRequestV1 Elements (Continued)
Element Child Element Required Type Description
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 schemaA ddLookupRequestV1 document object has the following structure:
ddLookupRequestV1 elementsThe ddLookupRequestV1 document object may contain the following elements:
Table 2-5: ddLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Optional StringMax = 15
This is the confirmation number returned by Paysafe in response to the original request. Include this element only if you want to search using this field. This field takes prece-dence over the merchantRefNum field.
merchantRefNum Conditional StringMax = 40
This is a unique ID number associated with the 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)
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 customer’s bank account to your merchant account.
When you submit a ddMandateRequestV1, Paysafe will return a value for the mandateReference ele-ment in the response. This value is either based on the value you send in the request, or it is automati-cally generated by the Paysafe system. You will use this value in the mandateReference element (which
startDate year Required IntMax = 9999
This is the year set for the search start.
month Required IntMin = 1Max = 12
This is the month set for the search start.
day Required IntMin = 1Max = 31
This is the day set for the search start.
hour Required IntMin = 0Max = 23
This is the hour set for the search start.
minute Required IntMin = 0Max = 59
This is the minute set for the search start.
second Required IntMin = 0Max = 59
This is the second set for the search start.
endDate year Required IntMax = 9999
This is the year set for the search end.
month Required IntMin = 1Max = 12
This is the month set for the search end.
day Required IntMin = 1Max = 31
This is the day set for the search end.
hour Required IntMin = 0Max = 23
This is the hour set for the search end.
minute Required IntMin = 0Max = 59
This is the minute set for the search end.
second Required IntMin = 0Max = 59
This is the second set for the search end.
Table 2-5: ddLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-19
Direct Debit Transactions May 2019
is a child element of the check element) when you process future charge requests against the cus-tomer’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 characters, 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 net-work typically takes 5 days to process the mandate, so 5 days after the mandate has been batched, Pay-safe 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, provided 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 requestsIn 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.
SEPA Direct Debit mandates are active as soon they are created by the merchant, so you can immedi-ately 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 ServiceDDMandateRequestV1 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;
Mandates are not required for SEPA credits.
2-20
May 2019 mandate example – C#
BillingDetailsV1 billingDetails = new BillingDetailsV1();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 chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.mandate(ddCheckRequest);
// Print out the resultString 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 schemaA ddMandateRequestV1 document object has the following structure:
2-22
May 2019 ddMandateRequestV1 elements
ddMandateRequestV1 elementsThe ddMandateRequestV1 document object may contain the following elements:
Table 2-6: ddMandateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Conditional StringMax = 40
This is the unique ID number associated with the original request. The value is created by the merchant and submitted as part of the original 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 Max = 40
This is the name of the customer’s bank, to which this transaction is posted.
checkNum Optional LongMax = 8
This is the check serial number, provided at the time of the transaction request.
accountNum Yes StringMax = 17
This is the customer’s bank account number.For SEPA transactions, this is IBAN (Interna-tional Bank Account Number) of the cus-tomer’s bank account.
routingNum Yes StringMin = 6Max = 9If BIC, Min = 8Max = 11
For British pound accounts, this is the 6-digit sort code of the customer’s bank.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
payee Optional StringMax = 81
This is the descriptor that will appear on the 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
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 StringMax = 40
This is the city in which the bank is located. This is a required element only for certain countries.
mandateReference Conditional StringMax = 10For SEPA, Max = 35
This is the mandate reference that allows the account to be charged. You may optionally set the value of the mandateReference your-self when making the request. If you do not supply a value here then it will be set by Pay-safe 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 StringMax = 40
This is the customer’s first name. Required if checkPayMethod is set to WEB or TEL.
lastName Conditional String Max = 40
This is the customer’s last name.Required if accountType is set to PC, PS, or PL.
companyName Conditional StringMax = 50
This is the company’s name. Required if accountType is set to BC, BS, or BL.
street Optional StringMax = 50
This is the first line of the customer’s street address.
street2 Optional StringMax = 50
This is the second line of the customer’s street address.
city Optional StringMax = 40
This is the city in which the customer resides.
state/region Conditional If state, then EnumerationIf region, then stringMax = 40
This is the state/province/region in which the customer resides. Provide state if within U.S./Canada. Provide region if outside of U.S./Canada. 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 StringMax = 10
This is the customer’s ZIP code if in the U.S.; otherwise, this is the customer’s postal code.
Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description
2-24
May 2019 Building change status requests
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:
phone Optional StringMax = 40
This is the customer’s telephone number.
email Optional StringMax = 100
This is the customer’s email address.
customerIP Optional StringMax = 50
This is the customer’s IP address.
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 sta-tus of PCA (Pending Customer Approval), and will not be sent to the bank.
If the autoSend status is set to N, the man-date 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 StringMax = 30
This is additional data that the merchant can include with the transaction request.
value Optional StringMax = 1024
This is additional data that the merchant can include with the transaction request.
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• Credit• Mandate
• W – Pending • X – Cancelled
Table 2-6: ddMandateRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-25
Direct Debit Transactions May 2019
Paysafe responds to your change status request with the ddCheckResponseV1. In this response, the con-firmationNumber 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 ServiceDDChangeStatusRequestV1 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 chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.changeStatus(ddCheckRequest);
// Print out the resultString 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;
UK Direct Debit (gateway merchants)
• Charge• Credit• Mandate
• C – Completed• CL – Cleared
• RE – Returned
NOTE: Use only when your sponsoring bank has rejected the transaction and no BACS report has been produced. Allow 5 working days from the completed date and then contact Tech-nical Support before making this change request.
EFT/ACH • Charge• Credit
• C – Completed • X – Cancelled
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• C – Completed
• X – Cancelled
NOTE: SEPA Direct Debit transactions can be can-celled only before their exe-cution date.
Table 2-7: Status Changes (Continued)
Solution Request Type Initial Status Resulting Status
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 schemaA ddChangeStatusRequestV1 document object has the following structure:
ddChangeStatusRequestV1 elementsThe ddChangeStatusRequestV1 document object may contain the following elements:
Table 2-8: ddChangeStatusRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
API Reference Guide for Web Services 1.0 2-27
Direct Debit Transactions May 2019
Building mandate update requests
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 confirmationNumber 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 ServiceDDUpdateMandateRequestV1 ddUpdateMandateRequest = new DDUpdateMandateRequestV1();MerchantAccountV1 merchantAccount = new MerchantAccountV1();merchantAccount.accountNum = "12345678";merchantAccount.storeID = "myStoreID";
confirmationNumber Optional StringMax = 15
This value identifies the transaction whose sta-tus you want to change. This is the confirmationNumber returned by Paysafe 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 StringMax = 30
This is additional data that the merchant can include with the transaction request.
value Optional StringMax = 1024
This is additional data that the merchant can include with the transaction request.
Only merchants processing SEPA Direct Debits can use this request type.
Table 2-8: ddChangeStatusRequestV1 Elements (Continued)
Element Child Element Required Type Description
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 chargeDirectDebitServiceV1 ddService = new DirectDebitServiceV1();DDCheckResponseV1 ddTxnResponse = ddService.updateMandate(ddCheckRequest);
// Print out the resultString 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 schemaA ddUpdateMandateRequestV1 document object has the following structure:
ddUpdateMandateRequestV1 elementsThe ddUpdateMandateRequestV1 document object may contain the following elements:
API Reference Guide for Web Services 1.0 2-29
Direct Debit Transactions May 2019
* At least one of these three elements must be included in the request: mandateReference, accountNum, and routing-Num.
Processing the responseA ddCheckResponseV1 has the following structure:
Table 2-9: ddUpdateMandateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Optional StringMax = 15
This value identifies the mandate that you want to update. This is the confirmationNumber returned by Paysafe in response to the original transaction request.
mandateReference Conditional StringMax = 10For SEPA, Max = 35
This is the mandate reference that allows the account to be charged. This is the value returned for the mandateReference parameter in the response to a ddMandateRequestV1. You might need to update the mandateReference, e.g., if the billing terms have changed but all other mandate informa-tion remains the same.
accountNum Conditional StringMax = 17If IBAN, Max = 32
For SEPA transactions, this is the IBAN (International Bank Account Number) of the customer’s bank account. 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 StringMin = 6Max = 9If BIC, Min = 8Max = 11
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: EMP-TYBICYou would need to update the routingNum, e.g., if the customer has changed banks, in which case the accountNum would also have to be updated.
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 pro-cessed in a batch file.
confirmationNumber Yes StringMax = 15
This is the confirmation number returned by Paysafe.If this is returned in response to a ddUpdateMandateRequestV1, this iden-tifies the new mandate that has been created.
merchantRefNum Optional String Max = 40
This is the unique ID number associated 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
mandateReference Yes String Max = 20
This is the mandate reference returned by Paysafe. It is either the value echoed back from the request, or if it was not specified correctly in the request, then it is generated 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 rea-son.
• Declined – the transaction was declined before it was sent for pro-cessing.
• 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 information. Ask the customer to cor-rect 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 StringMax = 100
This is a human readable description of the code element.
detail tag Optional StringMax = 1024
This is the classification of the detail ele-ment.
value Optional StringMax = 30
This is the description of the detail.
txnTime Yes dateTime This is the date and time the transaction was processed by Paysafe.
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
2-32
May 2019 Processing the response
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-53. This value is returned only in response to lookup requests.
amount Optional StringMax = 9999999.99
This is the amount of the first transac-tion that matches a lookup request.
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 2-33
Direct Debit Transactions May 2019
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 appli-cation. You can also look at the code element to provide more fine-grained control for your appli-cation. See Response codes on page B-1 for more details.
transaction Optional This is returned only in response to a lookup request. All transactions that match the lookup request are returned here.
confirmationNum-ber
Conditional StringMax = 15
This is the confirmation number returned by Paysafe for a previous trans-action.
merchantRefNum Optional StringMax = 255
This is the unique ID number associated 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 StringMax = 9999999.99
This is the amount of the transaction.
Table 2-10: ddCheckResponseV1 Elements (Continued)
Element Child Element Required Type Description
2-34
CHAPTER 3
Credit/Debit Card Transactions
IntroductionThis 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 subse-quent settlement transaction.
See Building Purchase/Authorization/Ver-ification requests on page 3-4.Purchase Allows you to both authorize and settle an amount on a cus-
tomer’s credit/debit card in a single transaction.
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 Reversal
Allows you to reverse all or part of an existing authorization, provided no settlements (either full or partial) have been pro-cessed against that authorization. This transaction type does not function with purchase transactions, but only with autho-rizations.
See Building Authorization Reversal requests on page 3-18.
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-21.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 Authorization
Allows you to authorize an amount on a customer’s credit/debit card using customer data that is stored in our database. You provide only a minimum of information, saving you time and effort. See Building Stored Data Requests on
page 3-25.Stored Data Purchase
Allows you to both authorize and settle an amount on a cus-tomer’s credit/debit card using customer data that 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.
See Building Cancel requests on page 3-28.
API Reference Guide for Web Services 1.0 3-1
Credit/Debit Card Transactions May 2019
• 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 doc-ument 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.
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-31.Independent Credit
Allows you to credit an amount to a customer’s credit card. The Independent Credit transaction is not associated with a previously existing authorization, so the amount of the trans-action is not restricted in this way.
Information Lookup
Allows you to run a report through the API over a date range you specify to return data on credit card transactions pro-cessed through your merchant account.
See Building Transaction Lookup requests on page 3-36.
Enrollment Lookup
Allows you to determine whether a customer’s credit card is enrolled in the 3D Secure program.NOTE: This operation is supported only for 3D Secure 1.0.2.
See Building Enrollment Lookup requests on page 3-40.
Authentication Allows you to send an Authentication request, in order to vali-date a cardholder’s password for credit cards enrolled in the 3D Secure program. NOTE: This operation is supported only for 3D Secure 1.0.2.
See Building Authentication requests on page 3-43.
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.
Table 3-1: Supported Operations
Operation Description Request Type
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-18
• See Building Settlement/Credit requests on page 3-21
• See Building Stored Data Requests on page 3-25
• See Building Cancel requests on page 3-28
• See Building Payment/Independent Credit requests on page 3-31
• See Building Enrollment Lookup requests on page 3-40
• See Building Authentication requests on page 3-43
• See Processing the response on page 3-46
Building Purchase/Authorization/Verification requestsPurchase, 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: ccAu-thRequestV1 Elements on page 3-8 for details on the elements required.
3-4
May 2019 Purchase example – C#
Purchase example – C#
The following is a Purchase example in C#.
//Prepare the call to the Credit Card Web ServiceCCAuthRequestV1 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.cardPayMethod = CardPayMethodV1.WEB; //WEB = Card Number ProvidedbillingDetails.cardPayMethodSpecified = true;billingDetails.firstName = "Jane";billingDetails.lastName = "Jones";billingDetails.street = "123 Main Street";billingDetails.city = "LA";billingDetails.Item = (object) StateV1.CA; // CaliforniabillingDetails.country = CountryV1.US; // United StatesbillingDetails.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 purchaseCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccPurchase(ccAuthRequest);
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 example below.
To make this an Authorize or Verification request, modify the value “ccPurchase” – in the line “CCTxnRe-sponseV1 ccTxnResponse = ccService.ccPurchase(ccAuthRequest);” below – to “ccAuthorize” or “ccVer-ification”, respectively.
API Reference Guide for Web Services 1.0 3-5
Credit/Debit Card Transactions May 2019
// Print out the resultString responseTxt = ccTxnResponse.code + " - " + ccTxnResponse.decision + " - "
+ 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 schemaA ccAuthRequestV1 has the following structure:
API Reference Guide for Web Services 1.0 3-7
Credit/Debit Card Transactions May 2019
r.
is
n
is
n
d d
e
o
es.
ccAuthRequestV1 elementsThe ccAuthRequestV1 document object may contain the following elements:
Table 3-2: ccAuthRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account numbe
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It defined by Paysafe and provided to the merchant as part of the integratioprocess.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It defined by Paysafe and provided to the merchant as part of the integratioprocess.
merchantRefNum Yes StringMax = 255
This is a unique ID number associatewith each request. The value is createby the merchant and submitted as part of the request.
customerTokenId For internal use only.
amount Yes StringMax=999999999.99
This is amount of the transaction request. NOTE: Though mandatory, this valuwill be ignored for the ccVerificationtransaction.
card cardNum Yes String Min = 8Max = 20
This is the card number used for thetransaction.
cardExpiry Yes The cardExpiry child element has twfurther child elements – month and year.
Child Element of
cardExpiry
month Yes Int Max = 2
This is the month the credit card expires.
year Yes IntLength = 4
This is the year the credit card expir
3-8
May 2019 ccAuthRequestV1 elements
e
a-
a
e.
ns-his r
rd on
ry e =
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
issueNum Optional IntegerMax = 2
The 1- or 2-digit number located onthe front of the card, following the card number.NOTE: The issueNum element can bused only when the cardType is MD (Maestro), or SO (Solo).
cvdIndicator Optional IntegerLength = 1
This is the status of CVD value informtion. Possible values are:• 0 – The customer did not provide
value. • 1 – The customer provided a valu• 2 – The value is illegible. • 3 – The value is not on the card.
NOTE: The cvdIndicator element is mandatory for the ccVerification traaction. Also note that even though telement is optional, it is required foseveral risk-related checks and we strongly advise you to include it to avoid failed transactions.
cvd Conditional StringLength = 3 or 4
The 3- or 4-digit security code that appears on the card following the canumber. This code does not appear imprints.NOTE: The cvd element is mandatowhen the cvdIndicator element valu1.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-9
Credit/Debit Card Transactions May 2019
i-
g -
n-
d
d
n
f t
-
e f t
-
authenticationNOTE: Use this element with ccAuthorize or ccPurchase requests only.
indicator Optional IntegerValue = 1
This is the Electronic Commerce Indcator code, a 2-digit value that gets returned by the card issuer indicatinwhether the cardholder was successfully authenticated. Possible values are:Visa / Amex / JCB• 05 – Identifies a successfully
authenticated transaction.• 06 – Identifies an attempted authe
ticated transaction.• 07 – Identifies a non-authenticate
transaction.
Mastercard• 01 – Identifies a non-authenticate
transaction.• 02 – Identifies a successfully
authenticated transaction.
This value is returned in the eci childelement of the tdsAuthenticateResponse element inthe ccTxnResponseV1 to your ccAu-thenticateRequestV1 request.
cavv Optional StringMax = 80
This is the Cardholder AuthenticatioVerification Value. This value is returned in the cavv child element othe tdsAuthenticateResponse elemenin the ccTxnResponseV1 to your ccAuthenticateRequestV1 request.
xid Optional StringMax = 80
This is the transaction identifier returned by the card issuer. This valuis returned in the xid child element othe tdsAuthenticateResponse elemenin the ccTxnResponseV1 to your ccAuthenticateRequestV1 request.NOTE: This exists only for 3D Secure1.0.2.
enrollmentStatus Optional Enumeration This indicates whether 3D Secure authentication is available for the cardholder. Possible values are:• Y – Authentication available• N – Cardholder not enrolled• U – Authentication unavailable• E – Error
NOTE: This exists only for 3D Secure1.0.2.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-10
May 2019 ccAuthRequestV1 elements
t-
n-
s
lly er.
2 rd
n. e is
en
for :ne
en
’s
a-
authenticationStatus Optional Enumeration This indicates the authentication oucome. Possible values are:• Y – Cardholder successfully authe
ticated with their Card Issuer.• A – Cardholder authentication wa
attempted. • N – Cardholder failed to successfu
authenticate with their Card Issu• U – Authentication with the Card
Issuer was unavailable. • E – Error• R – Rejected transaction
NOTE: The value R exists only for 3DSecure 2.|
directoryServerTransactionId Optional StringMax = 36
This is the unique directory server transaction ID required for Mastercard. NOTE: This exists only for 3D Secureand is required only for the Mastercabrand.
threeDSecureVersion Optional StringMin = 5Max = 8
This is the 3D Secure protocol versioNOTE: If no version is specified in threquest, value defaults to 1.0.2. andechoed in the response.
authCode Optional StringMax = 50
This is the Authorization code assigned by the issuing bank and returned by Paysafe for a previous transaction. NOTE: Include this element only whinstructed to do so by Paysafe.
billingDetails cardPayMethod Optional Enumeration This is how the card was presented the transaction. Possible values are• WEB – Card number provided onli• TEL – Card number provided by
phone• P – Card present• PD – Card present deferred• D – Deferred
NOTE: Include this element only whinstructed to do so by Paysafe.
firstName Optional String Max = 40
This is the customer’s first name.
lastName Optional String Max = 40
This is the customer’s last name.
street Optional StringMax = 50
This is the first line of the customerstreet address.NOTE: the street element is manda-tory if you are processing a ccVerifiction transaction.
street2 Optional StringMax = 50
This is the second line of the cus-tomer’s street address.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-11
Credit/Debit Card Transactions May 2019
r
-
e ’s
m-
.
ce
t
city Optional StringMax = 40
This is the city in which the customeresides.
state/region Optional If state, EnumerationIf region, then stringMax = 40
This is the state/province/region in which the customer resides. Provide state if within U.S./Canada. Provide region if outside of U.S./Canada. See Appendix C: Geographical Codesfor correct codes to use.
country Optional Enumeration This is the country in which the cus-tomer resides. See Country codes onpage C-3 for correct codes to use.
zip Mandatory StringMax = 10
This is the customer’s ZIP code if in thU.S.; otherwise, this is the customerpostal code.
phone Optional StringMax = 40
This is the customer’s telephone nuber.
email Optional StringMax = 100
This is the customer’s email address
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 Servi• 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 StringMax = 40
This is the recipient’s first name.
lastName Optional StringMax = 40
This is the recipient’s last name.
street Optional StringMax = 50
This is the first line of the recipient’sstreet address.
street2 Optional String Max = 50
This is the second line of the recipi-ent’s street address.
city Optional StringMax = 40
This is the city in which the recipienresides.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-12
May 2019 ccAuthRequestV1 elements
-
pi-
he ’s
r.
.
-
za-
r a -ng
e-
in e
is by
ly r a of e
is by -
o
be
state/region Optional If state, EnumerationIf region, then stringMax = 40
This is the state/province/region in which the recipient resides. Provide state if within U.S./Canada.Provide region if outside of U.S./Canada. See Appendix C: Geographical Codesfor correct codes to use.
country Optional Enumeration This is the country in which the recient resides.
zip Optional StringMax = 10
This is the recipient’s ZIP code if in tU.S.; otherwise, this is the recipientpostal code.
phone Optional StringMax = 40
This is the recipient’s phone numbe
email Optional StringMax = 100
This is the recipient’s email address
recurring Optional NOTE: You cannot include both therecurring element and the storedCredential element in the same authorition request. Paysafe recommends using storedCredential.
recurringIndicator Conditional Enumeration Use this parameter to indicate whether a transaction is an initial orepeat transaction for a specific customer for whom you will be processirecurring transactions. Depending on which processing gatway is used, if the value for a repeattransaction is set to R, the gateway may be more lenient regarding certarequirements such as CVD data andaddress information, authorizing threquest without this data.Possible values are:• I – Initial Recurring • R – Subsequent Recurring
originalConfirmationNumber
Conditional StringMax = 15
If this is a recurring transaction, thisthe confirmation number returned Paysafe for the initial transaction inthe series. If you include this value, Paysafe will be able to more preciseidentify an Authorization to Settle oSettlement to Credit, should either those transactions be required in thfuture.
previousConfirmationNumber
Conditional String Max = 15
If this is a recurring transaction, thisthe confirmation number returned Paysafe for the most recent transaction in the series. If you include thisvalue, Paysafe will be able to more precisely identify an Authorization tSettle or a Settlement to Credit, should either of those transactions required in the future.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-13
Credit/Debit Card Transactions May 2019
d at
-a-
or e
d e
d
r
e-.
st it
--
storedCredential Optional The storedCredential element is useto identify authorization requests thuse credit card numbers that are stored by merchants, in order to improve authorization rates and reduce fraud. NOTE: You cannot include both the recurring element and the storedCredential element in the same authoriztion request. Paysafe recommends using storedCredential.If you are not sending this element and are sending the recurringIndicatelement with the value R, type will bdefaulted to RECURRING and occur-rence will be defaulted to SUBSE-QUENT. If recurringIndicator is sent with the value I, type will be defaulteto RECURRING and occurrence will bdefaulted to INITIAL.
type Optional Enumeration This specifies the type of request being made. Possible values are:• ADHOC – Ad hoc consumer-initiate
request• TOPUP – Unscheduled merchant-
initiated request when a consumebalance is below a set limit
• RECURRING – Scheduled, mer-chant-initiated recurring request
occurrence Optional Enumeration This specifies whether this stored crdential request is initial or recurringPossible values are:• INITIAL – Used when this is the fir
time the consumer uses this credcard
• RECURRING – Used when the consumer uses this credit card for subsequent requests
NOTE: The card cvd value is requiredwhen this is set to INITIAL.
customerIP Optional StringMax = 50
This is the customer’s IP address.
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.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-14
May 2019 ccAuthRequestV1 elements
t a nd
if
.
he
.
et
.
st. on
st. on
ill
er,
.
nc-
-
n,
he re:.
dupeCheck Optional Boolean This validates that this request is noduplicate. A request is considered aduplicate if the cardNum, amount, amerchantRefNum are the same.
sdk version Conditional StringMax = 20
This is the version of the SDK used, any.Required if sdk element is provided
platform Conditional StringMax = 10
This is the integration language of tSDK used (e.g., Java, .NET). Required if sdk element is provided
provider Conditional StringMax = 20
This is the author of the SDK used. Sto value “op” when the SDK is pro-vided by Paysafe. Required if sdk element is provided
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction requeSee addendumData tag/value pairs page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction requeSee addendumData tag/value pairs page 3-17 for details.
merchantDescriptorNOTE: Not all process-ing gateways support this parameter. Contact your account manager for more information.
dynamicDescriptor Optional StringMax = 25
This is a merchant descriptor that wbe displayed on a customer’s creditcard statement.
phone Optional StringMax = 13
This is the merchant’s phone numbwhich will be appended to the mer-chant descriptor on a customer’s credit card statement.
accordDNOTE: Include this ele-ment only when instructed to do so by Paysafe.
financingType Conditional Enumeration This is the type of financing offeredPossible values are:• D – Deferred payment financing• E – Equal payment financing
plan Conditional StringMax = 3
This is the plan number for this finaing transaction.
gracePeriod Optional IntegerMax = 2
This is the grace period, in months,associated with deferred payment transactions.
term Optional IntegerMax = 2
This is the number of payments, in months, for equal payment transactions.
description Optional StringMax = 255
This is a description of the transactioprovided by the merchant.
cardEntryMode Optional Enumeration This is the method used to capture tcard information. Possible values a• SWIPED – A card reader was used• MANUAL – The card number was
entered manually.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-15
Credit/Debit Card Transactions May 2019
e
s-
e ti-
h.
or s
er
.
geoLocation Optional This is the geographical location of thmobile transaction.
latitude Conditional StringMax = 24
This is the latitude of the mobile tranaction (e.g., 44.903889).
longitude Conditional StringMax = 24
This is the longitude of the mobile transaction (e.g., -77.255123).
walletTransactionId Internal use only.
profile dateOfBirth Conditional This field allows you to record the cardholder’s date of birth, if you havit. It may be used to assist in authencating the customer’s identity with athird-party validation service.
Child Element of
dateOfBirth
day Mandatory IntegerMin = 1Max = 31
This is the customer‘s day of birth.
month Mandatory IntegerMin = 1Max = 12
This is the customer‘s month of birt
year Mandatory IntegerMin = 1900Max = 9999
This is the customer‘s year of birth.
visaAdditionalAuthData NOTE: This element is supported for both Visa and Mastercard. The recipient is deemed to be the person party who has the contractual relationship with the merchant/ financial institution. This may be differentfrom the cardholder, e.g., in the case of a parent topping up a child’s savings account. Therefore, the fieldshould not be collected on the same page as cardholder information, but instead be passed in the back-ground from the merchant’s records.Include this element if your Merchant Category Code is 6012 and your registered trading address is in theUnited Kingdom. If you have any questions, contact your account manager. All fields are optional, howevscheme fines may apply if data is consistently not supplied and chargebacks persist.
recipientDateOfBirth Optional
Child Element of recipientDateOfBirth
day Conditional IntegerMin = 1Max = 31
This is the recipient’s day of birth.
month Conditional IntegerMin = 1Max = 12
This is the recipient’s month of birth
year Conditional IntegerMin = 1900Max = 9999
This is the recipient’s year of birth.
recipientZip Optional StringMax = 10
This is the recipient‘s postcode. NOTE: The last 3 characters are not sent to the banking network.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-16
May 2019 addendumData tag/value pairs
ur-
e
er, s-
pi-rd
r-rk in
ts,
addendumData tag/value pairs
The following table contains the tag/value pairs supported for the addendumData element.
recipientLastName Optional String Max = 40
This is the recipient‘s last name or sname. NOTE: Only the first 6 characters arsent to the banking network.
recipientAccountNumber Optional StringMax = 25
This is the recipient‘s account numbe.g., a loan agreement number or cutomer ID. In the case where the recient account is a prepaid card, the canumber may be sent in full.NOTE: Only the first 6 and last 4 chaacters are sent to the banking netwoand will be masked accordingly withthe back office and any other reporto comply with PCI regulations.
Not all processing gateways support all addendumData tag/value pairs. Contact your account man-ager for more information
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.
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][_][-]
KEYWORD This value can be any text the merchant wants to use, e.g., used for reporting purposes 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.
Table 3-2: ccAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-17
Credit/Debit Card Transactions May 2019
Building Authorization Reversal requestsAuthorization 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.
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: ccAu-thReversalRequestV1 Elements on page 3-20 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 ServiceCCAuthReversalRequestV1 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
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_CURRENCYNOTE: This tag/value pair can be included with the ccAuthRequestV1 document object only (i.e., for Authorization, Purchase, and Verification card transaction requests).
Include this tag/value pair in order to have the merchant account’s currency returned in the transaction response.Possible values:• on• 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.
You can use Authorization Reversal transactions to reverse Authorizations only. You cannot reverse Purchase transactions.
Table 3-3: addendumData Tag/Value Pairs (Continued)
Tag Value
3-18
May 2019 ccAuthReversalRequestV1 schema
CreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccAuthorizeReversal(authReversalRequest);
// Print out the resultString 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);}
ccAuthReversalRequestV1 schemaA ccAuthReversalRequestV1 has the following structure:
API Reference Guide for Web Services 1.0 3-19
Credit/Debit Card Transactions May 2019
ccAuthReversalRequestV1 elementsThe ccAuthReversalRequestV1 document object contains the following elements:
Table 3-4: ccAuthReversalRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
confirmationNumber Yes StringMax = 15
This is the confirmation number returned by Paysafe for the Authorization you want to reverse.
merchantRefNum Yes StringMax = 255
This is a unique ID number associated with each request. The value is created by the mer-chant and submitted as part of the request.
3-20
May 2019 Building Settlement/Credit requests
Building Settlement/Credit requestsSettlement 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: ccPostAu-thRequestV1 Elements on page 3-23 for details on the elements required.
Settlement example – C#The following is a Settlement example in C#.
//Prepare the call to the Credit Card Web ServiceCCPostAuthRequestV1 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 SettlementCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccSettlement(ccPostAuthRequest);
reversalAmount Optional StringMax=999999999.99
This is amount of the original authorization that you want to reverse. If you omit this ele-ment, the full amount of the original authoriza-tion will be reversed.NOTE: Not all processing gateways support partial authorization reversals. Contact your account manager for more information.
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional StringMax = 24
This is the latitude of the mobile transaction (e.g., 44.903889).
longitude Conditional StringMax = 24
This is the longitude of the mobile transaction (e.g., -77.255123).
To make this a Credit request, just modify the value “ccSettlement” – in the line “CCTxnResponseV1 ccTxnResponse = ccService.ccSettlement(ccPostAuthRequest);” below – to “ccCredit”.
Table 3-4: ccAuthReversalRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-21
Credit/Debit Card Transactions May 2019
// Print out the resultString 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 schemaA ccPostAuthRequestV1 document object has the following structure:
3-22
May 2019 ccPostAuthRequestV1 elements
ccPostAuthRequestV1 elementsThe ccPostAuthRequestV1 document object may contain the following elements:
Table 3-5: ccPostAuthRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Yes StringMax = 15
This is the confirmation number returned by Paysafe for the original request.
merchantRefNum Yes StringMax = 40
This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request.
API Reference Guide for Web Services 1.0 3-23
Credit/Debit Card Transactions May 2019
amount Optional StringMax=999999999.99
This is amount of the transaction request. You can Settle all or part of an Authoriza-tion. You can Credit all or part of a Settle-ment.
origMerchantTxn Conditional StringMax = 255
This is the merchant transaction ID from a 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 duplicate. A request is considered a dupli-cate if the cardNum, amount, and merchantRefNum are the same.
sdk version Conditional StringMax = 20
This is the version of the SDK used, if any.Required if sdk element is provided.
platform Conditional StringMax = 10
This is the integration language of the SDK used (e.g., Java, .NET). Required if sdk element is provided.
provider Conditional StringMax = 20
This is the author of the SDK used. Set to value “op” when the SDK is provided by Paysafe.Required if sdk element is provided.
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional StringMax = 24
This is the latitude of the mobile transac-tion (e.g., 44.903889).
longitude Conditional StringMax = 24
This is the longitude of the mobile transac-tion (e.g., -77.255123).
accordDNOTE: Include this element only when instructed to do so by Paysafe. It cannot be used for credit requests.
Optional You can include the accordD element only if you have already provided it in the authori-zation request you are now settling and you want to change one or more of the terms specified in the child elements.
financingType Conditional Enumeration This is the type of financing offered. Possi-ble values are:• D – Deferred payment financing• E – Equal payment financing
plan Conditional StringMax = 3
This is the plan number for this financing transaction.
Table 3-5: ccPostAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-24
May 2019 Building Stored Data Requests
Building Stored Data RequestsStored 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-27 for details on the elements required.
Stored Data requests allow you to perform credit card Authorizations and Purchases by providing a minimum of customer information. The Stored Data request requires a Confirmation Number from a previous Authorization or Purchase.
This Confirmation Number allows Paysafe to access from its database most of the data required for the transaction.
Stored Data Authorization example – C#The following is a Stored Data Authorization example in C#.
//Prepare the call to the Credit Card Web ServiceMerchantAccountV1 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
gracePeriod Optional IntegerMax = 2
This is the grace period, in months, associ-ated with deferred payment transactions.
term Optional IntegerMax = 2
This is the number of payments, in months, for equal payment transactions.
The Confirmation Number can be a maximum of 24 months old.
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 sim-ilar data associated with the Confirmation Number, for that request only.
To make this a Stored Data Purchase request, just modify the value “ccStoredDataAuthorize” – in the line “CCTxnResponseV1 ccTxnResponse = ccService.ccStoredDataAuthorize(ccStoredDataRequest);” below – to “ccStoredDataPurchase”.
Table 3-5: ccPostAuthRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-25
Credit/Debit Card Transactions May 2019
CreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccStoredDataAuthorize(ccStoredDataRequest);String responseTxt = ""; // Print out the resultif (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 schemaA ccStoredDataRequestV1 document object has the following structure:
3-26
May 2019 ccStoredDataRequestV1 elements
ccStoredDataRequestV1 elementsThe ccStoredDataRequestV1 document object may contain the following elements:
Table 3-6: ccStoredDataRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Required StringMax = 10
This is the merchant account number.
storeID Required String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Required StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Required StringMax = 255
This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request.
confirmationNumber Required StringMax = 15
This is the confirmation number returned by Paysafe for the original request.NOTE: The confirmationNumber can be a maximum of 24 months old.
amount Required StringMax=999999999.99
This is amount of the transaction request.
cardExpiry month Optional Int Max = 2
This is the month the credit card expires.Use this element to include updated card expiry date information, if required, to be included with the rest of the transaction data.
year Optional IntLength = 4
This is the year the credit card expires.Use this element to include updated card expiry date information, if required, to be included with the rest of the transaction data.
cvdIndicator Optional IntegerLength = 1
This is the status of CVD value information. 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 StringLength = 3 or 4
The 3- or 4-digit security code that appears on 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.
API Reference Guide for Web Services 1.0 3-27
Credit/Debit Card Transactions May 2019
Building Cancel requestsUse 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-30 for details on the elements required.
Cancel Settle example – C#The following is a Cancel Settle example in C#.
storedCredential Optional The storedCredential element is used to identify stored data requests that use credit card information stored by Paysafe. In this case, it would be card information associ-ated 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.
merchantDescriptorNOTE: Not all pro-cessing gateways support this parame-ter. Contact your account manager for more information.
dynamicDescrip-tor
Optional StringMax = 25
This is a merchant descriptor that will be dis-played on a customer’s credit card state-ment.
phone Optional StringMax = 13
This is the merchant’s phone number, which will be appended to the merchant descriptor on a customer’s credit card statement.
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
Table 3-6: ccStoredDataRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-28
May 2019 ccCancelRequestV1 schema
//Prepare the call to the Credit Card Web ServiceCCCancelRequestV1 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 settleCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccCancelSettle(ccCancelRequest);
// Print out the resultString 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);
}
ccCancelRequestV1 schemaA ccCancelRequestV1 document object has the following structure:
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.ccCancelSettle(ccCancel-Request);” below – to “ccCancelCredit”, “ccCancelPayment”, or “ccCancelIndependentCredit”, respec-tively.
API Reference Guide for Web Services 1.0 3-29
Credit/Debit Card Transactions May 2019
ccCancelRequestV1 elementsThe ccCancelRequestV1 document object may contain the following elements:
Table 3-7: ccCancelRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Yes StringMax = 15
This is the confirmation number returned by Paysafe for the original Settlement or Credit request.
sdk version Conditional StringMax = 20
This is the version of the SDK used, if any.Required if sdk element is provided.
platform Conditional StringMax = 10
This is the integration language of the SDK used (e.g., Java, .NET). Required if sdk element is provided.
3-30
May 2019 Building Payment/Independent Credit requests
Building Payment/Independent Credit requestsPayments 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: ccPaymen-tRequestV1 Elements on page 3-33 for details on the elements required.
Payment example – C#
The following is a Payment example in C#.
//Prepare the call to the Credit Card Web ServiceCCPaymentRequestV1 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";
provider Conditional StringMax = 20
This is the author of the SDK used. Set to value “op” when the SDK is provided by Pay-safe.Required if sdk element is provided.
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
geoLocation Optional This is the geographical location of the mobile transaction.
latitude Conditional StringMax = 24
This is the latitude of the mobile transaction (e.g., 44.903889).
longitude Conditional StringMax = 24
This is the longitude of the mobile transac-tion (e.g., -77.255123).
All optional elements that take non-nullable data types (e.g., int or enum) must have their speci-fied attribute set to true when setting values for those elements. See the cardType element in the example below.
To make this an Independent Credit request, just modify the value “ccPayment” – in the line “CCTxnRe-sponseV1 ccTxnResponse = ccService.ccPayment(ccPaymentRequest);” below – to “ccIndependentCredit”.
Table 3-7: ccCancelRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-31
Credit/Debit Card Transactions May 2019
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.cardPayMethod = CardPayMethodV1.WEB; //WEB = Card Number ProvidedbillingDetails.cardPayMethodSpecified = true;billingDetails.firstName = "Jane";billingDetails.lastName = "Jones";billingDetails.street = "123 Main Street";billingDetails.city = "LA";billingDetails.Item = (object)StateV1.CA; // CaliforniabillingDetails.country = CountryV1.US; // United StatesbillingDetails.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 requestCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccPayment(ccPaymentRequest);
// Print out the resultString 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);
}}catch (WebException we){
consoleTextBox.Text += we.Message.ToString();
3-32
May 2019 ccPaymentRequestV1 schema
consoleTextBox.Refresh();}
ccPaymentRequestV1 schemaA ccPaymentRequestV1 has the following structure:
ccPaymentRequestV1 elements The ccPaymentRequestV1 document object may contain the following elements:
Table 3-8: ccPaymentRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
merchantRefNum Yes StringMax = 40
This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request.
customerTokenId For internal use only.
API Reference Guide for Web Services 1.0 3-33
Credit/Debit Card Transactions May 2019
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 maxi-mum per credit card. Contact your account manager for details.
card cardNum Yes String Min = 8Max = 20
This is the card number used for the trans-action.
cardExpiry Yes The cardExpiry child element has two fur-ther child elements – month and year.
Child Element of
cardExpiry
month Yes Int Max = 2
This is the month the credit card expires.
year Yes IntLength = 4
This is the year the credit card expires.
cardType Optional Enumeration This is the type of card used for the trans-action. 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 IntegerMax = 2
The 1- or 2-digit number located on the front of the card, following the card num-ber.NOTE: The issueNum element can be used only when the cardType is MD (Maestro), or SO (Solo).
cvdIndicator Optional IntegerLength = 1
This is the status of CVD value information. 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 Condi-tional
StringLength = 3 or 4
The 3- or 4-digit security code that 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.
Table 3-8: ccPaymentRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-34
May 2019 ccPaymentRequestV1 elements
billingDetails cardPayMethod For internal use only.
firstName Optional String Max = 40
This is the customer’s first name.
lastName Optional String Max = 40
This is the customer’s last name.
street Optional StringMax = 50
This is the first line of the customer’s street address.
street2 Optional StringMax = 50
This is the second line of the customer’s street address.
city Optional StringMax = 40
This is the city in which the customer resides.
state/region Optional If state, EnumerationIf region, then stringMax = 40
This is the state/province/region in which the customer resides. Provide state if within U.S./Canada. Pro-vide region if outside of U.S./Canada. 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 StringMax = 10
This is the customer’s ZIP code if in the U.S.; otherwise, this is the customer’s postal code.
phone Optional StringMax = 40
This is the customer’s telephone number.
email Optional StringMax = 100
This is the customer’s email address.
sdk version Condi-tional
StringMax = 20
This is the version of the SDK used, if any.Required if sdk element is provided.
platform Condi-tional
StringMax = 10
This is the integration language of the SDK used (e.g., Java, .NET). Required if sdk element is provided.
provider Condi-tional
StringMax = 20
This is the author of the SDK used. Set to value “op” when the SDK is provided by Paysafe. Required if sdk element is provided.
authcode Optional StringMax = 50
This is the Authorization code assigned by the issuing bank and returned by Paysafe for a previous transaction. NOTE: Include this element only when instructed to do so by Paysafe.
previousConfirmation-Number
Optional StringMax = 20
This is the confirmation number of a previ-ously processed authorization. NOTE: Include this element only when instructed to do so by Paysafe.
Table 3-8: ccPaymentRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-35
Credit/Debit Card Transactions May 2019
Building Transaction Lookup requestsThe 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 ServiceCCTxnLookupRequestV1 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();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";
addendumData tag Optional StringMax = 30
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
value Optional StringMax = 1024
This is additional data that can be included with the transaction request. See addendumData tag/value pairs on page 3-17 for details.
Table 3-8: ccPaymentRequestV1 Elements (Continued)
Element Child Element Required Type Description
3-36
May 2019 Transaction Lookup example – C#
endDate.minute = "00";endDate.second = "00";ccTxnLookupRequest.endDate = endDate;
//Perform the Web Services call to process the requestCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccTxnLookup(ccTxnLookupRequest);// Print out the resultString 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-37
Credit/Debit Card Transactions May 2019
ccTxnLookupRequestV1 schemaA ccTxnLookupRequestV1 has the following structure:
ccTxnLookupRequestV1 elementsThe ccTxnLookupRequestV1 document object may contain the following elements:
Table 3-9: ccTxnLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Optional StringMax = 15
This is the confirmation number returned by Paysafe in response to the original request. Include this element only if you want to search using this field. This field takes prece-dence over the merchantRefNum field.NOTE: If you include this element, you do not have to specify the startDate or endDate elements.
3-38
May 2019 ccTxnLookupRequestV1 elements
netbanxReference Optional StringMax = 18
This is a transaction ID used to identify cer-tain legacy transactions.NOTE: If you include this element, you must specify the startDate and endDate elements.
merchantRefNum Optional StringMax = 255
This is a unique ID number associated with the 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 IntMax = 9999
This is the year set for the search start.
month Conditional IntMin = 1Max = 12
This is the month set for the search start.
day Conditional IntMin = 1Max = 31
This is the day set for the search start.
hour Conditional IntMin = 0Max = 23
This is the hour set for the search start.
minute Conditional IntMin = 0Max = 59
This is the minute set for the search start.
second Conditional IntMin = 0Max = 59
This is the second set for the search start.
endDate year Conditional IntMax = 9999
This is the year set for the search end.
month Conditional IntMin = 1Max = 12
This is the month set for the search end.
day Conditional IntMin = 1Max = 31
This is the day set for the search end.
hour Conditional IntMin = 0Max = 23
This is the hour set for the search end.
minute Conditional IntMin = 0Max = 59
This is the minute set for the search end.
second Conditional IntMin = 0Max = 59
This is the second set for the search end.
Table 3-9: ccTxnLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-39
Credit/Debit Card Transactions May 2019
Building Enrollment Lookup requestsUse 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-42 for details on the elements required.
Enrollment Lookup example – C#The following is an Enrollment Lookup example in C#.
//Prepare the call to the Credit Card Web ServiceCCEnrollmentLookupRequestV1 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 LookupCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccTDSLookup(enrollmentLookupRequest);
// Print out the resultString 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++)
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.
All optional elements that take non-nullable data types (e.g., int or enum) must have their speci-fied attribute set to true when setting values for those elements. See the cardType element in the example below.
3-40
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 schemaA ccEnrollmentLookupRequestV1 has the following structure:
ccEnrollmentLookupRequestV1 elementsThe ccEnrollmentLookupRequestV1 document object may contain the following elements:
API Reference Guide for Web Services 1.0 3-41
Credit/Debit Card Transactions May 2019
Table 3-10: ccEnrollmentLookupRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Pay-safe and provided to the merchant as part of the integration process.
merchantRefNum Yes StringMax = 255
This is a unique ID number associated with each request. The value is created by the mer-chant and submitted as part of the request.
amount Yes StringMax=999999999.99
This is amount of the transaction request. NOTE: Though the amount element is man-datory for the Enrollment Lookup transaction, no amount is actually processed against the credit card.
card cardNum Yes String Min = 8Max = 20
This is the card number used for the transac-tion.
cardExpiry Yes The cardExpiry child element has two further child elements – month and year.
Child Element of
cardExpiry
month Yes Int Max = 2
This is the month the credit card expires.
year Yes IntLength = 4
This is the year the credit card expires.
cardType Optional Enumeration This is the type of card used for the transaction. Possible values are:• JC – JCB• MC – Mastercard• VI – Visa
issueNum Optional IntegerMax = 2
The 1- or 2-digit number located on the front of the card, following the card number.NOTE: The issueNum element is not used for this request type.
cvdIndicator Optional IntegerLength = 1
This is the status of CVD value information. 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-42
May 2019 Building Authentication requests
Building Authentication requestsUse 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. Authen-tication requests require the ccAuthenticateRequestV1 document object. This section describes the structure of a ccAuthenticateRequestV1 and how to construct one. See Table 3-11: ccAuthenticateReq-uestV1 Elements on page 3-44 for details on the elements required.
Authentication example – C#The following is an Authentication example in C#.
//Prepare the call to the Credit Card Web ServiceCCAuthenticateRequestV1 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 authenticationCreditCardServiceV1 ccService = new CreditCardServiceV1();CCTxnResponseV1 ccTxnResponse = ccService.ccTDSAuthenticate(authenticateRequest);
// Print out the resultString 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);
cvd Conditional StringLength = 3 or 4
The 3- or 4-digit security code that appears on the card following the card number. This code does not appear on imprints.NOTE: The cvd element is not used for this request type.
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.
Table 3-10: ccEnrollmentLookupRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-43
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 schemaA ccAuthenticateRequestV1 has the following structure:
ccAuthenticateRequestV1 elementsThe ccAuthenticateRequestV1 document object may contain the following elements:
Table 3-11: ccAuthenticateRequestV1 Elements
Element Child Element Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 20
This is the Paysafe store identifier, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenticate the request. It is defined by Paysafe and provided to the merchant as part of the integration process.
confirmationNumber Yes StringMax = 15
This is the confirmation number in the ccTxn-ResponseV1 returned by Paysafe in response to the ccEnrollmentLookupRequestV1.
3-44
May 2019 ccAuthenticateRequestV1 elements
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 authenti-cation information. It is an encoded response generated by the Issuer ACS soft-ware. Its digital signature will be verified through Paysafe to ensure it was generated by a legitimate Issuer.
merchantRefNum Optional StringMax = 255
This is a unique ID number associated with each request. The value is created by the merchant and submitted as part of the request.
Table 3-11: ccAuthenticateRequestV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-45
Credit/Debit Card Transactions May 2019
Processing the responseA ccTxnResponseV1 has the following structure:
3-46
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 StringMax = 15
This is the confirmation number returned by Paysafe.
merchantRefNum Optional StringMax = 255
This is a unique ID number that was created by the merchant and submit-ted as part of the request.
childAccountNum Optional StringMax = 10
This is the child merchant account number, and provided only if the transaction was processed via a mas-ter account.
decision Yes Enumeration This is the status of the transaction. One of the following is returned:• Accepted – the transaction was
processed.• 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 catego-rizes 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 StringMax = 1024
This is a human readable description of the code element.
authCode Optional StringMax = 20
This is the Authorization code assigned by the issuing bank and returned by Paysafe.
API Reference Guide for Web Services 1.0 3-47
Credit/Debit Card Transactions May 2019
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 pro-
cess.• 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 pro-vided 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 StringMax = 30
This is the tag/value pair returned as part of the detail element. See detail tag/value pairs on page 3-53 for details.value Optional String
Max = 1024
txnTime Yes dateTime This is the date and time the transac-tion was processed by Paysafe.
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
3-48
May 2019 Processing the response
duplicateFound Yes Boolean This indicates if this transaction is a duplicate transaction, if a duplicate check was requested.
duplicateTransactionResponse Optional CCTxnRespon-seV1
If a duplicate record was found, this element contains the details of that record.
tdsResponseThis element and its child ele-ments are returned only in response to the ccEnrollmentLookupRequestV1 transaction request.
acsURL Optional StringMax = 255
This is a fully qualified URL to redirect the consumer to complete the Pay-ment Authentication Request trans-action.
paymentRe-quest
Optional String This is an encoded Payment Authen-tication Request generated by the merchant authentication processing system (MAPS).
enrollmentSta-tus
Yes Enumeration This indicates whether or not the cardholder 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
authenticated 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 ele-ment in your ccAuthRequestV1 Authorization/Purchase request.However, if the cardholder is enrolled in 3D Secure, use the eci value in the tdsAuthenticateResponse element below.
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-49
Credit/Debit Card Transactions May 2019
tdsAuthenticateResponseThis element and its child ele-ments are returned only in response to the ccAuthenticateRequestV1 transaction request.
status Yes Enumeration This indicates the outcome of the authentication request. Possible values are:• Y – Cardholder successfully
authenticated with their Card Issuer.
• A – Cardholder authentication was attempted.
• N – Cardholder failed to success-fully authenticate with their Card Issuer.
• U – Authentication with the Card Issuer was unavailable.
• E – Error
cavv Optional StringMax = 80
This is the Cardholder Authentication Verification Value returned by the card issuer. Use this value for the indi-cator child element of the authentica-tion element in a ccAuthRequestV1.
signatureVerification
Yes Enumeration This indicates whether the 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 StringMax = 80
This is the transaction identifier returned in response to a ccAuthenti-cateRequestV1 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
authenticated 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-tional
Int This is the number of times Paysafe retried the transaction.
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
3-50
May 2019 Processing the response
originalCode Condi-tional
Int The original response code returned by the system that caused Paysafe to retry the transaction.
addendumResponse Optional This element allows Paysafe to return certain gateway-specific response values to the merchant.
service Condi-tional
StringMax = 50
This is the service provider who pro-vides the values for the tag/value pair.
detail Condi-tional
There may be multiple detail ele-ments, if required.
Child Element of detail
tag Condi-tional
StringMax = 30
This is the tag/value pair returned as part of the addendumResponse. See addendumResponse tag/value pairs on page 3-53 for details.value Condi-
tionalStringMax = 30
amount Optional StringMax=999999999.99
This is amount of the transaction request.
tranTypeNOTE: The tranType element is returned only in response to a ccTxnLookupRequestV1.
Optional Enumeration This is the type of transaction that was looked up. Possible values are:• A – Authorization• S – Settlement• P – Purchase• CR – Credit• PY – Payment• N – Independent Credit
cardEndingNOTE: The cardEnding element is returned only in response to a ccTxnLookupRequestV1.
Optional StringMax = 4
This is the last four digits of the card associated with this transaction.
cardExpiryNOTE: The cardExpiry element is returned only in response to a ccTxnLookupRequestV1.
Optional
month Condi-tional
Int Max = 2
This is the month the credit card expires.
year Condi-tional
IntLength = 4
This is the year the credit card expires.
netbanxReferenceNOTE: The netbanxReference element is returned only in response to a ccTxnLookupRequestV1.
Optional StringMax = 18
This is a transaction ID that identifies certain legacy transactions.
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 3-51
Credit/Debit Card Transactions May 2019
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);
}
txnLookupResultNOTE: The txnLookupResult element is returned only in response to a ccTxnLookupRe-questV1.
Condi-tional
This contains all the elements con-tained in the standard ccTxnRespon-seV1 that would have been returned for the initial request, in addition to the elements in this table that are identified as being returned only in response to a ccTxnLookupRequestV1 (e.g., tranType).
profile id Optional StringMax = 50
This is an internal ID returned in the response to the profile request, used to identify a customer.
card Condi-tional
Child Element of card
id Condi-tional
StringMax = 50
This is the card ID returned by Paysafe to identify the profile card.
lastFourDigits Condi-tional
Integer This is the last 4 digits of the card number associated with the profile.
paymentToken Condi-tional
StringMax = 50
This is a token generated by Paysafe that represents the card.
Table 3-12: ccTxnResponseV1 (Continued)
Element Child Element Required Type Description
3-52
May 2019 detail tag/value pairs
2. Process based on the decision element. You would insert handling code appropriate to your appli-cation. You can also look at the code element to provide more fine-grained control for your appli-cation. See Response codes on page B-1 for more details.
detail tag/value pairs
The following table contains the tag/value pairs supported for the data element.
addendumResponse tag/value pairs
The following table contains the tag/value pairs supported for the addendumResponse element.
Currency codes
Not all processing gateways support all detail tag/value pairs. Contact your account manager for more information.
Table 3-13: detail Tag/Value Pairs
Tag Value
CurrencyCode This value is returned if the addendumData tag element of the original transac-tion was set to SERVICE_REQUEST_CURRENCY.The value will be one of the currency codes in Table 3-15: Currency Codes on page 3-53.
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.
Not all processing gateways support all addendumResponse tag/value pairs. Contact your account manager for more information.
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.
Table 3-15: Currency Codes
Code Currency
ARS Argentine Peso
AUD Australian Dollar
BGN Bulgarian Lev
API Reference Guide for Web Services 1.0 3-53
Credit/Debit Card Transactions May 2019
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
Table 3-15: Currency Codes (Continued)
Code Currency
3-54
CHAPTER 4
Information Lookup ServiceTransactions
IntroductionThe 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.
Paysafe ILS WSDLs and linksWSDL:
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
The maximum range for most ILS requests is 24 hours.
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 requestsILS 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 ServiceILSLookupRequestV1 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 schemaAn ilsLookupRequestV1 has the following structure:
ilsLookupRequestV1 elementsThe ilsLookupRequestV1 document object contains the following elements:
Table 4-1: ilsLookupRequestV1 Elements
Element Child
Element
Required Type Description
merchantAccount accountNum Yes StringMax = 10
This is the merchant account number.
storeID Yes String Max = 80
This is the Paysafe store identifier, used to authenti-cate the request. It is defined by Paysafe and pro-vided to the merchant as part of the integration process.
storePwd Yes StringMax = 20
This is the Paysafe store password, used to authenti-cate the request. It is defined by Paysafe and pro-vided to the merchant as part of the integration process.
startDate year Yes IntMax = 9999
This is the year set for the search start.
API Reference Guide for Web Services 1.0 4-5
Information Lookup Service Transactions May 2019
month Yes Int Min = 1Max = 12
This is the month set for the search start.
day Yes IntMin = 1Max = 31
This is the day set for the search start.
hour Yes IntMin = 0Max = 23
This is the hour set for the search start.
minute Yes Int Min = 0Max = 59
This is the minute set for the search start.
second Yes IntMin = 0Max = 59
This is the second set for the search start.
endDate year Yes IntMax = 9999
This is the year set for the search end.
month Yes Int Min = 1Max = 12
This is the month set for the search end.
day Yes IntMin = 1Max = 31
This is the day set for the search end.
hour Yes IntMin = 0Max = 23
This is the hour set for the search end.
minute Yes Int Min = 0Max = 59
This is the minute set for the search end.
second Yes IntMin = 0Max = 59
This is the second set for the search end.
Table 4-1: ilsLookupRequestV1 Elements (Continued)
Element Child
Element
Required Type Description
4-6
May 2019 ilsLookupRequestV1 elements
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 ele-
ment)• 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 transac-tions 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.
Table 4-1: ilsLookupRequestV1 Elements (Continued)
Element Child
Element
Required Type Description
API Reference Guide for Web Services 1.0 4-7
Information Lookup Service Transactions May 2019
Processing the responseThe 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.
<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1"><decision>ACCEPTED</decision><description/><merchantAccount>10000400036</merchantAccount><currency>USD</currency><startDate>
<year>2011</year><month>2</month><day>5</day><hour>0</hour><minute>0</minute><second>0</second>
</startDate><endDate>
<year>2011</year><month>3</month><day>5</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate><txnType>
<code>authorizations</code><count>2</count>
</txnType><txnType><code>settlements</code>
<count>2</count></txnType><txnType>
<code>credits</code><count>1</count>
</txnType><txnType>
<code>chargebacks</code><count>1</count>
</txnType><transactions childFma='1000201930'>
<authorizations>100052493|FS|2011-02-05 09:57:54|test 123|111.65</authorizations><settlements>100052493|C|2011-02-05 09:57:55|test 123|111.65</settlements><credits>116883988|C|2011-03-02 15:17:09|test 123|5.0|102318569|USD</credits><chargebacks>368237|100052493|test 123|test 123|1111|2011-02-05|111.65|USD|111.65|30|40003610000160100052493|100000|1||2008-02-05</chargebacks>
</transactions><transactions childFma='1000201931'>
<authorizations>100052493|FS|2011-02-05 09:57:54|test 123|88.00</authorizations><settlements>100052493|C|2011-02-05 09:57:55|test 123|88.00</settlements>
</transactions>
4-8
May 2019 ilsLookupResponseV1 schema
</ilsLookupResponseV1>
The following is an example of a typical ilsLookupResponseV1 for a rejected transaction. In this exam-ple, an invalid merchant ID or password was submitted.
<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1"> <decision>REJECTED</decision> <description>Invalid Credentials</description></ilsLookupResponseV1>
ilsLookupResponseV1 schemaAn 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 rea-son.
• Rejected – the request was rejected, e.g., due to invalid merchant creden-tials.
description Yes StringMax = 1024
If the decision returned is Error or Rejected, this is a description of the error.
merchantAccount Yes StringMax = 10
This is the merchant account number.
API Reference Guide for Web Services 1.0 4-9
Information Lookup Service Transactions May 2019
currency Yes StringLength = 3
This is the currency of the merchant account.
startDate year Yes IntMax = 9999
This is the year set for the search start date.
month Yes Int Min = 1Max = 12
This is the month set for the search start date.
day Yes IntMin = 1Max = 31
This is the day set for the search start date.
hour Yes IntMin = 0Max = 23
This is the hour set for the search start date.
minute Yes Int Min = 0Max = 59
This is the minute set for the search start date.
second Yes IntMin = 0Max = 59
This is the second set for the search start date.
endDate year Yes IntMax = 9999
This is the year set for the search end date.
month Yes Int Min = 1Max = 12
This is the month set for the search end date.
day Yes IntMin = 1Max = 31
This is the day set for the search end date.
hour Yes IntMin = 0Max = 23
This is the hour set for the search end date.
minute Yes Int Min = 0Max = 59
This is the minute set for the search end date.
second Yes IntMin = 0Max = 59
This is the second set for the search end date.
Table 4-2: ilsLookupResponseV1 Elements (Continued)
Element Child Element Required Type Description
4-10
May 2019 ilsLookupResponseV1 schema
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 StringMax = 10
This is the child merchant account num-ber, and provided only if the account provided for the merchantAccount ele-ment is a master account.
authorizations Optional String Each instance of authorizations con-tains further details. See Authorizations response details on page 4-12 for a description.
settlements Optional String Each instance of settlements contains further 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-mandate-bacs contains further details. See Direct Debit response details on page 4-14 for a description.
dd-credit Optional String
dd-charge-bacs Optional String
dd-credit-bacs Optional String
dd-mandate-bacs Optional String
Table 4-2: ilsLookupResponseV1 Elements (Continued)
Element Child Element Required Type Description
API Reference Guide for Web Services 1.0 4-11
Information Lookup Service Transactions May 2019
Response element contentsPaysafe may without warning, when necessary, add additional detail elements to each of the transac-tion 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.
<ilsLookupResponseV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1">…
<transactions childFma='1000201930'><authorizations>100052493|FS|2011-02-05 09:57:54|test 123|111.65|added element|added element</authorizations><settlements>100052493|C|2011-02-05 09:57:55|test 123|111.65|added element|added element</settlements><credits>116883988|C|2011-03-02 15:17:09|test 123|5.0|102318569|USD|added element|added element</credits><chargebacks>368237|100052493|test 123|test 123|1111|2011-02-05|111.65|USD|111.65|30|40003610000160100052493|100000|1||2008-02-05|added element</chargebacks>
…</ilsLookupResponseV1>
Authorizations response detailsThe following details may returned for authorizations:
Settlements response detailsThe following details may be returned for settlements:
It is the merchant’s responsibility to ensure that their integration for the ilsLookupRe-questV1 is not adversely affected by the addition of extra detail elements by Paysafe.
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.
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
Credits response detailsThe following details may be returned for credits:
Chargebacks response detailsThe following details may be returned for chargebacks:
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.
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.
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.
Table 4-4: Settlements Response Details (Continued)
Parameter Description
API Reference Guide for Web Services 1.0 4-13
Information Lookup Service Transactions May 2019
Direct Debit response detailsThe following details may be returned for Direct Debit transactions:
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
Table 4-7: Direct Debit Response Details
Parameter Description
Echeck ID This is the confirmation number assigned by Paysafe to the transaction.
Table 4-6: Chargebacks Response Details (Continued)
Parameter Description
4-14
May 2019 Response element contents
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-mandate-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 net-work.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 effec-tive 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.
Table 4-7: Direct Debit Response Details (Continued)
Parameter Description
API Reference Guide for Web Services 1.0 4-15
Information Lookup Service Transactions May 2019
Reason codes
Chargeback reason codesOne of the following chargeback reason codes may be returned with a chargebacks response:
Table 4-8: Visa/MasterCard Chargeback Reason Codes
Card Brand Code Description
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
Retrieval request reason codesOne of the following retrieval request reason codes may be returned with a chargebacks response:
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
Table 4-9: Visa/MasterCard Retrieval Request Reason Codes
Card Brand Code Description
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
MC 41 Legal/Fraud Analysis – Signature Verification
Table 4-8: Visa/MasterCard Chargeback Reason Codes (Continued)
Card Brand Code Description
API Reference Guide for Web Services 1.0 4-17
Information Lookup Service Transactions May 2019
Discover chargeback and retrieval request reason codesOne of the following chargeback or retrieval request reason codes may be returned with a chargebacks response:
MC 42 Potential Chargeback or Compliance Documentation
MC 43 Legal/Fraud – Imprint Verification
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 can-cellation 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, RN2
Cardholder alleges that an expected credit from the merchant was not received or was insufficient in 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.
NC Cardholder challenges the validity of a card sale and no other reason code applies.
Table 4-9: Visa/MasterCard Retrieval Request Reason Codes (Continued)
Card Brand Code Description
4-18
May 2019 Discover chargeback and retrieval request reason codes
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 positive 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 com-ply 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 authorization response.
UA03 Cardholder or issuer challenges the validity of a card sale because the amount billed to the card-holder 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 authorization request.
UA99 Cardholder or issuer challenges the validity of a card sale and the acquirer or merchant did not com-ply with the applicable operating regulations in connection with the card sale.
R2 Credit not processed.
A Cardholder dispute, cardholder request draft.
Table 4-10: Discover Chargeback and Retrieval Request Codes (Continued)
Code Description
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
IntroductionIn addition to a standard Web Service–based call, you can also use the HTTP Post method to post trans-action 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 parameters.
• Email [email protected]
• Telephone 1-888-709-8753
Direct Debit requests
charge/creditFor 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:
<ddCheckRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><check>
<accountType>PC</accountType><bankName>Chase</bankName><checkNum>12</checkNum><accountNum>987654321</accountNum><routingNum>123456789</routingNum>
</check><billingDetails>
<checkPayMethod>WEB</checkPayMethod><firstName>Jane</firstName><lastName>Jones</lastName>
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.
API Reference Guide for Web Services 1.0 A-1
Using the HTTP Post Method May 2019
<street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails><sdk>
<version>1.0</version>platform>http</platform><provider>Merchant</provider>
</sdk></ddCheckRequestV1>
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 – chargeThis example shows a form version of a charge/credit request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Paysafe - Direct Debit Transaction</title><body><form NAME="Direct Debit" METHOD="post"
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"><b>Transaction Mode: </b><br><select name="txnMode"><option value="charge">Charge</option><option value="credit">Credit</option></select><br><br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10><ddCheckRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
See Table 2-2: ddCheckRequestV1 Elements on page 2-6 for a list and description of parame-ters to include in this request.
A-2
May 2019 charge/credit
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><check>
<accountType>PC</accountType><bankName>Chase</bankName><checkNum>12</checkNum><accountNum>987654321</accountNum><routingNum>123456789</routingNum>
</check><billingDetails>
<checkPayMethod>WEB</checkPayMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails><sdk>
<version>1.0</version><platform>http</platform><provider>Merchant</provider>
</sdk></ddCheckRequestV1></TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-3
Using the HTTP Post Method May 2019
updateShippingInfoFor 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:
<ddShippingRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><carrier>FEX</carrier><trackingNumber>555666888999</trackingNumber><confirmationNumber>123456</confirmationNumber><shipMethod>T</shipMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</ddShippingRequestV1>
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 – updateShippingInfoThis example shows a form version of an updateShippingInfo request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Direct Debit Transaction</title><body><form NAME="Direct Debit" METHOD="post"
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"><input type=hidden name="txnMode" value="updateShippingInfo" >
See Table 2-4: ddShippingRequestV1 Elements on page 2-14 for a list and description of parameters to include in this request.
A-4
May 2019 updateShippingInfo
<br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10>
<ddShippingRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><carrier>FEX</carrier><trackingNumber>555666888999</trackingNumber><confirmationNumber>123456</confirmationNumber><shipMethod>T</shipMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</ddShippingRequestV1></TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-5
Using the HTTP Post Method May 2019
ddLookupRequestFor 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:
<ddLookupRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><startDate>
<year>2012</year><month>1</month><day>1</day><hour>12</hour><minute>1</minute><second>1</second>
</startDate><endDate>
<year>2012</year><month>1</month><day>1</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate></<ddLookupRequestV1>
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 – lookupRequestThis example shows a form version of a lookupRequest – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Direct Debit Transaction</title><body><form NAME="Direct Debit" METHOD="post"
See Table 2-5: ddLookupRequestV1 Elements on page 2-18 for a list and description of parameters to include in this request.
A-6
May 2019 Mandate request
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"><input type=hidden name="txnMode" value="lookup" >
<br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10>
<ddLookupRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><startDate>
<year>2012</year><month>1</month><day>1</day><hour>12</hour><minute>1</minute><second>1</second>
</startDate><endDate>
<year>2012</year><month>1</month><day>31</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate></<ddLookupRequestV1>
</TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 requestFor 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:
<ddMandateRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-7
Using the HTTP Post Method May 2019
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><check>
<bankName>Chase</bankName><accountNum>987654321</accountNum><routingNum>123456</routingNum>
</check><billingDetails>
<checkPayMethod>WEB</checkPayMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>Cambridge</city><country>UK</country><zip>CB12345</zip><phone>1222 444000</phone><email>[email protected]</email>
</billingDetails><autoSend>Y</autoSend>
</ddMandateRequestV1>
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 requestThis example shows a form version of a mandate request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Paysafe - Direct Debit Test</title><body><form NAME="Direct Debit" METHOD="post"
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"<input type=hidden name="txnMode" value="mandate" ><br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10><ddMandateRequestV1
See Table 2-6: ddMandateRequestV1 Elements on page 2-23 for a list and description of parameters to include in this request.
A-8
May 2019 Change status request
xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1"><merchantAccount>
<accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><check>
<bankName>Chase</bankName><accountNum>987654321</accountNum><routingNum>123456</routingNum>
</check><billingDetails>
<checkPayMethod>WEB</checkPayMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>Cambridge</city><country>UK</country><zip>CB12345</zip><phone>1222 444000</phone><email>[email protected]</email>
</billingDetails><autoSend>Y</autoSend>
</ddMandateRequestV1></TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 requestFor 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:
<ddChangeStatusRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><status>C</status>
</ddChangeStatusRequestV1>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
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 requestThis example shows a form version of a change status request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Paysafe - Direct Debit Transaction</title><body><form NAME="Direct Debit" METHOD="post"
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"<input type=hidden name="txnMode" value="changeStatus" ><br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10><ddChangeStatusRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><status>C</status>
</ddChangeStatusRequestV1></TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 requestFor more information on this request type, see Building mandate update requests on page 2-28.
See Table 2-8: ddChangeStatusRequestV1 Elements on page 2-27 for a list and description of parameters to include in this request.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
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:
<ddUpdateMandateRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><mandateReference>PDESTEST7A</mandateReference><accountNum>NL77ABNA0574908765</accountNum><routingNum>ABNANL2A</routingNum>
</ddUpdateMandateRequestV1>
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 requestThis example shows a form version of a mandate update request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Paysafe - Direct Debit Transaction</title><body><form NAME="Direct Debit" METHOD="post"
ACTION="https://webservices.optimalpayments.com/directdebitWS/DirectDebitServlet/v1"<input type=hidden name="txnMode" value="updateMandate" ><br><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10><ddUpdateMandateRequestV1 xmlns="http://www.optimalpayments.com/directdebit/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><mandateReference>PDESTEST7A</mandateReference><accountNum>NL77ABNA0574908765</accountNum>
See Table 2-9: ddUpdateMandateRequestV1 Elements on page 2-30 for a list and description of parameters to include in this request.
API Reference Guide for Web Services 1.0 A-11
Using the HTTP Post Method May 2019
<routingNum>ABNANL2A</routingNum></ddUpdateMandateRequestV1></TEXTAREA> <br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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/VerificationFor 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:
<ccAuthRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><card>
<cardNum>4653111111111111</cardNum><cardExpiry>
<month>11</month><year>2008</year>
</cardExpiry><cardType>VI</cardType><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
</card><authentication>
<indicator>05</indicator><cavv>AAABB4WZlQAAAAAAcJmVENiWiV+=</cavv><xid>Q2prWUI2RFNBc3FOTXNlem50eWY=</xid>
</authentication><billingDetails>
<cardPayMethod>WEB</cardPayMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>LA</city>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
A-12
May 2019 Purchase/Authorization/Verification
<state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails><shippingDetails>
<carrier>FEX</carrier><shipMethod>T</shipMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>44 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</shippingDetails><recurring>
<recurringIndicator>I</recurringIndicator><originalConfirmationNumber>115147689</originalConfirmationNumber>
</recurring><customerIP>127.0.0.1</customerIP><productType>M</productType><addendumData>
<tag>CUST_ACCT_OPEN_DATE</tag><value>20041012</value>
</addendumData><addendumData>
<tag>MERCHANT_COUNTRY_CODE</tag><value>US</value>
</addendumData><addendumData>
<tag>SERVICE_REQUEST_CURRENCY</tag><value>on</value>
</addendumData></ccAuthRequestV1>
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 – AuthorizationThis example shows a form version of a credit card Authorization request – containing the example above – that you could post to Paysafe.
See Table 3-2: ccAuthRequestV1 Elements on page 3-8 for a list and description of parameters to include in this request.
API Reference Guide for Web Services 1.0 A-13
Using the HTTP Post Method May 2019
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Credit Card Test</title><body><form NAME="Credit Card" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccAuthorize" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccAuthRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><card>
<cardNum>4653111111111111</cardNum><cardExpiry>
<month>11</month><year>2008</year>
</cardExpiry><cardType>VI</cardType><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
</card><authentication>
<indicator>05</indicator><cavv>AAABB4WZlQAAAAAAcJmVENiWiV+=</cavv><xid>Q2prWUI2RFNBc3FOTXNlem50eWY=</xid>
</authentication><billingDetails>
<cardPayMethod>WEB</cardPayMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails><shippingDetails>
<carrier>FEX</carrier><shipMethod>T</shipMethod><firstName>Jane</firstName><lastName>Jones</lastName><street>44 Main Street</street>
To make this a Purchase or Verification request, just modify the txnMode value “ccAuthorize” – in the line “<input type=hidden name="txnMode" value="ccAuthorize" >” below – to “ccPurchase” or “ccVeri-fication”, respectively.
A-14
May 2019 Authorization Reversal
<city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</shippingDetails><recurring>
<recurringIndicator>I</recurringIndicator><originalConfirmationNumber>115147689</originalConfirmationNumber>
</recurring><customerIP>127.0.0.1</customerIP><productType>M</productType><addendumData>
<tag>CUST_ACCT_OPEN_DATE</tag><value>20041012</value>
</addendumData><addendumData>
<tag>MERCHANT_COUNTRY_CODE</tag><value>US</value>
</addendumData><addendumData>
<tag>SERVICE_REQUEST_CURRENCY</tag><value>on</value>
</addendumData></ccAuthRequestV1> </TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 ReversalFor more information on these request types, see Building Authorization Reversal requests on page 3-18.
To send a credit card Authorization Reversal transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccAuthReversalRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-15
Using the HTTP Post Method May 2019
<confirmationNumber>115147689</confirmationNumber><merchantRefNum>AR2</merchantRefNum><reversalAmount>18.00</reversalAmount>
</ccAuthReversalRequestV1>
2. Include this transaction request in an HTTP Post (see HTML example – Authorization Reversal on page A-16).
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 ReversalThis example shows a form version of a credit card Authorization Reversal request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Reverse Authorization Transaction</title><body><form NAME="Credit Card" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccAuthorizeReversal" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccAuthReversalRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>115147689</confirmationNumber><merchantRefNum>AR2</merchantRefNum><reversalAmount>18.00</reversalAmount>
</ccAuthReversalRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Table 3-4: ccAuthReversalRequestV1 Elements on page 3-20 for a list and description of parame-ters to include in this request.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
A-16
May 2019 Settlement/Credit
See Sample HTTP Post on page A-30 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/CreditFor more information on these request types, see Building Settlement/Credit requests on page 3-21.
To send a credit card Settlement/Credit transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccPostAuthRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><addendumData>
<tag>MERCHANT_DATA</tag><value>MERCHANT_DATA</value>
</addendumData></ccPostAuthRequestV1>
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 – SettlementThis example shows a form version of a credit card Settlement request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Credit Card Test</title><body><form NAME="Credit Card" METHOD="post"
See Table 3-5: ccPostAuthRequestV1 Elements on page 3-23 for a list and description of parameters to include in this request.
To make this a Credit request, just modify the txnMode value “ccSettlement” – in the line “<input type=hidden name="txnMode" value="ccSettlement" >” below – to “ccCredit”.
API Reference Guide for Web Services 1.0 A-17
Using the HTTP Post Method May 2019
ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccSettlement" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccPostAuthRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><addendumData>
<tag>MERCHANT_DATA</tag><value>MERCHANT_DATA</value>
</addendumData></ccPostAuthRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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/PurchaseFor more information on these request types, see Building Stored Data Requests on page 3-25.
To send a Stored Data Authorization/Purchase transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccStoredDataRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><confirmationNumber>123456</confirmationNumber><amount>18.00</amount><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
A-18
May 2019 Stored Data Authorization/Purchase
</ccStoredDataRequestV1>
2. Include this transaction request in an HTTP Post (see HTML example – Stored Data Authorization on page A-19).
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.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Credit Card Test</title><body><form NAME="Credit Card" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccStoredDataAuthorize" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccStoredDataRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><confirmationNumber>123456</confirmationNumber><amount>18.00</amount><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
</ccStoredDataRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Table 3-6: ccStoredDataRequestV1 Elements on page 3-27 or a list and description of parameters to include in this request.
To make this a Stored Data Purchase request, just modify the txnMode value “ccStoredDataAuthorize” – in the line “<input type=hidden name="txnMode" value="ccStoredDataAuthorize" >” below – to “ccStoredDataPurchase”.
API Reference Guide for Web Services 1.0 A-19
Using the HTTP Post Method May 2019
See Sample HTTP Post on page A-30 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 CreditFor more information on these request types, see Building Cancel requests on page 3-28.
To cancel a credit card Settle/Credit/Payment/Independent Credit request via HTTP Post:
1. Create a transaction request like the following example:
<ccCancelRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><addendumData>
<tag>MERCHANT_DATA</tag><value>MERCHANT_DATA</value>
</addendumData></ccCancelRequestV1>
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.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Table 3-7: ccCancelRequestV1 Elements on page 3-30 for a list and description of parameters to include in this request.
To make this a Cancel Credit, Cancel Payment, or Cancel Independent Credit request, just modify the txnMode value “ccCancelSettle” – in the line “<input type=hidden name="txnMode" value="ccCancel-Settle" >” below – to “ccCancelCredit”, “ccCancelPayment”, or “ccCancelIndependentCredit”, respec-tively.
A-20
May 2019 Payment request
<html><title>Credit Card Test</title><body><form NAME="Credit Card" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccCancelSettle" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccCancelRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><addendumData>
<tag>MERCHANT_DATA</tag><value>MERCHANT_DATA</value>
</addendumData></ccCancelRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 requestFor more information on this request type, see Building Payment/Independent Credit requests on page 3-31.
To make a Payment request via HTTP Post:
1. Create a transaction request like the following example:
<ccPaymentRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><card>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-21
Using the HTTP Post Method May 2019
<cardNum>4653111111111111</cardNum><cardExpiry>
<month>11</month><year>2008</year>
</cardExpiry><cardType>VI</cardType><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
</card><billingDetails>
<cardPayMethod>WEB</cardPayMethod><firstName>jane</firstName><lastName>jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails></ccPaymentRequestV1>
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
3. Send the HTTP Post to the following URL:
https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – PaymentThis example shows a form version of a credit card Payment request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title>CC Payment</title></head>
<body><h1> Credit Card Webservice Tester </h1><form NAME="creditcard" id="creditcard" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1">
See Table 3-8: ccPaymentRequestV1 Elements on page 3-33 for a list and description of parameters to include in this request.
To make this an Indpendent Credit request, just modify the txnMode value “ccPayment” – in the line “<input type=hidden name="txnMode" value="ccPayment" >” below – to “ccIndependent Credit”.
A-22
May 2019 Credit card Information Lookup
<input type=hidden name="txnMode" value="ccPayment" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccPaymentRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>10.00</amount><card>
<cardNum>4653111111111111</cardNum><cardExpiry>
<month>11</month><year>2008</year>
</cardExpiry><cardType>VI</cardType><cvdIndicator>1</cvdIndicator><cvd>111</cvd>
</card><billingDetails>
<cardPayMethod>WEB</cardPayMethod><firstName>jane</firstName><lastName>jones</lastName><street>123 Main Street</street><city>LA</city><state>CA</state><country>US</country><zip>90210</zip><phone>555-555-5555</phone><email>[email protected]</email>
</billingDetails></ccPaymentRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 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 LookupFor more information on this request type, see Building Transaction Lookup requests on page 3-36.
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-23
Using the HTTP Post Method May 2019
To send a credit card Information Lookup transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccTxnLookupRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><startDate>
<year>2012</year><month>1</month><day>1</day><hour>12</hour><minute>1</minute><second>1</second>
</startDate><endDate>
<year>2012</year><month>1</month><day>1</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate></ccTxnLookupRequestV1>
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
HTML example – Information Lookup<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Information Lookup</title>
<form NAME="Information Lookup" METHOD="post" ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1">
<input type=hidden name="txnMode" value="ccTxnLookup" ><b>XML Message body:</b>
See Table 3-9: ccTxnLookupRequestV1 Elements on page 3-38 for a list and description of parameters to include in this request.
A-24
May 2019 Enrollment Lookup
<TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=25 >
<ccTxnLookupRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><merchantRefNum>Ref-12345</merchantRefNum><startDate>
<year>2012</year><month>1</month><day>1</day><hour>12</hour><minute>1</minute><second>1</second>
</startDate><endDate>
<year>2012</year><month>1</month><day>1</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate></<ccTxnLookupRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Enrollment LookupFor more information on this request type, see Building Enrollment Lookup requests on page 3-40.
To send a credit card Enrollment Lookup transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccEnrollmentLookupRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1"> <merchantAccount> <accountNum>12345678</accountNum> <storeID>MyStoreID</storeID> <storePwd>MyStorePWD</storePwd>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
API Reference Guide for Web Services 1.0 A-25
Using the HTTP Post Method May 2019
</merchantAccount> <merchantRefNum>Ref-12345</merchantRefNum> <amount>21.00</amount> <card> <cardNum>4000000000000002</cardNum> <cardExpiry> <month>01</month> <year>2011</year> </cardExpiry> <cardType>VI</cardType> </card> </ccEnrollmentLookupRequestV1>
2. Include this transaction request in an HTTP Post (see HTML example – Enrollment Lookup on page A-26).
This HTTP Post must include two parameters:
• txnMode – ccTDSLookup
• txnRequest – the transaction request above
3. Send the HTTP Post to the following URL:
https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
HTML example – Enrollment Lookup<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Enrollment Lookup</title>
<form NAME="Enrollment Lookup" METHOD="post" ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1">
<input type=hidden name="txnMode" value="ccTDSLookup" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=25 >
<ccEnrollmentLookupRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>MyStoreID</storeID><storePwd>MyStorePWD</storePwd>
</merchantAccount><merchantRefNum>Ref-12345</merchantRefNum><amount>21.00</amount><card>
<cardNum>4653111111111111</cardNum><cardExpiry>
<month>01</month>
See Table 3-10: ccEnrollmentLookupRequestV1 Elements on page 3-42 for a list and description of parameters to include in this request.
A-26
May 2019 Authentication
<year>2011</year></cardExpiry><cardType>VI</cardType>
</card></ccEnrollmentLookupRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
AuthenticationFor more information on this request type, see Building Authentication requests on page 3-43.
To send a credit card Authentication transaction request via HTTP Post:
1. Create a transaction request like the following example:
<ccAuthenticateRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><paymentResponse>myPaymentResponse</paymentResponse>
</ccAuthenticateRequestV1>
2. Include this transaction request in an HTTP Post (see HTML example – Authentication on page A-28).
This HTTP Post must include two parameters:
• txnMode – ccTDSAuthenticate
• txnRequest – the transaction request above
3. Send the HTTP Post to the following URL:
https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
See Table 3-11: ccAuthenticateRequestV1 Elements on page 3-44 for a list and description of parame-ters to include in this request.
API Reference Guide for Web Services 1.0 A-27
Using the HTTP Post Method May 2019
HTML example – AuthenticationThis example shows a form version of a credit card Authentication request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Credit Card Test</title><body><form NAME="Credit Card" METHOD="post"ACTION="https://webservices.optimalpayments.com/creditcardWS/CreditCardServlet/v1"><input type=hidden name="txnMode" value="ccTDSAuthenticate" ><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ccAuthenticateRequestV1 xmlns="http://www.optimalpayments.com/creditcard/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/creditcard/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><confirmationNumber>123456</confirmationNumber><paymentResponse>myPaymentResponse</paymentResponse>
</ccAuthenticateRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Information Lookup Service requestsFor more information on this request type, see Building ILS requests on page 4-3.
To send an ILS request via HTTP Post:
1. Create a transaction request like the following example:
<ilsLookupRequestV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/ils/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><startDate>
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
A-28
May 2019 HTML example - ILS
<year>2008</year><month>03</month><day>05</day><hour>00</hour><minute>00</minute><second>00</second>
</startDate><endDate>
<year>2008</year><month>03</month><day>05</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate><type>authorizations</type><type>settlements</type><type>credits</type><type>chargebacks</type>
</ilsLookupRequestV1>
2. Include this transaction request in an HTTP Post (see HTML example - ILS on page A-29).
3. Send the HTTP Post to the following URL:
https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1
HTML example - ILS This example shows a form version of an ILS request – containing the example above – that you could post to Paysafe.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><title>Information Lookup Service</title><body><form NAME="ILS" METHOD="post"ACTION="https://webservices.optimalpayments.com/ilsWS/IlsServlet/v1"><b>XML Message body:</b><TEXTAREA class="xmlbox" name="txnRequest" COLS=100 ROWS=10 ><ilsLookupRequestV1 xmlns="http://www.optimalpayments.com/ils/xmlschema/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.optimalpayments.com/ils/xmlschema/v1">
<merchantAccount><accountNum>12345678</accountNum><storeID>myStoreID</storeID><storePwd>myStorePWD</storePwd>
</merchantAccount><startDate>
<year>2008</year><month>03</month><day>05</day><hour>00</hour><minute>00</minute><second>00</second>
See Table 4-1: ilsLookupRequestV1 Elements on page 4-5 for a list and description of parameters to include in this request.
API Reference Guide for Web Services 1.0 A-29
Using the HTTP Post Method May 2019
</startDate><endDate>
<year>2008</year><month>03</month><day>05</day><hour>23</hour><minute>59</minute><second>59</second>
</endDate><type>authorizations</type><type>settlements</type><type>credits</type><type>chargebacks</type>
</ilsLookupRequestV1></TEXTAREA><br><input TYPE=submit class=input VALUE="Send Request"></form></body></html>
See Sample HTTP Post on page A-30 to see what this would look like viewed with a browser. Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Sample HTTP PostThis is what the HTTP Post examples of the transaction types described in this chapter would look like viewed in a browser:
Clicking the Send Request button sends the transaction via HTTP Post to Paysafe.
Sample HTTP Post responsesPaysafe returns a response like the following for a successful transaction request:
The maximum file size supported is 100K. If your HTTP Post exceeds 100K it will fail.
A-30
May 2019 Sample HTTP Post responses
Paysafe returns a response like the following for a failed transaction request:
For an explanation of the elements in the response, see Processing the response on page 3-46. For an explanation of error codes, see Response codes on page B-1.
API Reference Guide for Web Services 1.0 A-31
Using the HTTP Post Method May 2019
A-32
APPENDIX B
Response Codes
OverviewPaysafe Web Services can return different types of code if a transaction attempt fails:
• Response codes
• Action codes
• Return codes
Response codes The following table describes the response codes that could be returned by Paysafe Web Services.
Table B-1: Response Codes
Response Code Action Description
1000 D An internal error occurred. Please contact Technical Support before retrying the transaction.
1001 R An error occurred with the external processing gateway. Please retry the transaction.
1002 R An internal error occurred. Please retry the transaction.
1003 D An error occurred with the external processing gateway. Do not retry the transaction. Contact Technical Support for more information.
1004 M Your account is not enabled for this transaction type. Please verify your parameters and retry the transaction.
1006 D An error occurred with the external processing gateway. Do not retry the transaction. Contact Technical Support for more information.
1007 R An internal error occurred. Please retry the transaction.
1008 D An internal error occurred. Do not retry the transaction. Contact Technical Support for more infor-mation.
1018 D The external processing gateway has reported the transaction is unauthorized. Do not retry the transaction. Contact Technical Support for more information.
1028 M The external processing gateway has reported invalid data. Please verify your parameters and retry the transaction.
1043 D The external processing gateway has reported the account type is invalid. Do not retry the trans-action. Contact Technical Support for more information.
1060 D The external processing gateway has reported a limit has been exceeded. Do not retry the trans-action.
1078 R The external processing gateway has reported a system error. Please retry the transaction.
1087 D The external processing gateway has rejected the transaction. Do not retry the transaction. Con-tact Technical Support for more information.
1101 M You submitted an unsupported card/currency combination with your request.
API Reference Guide for Web Services 1.0 B-1
Response Codes May 2019
2000 D The echeck status cannot be found.
2001 C You submitted a request containing a bank account, amount, and check number already used together in a request within the last 24 hours.
2002 M The echeck request cannot be found. Please verify your parameters and retry.
2003 M The payment type you provided conflicts with the bank account type you provided. Please verify your parameters and retry the transaction.
2004 D The echeck transaction cannot be found.
2005 M An internal error occurred. Please verify your parameters and retry the transaction.
2006 C You have submitted a Decline transaction in response to a Settlement attempt.
2007 M The payment type included with your request cannot be used in Credit transaction mode. Please verify your parameters and retry the request.
2008 C You have submitted an invalid routing number. Please verify your parameter and retry the trans-action.
2009 C You have submitted an invalid bank account number. Please verify your parameter and retry the transaction.
2010 C You have submitted an invalid check number. Please verify your parameter and retry the transac-tion.
2011 M You have submitted a mandate reference that does not exist. Please verify your parameter and retry the transaction.
2012 M You have submitted a mandate reference that is not active yet. Please resubmit your request after the mandate becomes active or resubmit your request including the txnDate element with a date after: <date>
2013 M You have submitted an invalid mandate reference. Please verify your parameter and retry the transaction.
2014 M The mandate reference is already in use for the specified bank account information. Please spec-ify a different mandate reference.
2016 M The paymentToken element cannot be used together with the check element or the billingDetails element.
2017 M The payment token bank scheme does not match the merchant account bank scheme.
2100 D You have attempted to refund a Charge transaction that is not in a completed state. Do not retry the transaction.
2101 R The requested refund amount exceeds the remaining Charge amount. Please verify your parame-ters and retry the transaction.
2102 R You have submitted an invalid bank country in your request. Please verify your parameter and retry the transaction.
2500 D A suitable merchant account could not be found for this request. Do not retry the transaction. Contact Technical Support for more information.
2501 D An internal error occurred. Do not retry the transaction. Contact Technical Support for more infor-mation.
2502 M The authentication failed for your transaction request. Either your credentials were entered incorrectly or your request was tampered with. Please verify your request and retry the transac-tion.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-2
May 2019 Response codes
2503 M You submitted an invalid shop ID. It must be a numeric value.
2504 M You submitted a shop ID for which a shop does not exist. Please verify your parameters and retry the transaction.
2505 M No merchant account could be found for the currency you submitted. Please verify your parame-ters and retry the transaction.
2506 M More than one merchant account was found for the currency you submitted. Please provide a merchant account number and retry the request.
2507 M The merchant account submitted does not correspond to the shop ID you submitted. Please ver-ify your parameters and retry the transaction.
2508 M You submitted a request that is missing the encodedMessage parameter. Please verify your parameters and retry the transaction.
2509 M You submitted a request that has an invalid encodedMessage parameter. The encodedMessage could not be Base64 decoded. Please verify your parameters and retry the request.
2510 M You submitted an invalid XML request. Please verify your request and retry the transaction.
2511 R An internal error occurred. Please retry the transaction. Contact Technical Support if the error persists.
2512 M You submitted a request that is missing the signature parameter. Please verify your parameters and retry the transaction.
2513 M You submitted a request that is missing the Shop ID parameter. Please verify your parameters and retry the transaction.
2514 D An internal error occurred. Your merchant credentials could not be found. Do not retry the trans-action. Contact Technical Support for more information.
2515 R An internal error occurred. Please retry the transaction.
2516 D An internal error occurred. Do not retry the transaction. Please contact Technical Support.
2517 D An internal error occurred. Do not retry the transaction. Please contact Technical Support.
2518 R An internal error occurred. Please retry the transaction. Contact Technical Support if the error persists.
2519 D You submitted a request for a shop that is disabled. Do not retry the transaction.
2520 M The cartItem and feeItem amounts do not equal the totalAmount. Please verify your parameters and retry the transaction.
2521 D An internal error occurred. Your shop is not configured properly. Do not retry the transaction. Contact Technical Support for more information.
2523 R An internal error occurred. Please retry the transaction. Contact Technical Support if the error persists.
2524 D An internal error occurred. The customer profile is not configured properly. Do not retry the trans-action. Contact Technical Support for more information.
2525 M The customer profile associated with the token provided could not be located. Please verify your parameters and retry the transaction.
2526 R An internal profile management error occurred and your request could not be processed. Please retry the transaction. Contact Technical Support if the error persists.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-3
Response Codes May 2019
2527 M You submitted a request with an unsupported locale. Please verify your parameters and retry the transaction.
2528 M You submitted a request with a merchant customer ID that is not associated with the customer token provided. Please verify your parameters and retry the transaction.
2529 R An internal error occurred. Please retry the transaction.
2530 D An internal error occurred. Do not retry the transaction. Contact Technical Support for more infor-mation.
2531 M A customer profile with the same merchant customer ID already exists. Please verify your param-eters and retry the transaction.
2532 D Your shop is not configured to process any payments. Do not retry the transaction. Contact Tech-nical Support for more information.
2533 D Your shop is not configured to process the selected payment method. Do not retry the transac-tion. Contact Technical Support for more information.
2534 M The customer profile associated with the token you provided is not active. Please verify your parameters and ensure the customer status is active and then retry the transaction.
2535 M The customer profile associated with the token you provided has a bank account that is not vali-dated. Please verify your parameters or have your customer validate their account and then retry the transaction.
2536 D The transaction was declined because the maximum number of attempts has been reached. Do not retry the transaction.
2537 D The bank account validation failed because the maximum number of attempts has been reached. Do not retry the transaction.
2538 D The customer entered an invalid micro deposit amount.
2539 R An internal error occurred. Please retry the transaction. Contact Technical Support if the error persists.
2540 M The merchant reference number already exists. Please verify your parameters and retry the trans-action.
2541 R An internal error occurred when sending the micro deposit transaction. Please retry the transac-tion. Contact Technical Support if the error persists.
2542 D The customer profile validation failed the AVS check.
2543 M The customer has a status that cannot be validated. Please reset the customer status before retry-ing the transaction.
2544 D The customer profile does not have the credit card information required for validation.
2445 D The customer tried to register an EFT bank account that is already used by another customer. Do not retry the transaction.
2546 D The customer tried to register a credit card that is already used by another customer. Do not retry the transaction.
2547 M The customer profile associated with the token you provided does not have a credit card. Please verify your parameters, and retry the transaction.
2548 M The customer profile used for this transaction has not been created. Please verify your parame-ters and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-4
May 2019 Response codes
2549 M Your shop is not configured to register a bank account for the country you submitted. Please verify your parameters and retry the transaction.
2550 M The customer profile associated with the token you provided does not have a registered bank account. Please verify your parameters and retry the transaction.
2551 M You submitted a request that contains an invalid payment method. Please verify your parameters and retry the transaction.
2552 M You submitted a request that contains an invalid shop request ID. Please verify your parameters and retry the transaction.
2553 D Our system cannot find the successful enrollment response associated with your shop request ID. Do not retry the transaction. Contact Technical Support for more information.
2554 M The customer profile associated with the token you provided is disabled. Please verify your parameters and ensure the customer status is active, and retry the transaction.
2555 M The payment token is not associated with the customer profile you provided. Please verify your parameters and retry the transaction.
2556 M The credit card selected for this transaction is not active. Please verify your parameters and retry the transaction.
2557 M The confirmation number included in this request could not be found. Please verify this parame-ter and retry the transaction.
2558 M The transaction cannot be cancelled. Please verify your parameters and ensure you are attempt-ing to cancel the correct transaction. If the error persists, contact Technical Support.
2701 None The Equifax validation was accepted with the condition that the customer’s request should be verified.
2702 R An internal error has occurred while processing an Equifax transaction. Retry the transaction. Contact Technical Support if the error persists.
2703 R Some or all of the Equifax databases are down. Retry the transaction. Contact Technical Support if the error persists.
2704 D The Equifax validation was rejected. Do not retry the transaction.
2705 R The Equifax validation was rejected and should be treated manually. The merchant can contact the customer directly.
2706 R The Equifax validation was rejected due to invalid input. Please verify your parameters and retry the transaction.
2707 R The Equifax validation was rejected due to an invalid address. Please verify your parameters and retry the transaction.
2708 R An internal error occurred. The Equifax response codes are missing. Please verify your parameters and retry the transaction.
2709 D The bank rejected the transaction. It could not process the request.
2710 M No email template is set up, so no email could be sent to confirm the transaction.
2711 D The validation was rejected for the profile update. Do not retry the transaction.
2712 D The request was rejected because the consumer is in a watch list.
3001 C You submitted an unsupported card type with your request. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-5
Response Codes May 2019
3002 C You submitted an invalid card number or brand or combination of card number and brand with your request. Please verify these parameters and retry the transaction.
3003 C You submitted an incorrect value for the cvdIndicator parameter with your request. Please verify this parameter and retry the transaction.
3004 C You have requested an AVS check. Please ensure that the zip/postal code is provided.
3005 C You submitted an incorrect value for the cvd parameter with your request. Please verify this parameter and retry the transaction.
3006 C You submitted an expired credit card number with your request. Please verify this parameter and retry the request.
3007 D Your request has failed the AVS check. Note that the amount may have been reserved on the cus-tomer’s card and will be released in 3-5 business days. Please ensure the billing address is accu-rate before retrying the transaction.
3008 D You submitted a card type for which the merchant account is not configured.
3009 D Your request has been declined by the issuing bank.
3011 D Your request has been declined by the issuing bank because the card used is a restricted card. Contact the cardholder’s credit card company for further investigation.
3012 D Your request has been declined by the issuing bank because the credit card expiry date submitted is invalid.
3013 D Your request has been declined by the issuing bank due to problems with the credit card account.
3014 D Your request has been declined – the issuing bank has returned an unknown response. Contact the cardholder’s credit card company for further investigation.
3015 D The bank has requested that you process the transaction manually by calling the cardholder’s credit card company.
3016 D The bank has requested that you retrieve the card from the cardholder – it may be a lost or stolen card.
3017 C You submitted an invalid credit card number with your request. Please verify this parameter and retry the transaction.
3018 R The bank has requested that you retry the transaction.
3019 C Your request has failed the CVD check. Please note that the amount may still have been reserved on the customer’s card, in which case it will be released in from 3 to 5 business days. Please ensure the CVD value is accurate before retrying the transaction.
3020 R The bank has requested that you retry the transaction.
3021 M The confirmation number included in this request could not be found. Please verify this parame-ter and retry the transaction.
3022 D The card has been declined due to insufficient funds.
3023 D Your request has been declined by the issuing bank due to its proprietary card activity regula-tions.
3024 D Your request has been declined because the issuing bank does not permit the transaction for this card.
3025 R The external processing gateway has reported invalid data. Please verify your parameters and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-6
May 2019 Response codes
3026 D The external processing gateway has reported the account type is invalid. Do not retry the trans-action. Contact Technical Support for more information.
3027 D The external processing gateway has reported a limit has been exceeded. Do not retry the trans-action.
3028 R The external processing gateway has reported a system error. Please retry the transaction.
3029 D The external processing gateway has rejected the transaction. Do not retry the transaction. Con-tact Technical Support for more information.
3030 D The external processing gateway has reported the transaction is unauthorized. Do not retry the transaction. Contact Technical Support for more information.
3031 M The confirmation number you submitted with your request references a transaction that is not on hold. Please verify this parameter and retry the transaction.
3032 D Your request has been declined by the issuing bank or external gateway because the card is prob-ably in one of their negative databases.
3035 D Your request has been declined due to exceeded PIN attempts.
3036 D Your request has been declined due to an invalid issuer.
3037 D Your request has been declined because it is invalid.
3038 D Your request has been declined due to customer cancellation.
3039 D Your request has been declined due to an invalid authentication value.
3040 D Your request has been declined because the request type is not permitted on the card.
3041 D Your request has been declined due to a timeout.
3042 D Your request has been declined due to a cryptographic error.
3044 D You have submitted a duplicate request.
3045 D You submitted an invalid date format for this request.
3046 D The transaction was declined because the amount was set to zero.
3047 D The transaction was declined because the amount exceeds the floor limit.
3048 D The transaction was declined because the amount is less than the floor limit.
3049 D The bank has requested that you retrieve the card from the cardholder – the credit card has expired.
3050 D The bank has requested that you retrieve the card from the cardholder – fraudulent activity is sus-pected.
3051 D The bank has requested that you retrieve the card from the cardholder – contact the acquirer for more information.
3052 D The bank has requested that you retrieve the card from the cardholder – the credit card is restricted.
3053 D The bank has requested that you retrieve the card from the cardholder – please call the acquirer.
3054 D The transaction was declined due to suspected fraud.
3200 M You have submitted an invalidly formatted authorization ID for this settlement. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-7
Response Codes May 2019
3201 M The authorization ID included in this settlement request could not be found. Please verify this parameter and retry the transaction.
3202 D You have exceeded the maximum number of settlements allowed. Contact Technical Support for more information.
3203 M The authorization is either fully settled or cancelled.
3204 M The requested settlement amount exceeds the remaining authorization amount.
3205 M The authorization you are attempting to settle has expired.
3206 D The external processing gateway has rejected the transaction. Do not retry the transaction. Con-tact Technical Support for more information.
3402 M The requested credit amount exceeds the remaining settlement amount.
3403 M You have already processed the maximum number of credits allowed for this settlement.
3404 M The settlement has already been fully credited.
3405 M The settlement you are attempting to credit has expired.
3406 M The settlement you are attempting to credit has not been batched yet. There are no settled funds available to credit.
3407 M The settlement referred to by the transaction response ID you provided cannot be found. Please verify this parameter and retry the transaction.
3408 M You have submitted an invalidly formatted response ID for the original purchase or settlement. Please verify this parameter and retry the transaction.
3409 M The authorization ID included in this credit request could not be found. Please verify this param-eter and retry the transaction.
3410 M The refund request failed.
3411 M The cancel refund request failed.
3412 M The Credit transaction you attempted was not permitted because your merchant account is in overdraft.
3413 M The requested Credit amount exceeds the permissible Visa credit ratio. Please verify this parame-ter and retry the transaction.
3414 M The credit referred to by the transaction response ID you provided cannot be found. Please verify this parameter and retry the transaction.
3415 D You cannot cancel this transaction. It is not in a state that can be cancelled. It may already have been completed and therefore not be in a pending state.
3416 M The external processing gateway for which your merchant account is configured does not support partial settlements. Ensure that the amount you are trying to settle is identical to the amount in the original authorization and retry the transaction.
3417 M There is already another request being processed on the transaction referenced for this request. Please use the confirmation number used for this request to run a report or lookup to determine the results.
3418 M The external processing gateway for which your merchant account is configured does not support partial credits.
3500 M The confirmation number included in this request could not be found. Please verify this parame-ter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-8
May 2019 Response codes
3501 M The requested authorization reversal amount exceeds the remaining authorization amount.
3502 D The authorization has already been settled. You cannot process an authorization reversal transac-tion against an authorization that has been settled.
3503 M The authorization reversal transaction is not supported for the card type used for the authoriza-tion you are attempting to reverse.
3504 M The external processing gateway for which your merchant account is configured does not support partial authorization reversals. Ensure that the amount you are trying to reverse is identical to the amount in the original authorization and retry the transaction.
3505 M The authorization reversal could not be completed.
3506 M The reversal amount exceeds the remaining amount of the authorization.
3601 D The 3D Secure authentication of this cardholder by the card issuer failed.
3602 M The confirmation number included in the 3D Secure authentication request could not be found. The confirmation number must be the one returned by the payment processor in response to the original authorization or purchase.
3603 M You submitted a request that is not available for 3D Secure authentication.
3604 D The original authorization or purchase request has expired. The 3D Secure authentication request must be completed within 60 minutes of the original authorization or purchase.
3605 D The 3D Secure authentication service was not available for the card used in this transaction.
3701 M The confirmation number included in this request could not be found. Please verify this parame-ter and retry the transaction.
3702 D You cannot cancel this payment transaction. It is not in a state that can be cancelled. It may already have been completed and therefore not be in a pending state.
3703 C The external gateway has reported that you have submitted an invalid amount with your request. Please verify this parameter and retry the transaction.
3704 M The transaction referred to cannot be found.
3705 M The transaction referred to uses a different card number.
3706 M The transaction referred to is not fully authenticated.
3707 D The transaction referred to is missing responses.
3708 M The transaction referred to has not been settled.
3800 D The transaction was declined by the authentication gateway. Do not retry the transaction.
3801 D The transaction was declined by the payment gateway. Do not retry the transaction.
3802 R The transaction was not completed successfully. Please retry the transaction.
3803 D The transaction attempt failed. Do not retry the transaction. Please contact Technical Support for more information.
3804 M You have attempted to refund a payment transaction that is not in a completed state. Do not retry the transaction.
3805 M The attempted refund amount exceeds the amount that remains available for refund. Please ver-ify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-9
Response Codes May 2019
3806 D You have attempted a refund, but no amount could be found that was eligible for refund. Do not retry the transaction.
3807 D You have attempted a refund, but a simultaneous refund attempt has been detected. Do not retry the transaction.
3808 D You have attempted a refund, but the transaction was refused by the payment provider. Do not retry the transaction.
3809 D The payment provider for the transaction you attempted denied you permission. Do not retry the transaction.
3810 D The payment transaction is pending due to payment provider fraud-management filters. Do not retry the transaction.
3811 D The request has been cancelled by the customer.
3812 D The cartItem amounts do not equal the totalAmount. Do not retry the transaction.
4000 D The transaction was declined by our Risk Management department.
4001 D The card number or email address associated with this transaction is in our negative database.
4002 D The transaction was declined by our Risk Management department.
5000 M Your merchant account authentication failed. Either your store ID/password are invalid or the IP address from which you are sending the transaction has not been authorized. Please verify these parameters and retry the transaction. Please contact Technical Support if the error persists.
5001 M You submitted an invalid currency code with your request. Please verify this parameter and retry the transaction.
5002 M You submitted an invalid payment method with your request. Please verify this parameter and retry the transaction.
5003 C You submitted an invalid amount with your request. Please verify this parameter and retry the transaction.
5004 M You submitted an invalid account type with your request. Please verify this parameter and retry the transaction.
5005 M You submitted an invalid operation type with your request. Please verify this parameter and retry the transaction.
5006 M You submitted an invalid personal ID type with your request. Please verify this parameter and retry the transaction.
5007 M You submitted an invalid product type with your request. Please verify this parameter and retry the transaction.
5008 M You submitted an invalid carrier with your request. Please verify this parameter and retry the transaction.
5009 M You submitted an invalid ship method with your request. Please verify this parameter and retry the transaction.
5010 M You submitted an invalid ID country with your request. Please verify this parameter and retry the transaction.
5011 M You submitted an invalid order date and time with your request. Please verify this parameter and retry the transaction.
5012 M You submitted an invalid ship country parameter with your request. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-10
May 2019 Response codes
5013 M You submitted an invalid ship state parameter with your request. Please verify this parameter and retry the transaction.
5014 M You submitted an invalid transaction type with your request. Please verify this parameter and retry the transaction.
5015 M At least one of the parameters in your request exceeds the maximum number of characters allowed. Please verify your parameters and retry the transaction.
5016 M Either you submitted an invalid merchant account or the merchant account could not be found. Please verify this parameter and retry the transaction. Please contact Technical Support if the error persists.
5017 D The merchant account submitted with your request is not enabled. Do not retry the transaction. Contact Technical Support for more information.
5018 M You submitted a request that either is missing a field or contains an invalid field.
5019 D There is no processor set up for the merchant account submitted with your request. Do not retry the transaction. Contact Technical Support for more information.
5020 M The currency type included with your request does not match the currency type of your merchant account. Please verify your parameters and retry the request.
5021 D Your transaction request has been declined. Please verify the transaction details before you attempt this transaction again. Should you require more information, please contact Technical Support.
5022 M You submitted a request that is missing search criteria. Please verify your parameters and retry the transaction.
5023 M The request is unparsable.
5024 M You submitted an invalid ID expiry date for this request. Please verify this parameter and retry the transaction.
5025 M The search criteria you submitted is currently not supported. Please verify your search criteria and retry.
5026 M The Web Services API does not currently support credit card transactions. Please verify your parameters and retry your transaction.
5027 M You submitted an invalid risk service name with your transaction request. Please verify your parameters and retry your transaction.
5028 M You submitted a batch file with the same file name, file size, and number of entries within the last 24 hours.
5029 M You submitted an improperly formatted batch file.
5030 M You submitted a batch file that has exceeded the maximum number of rows allowed.
5031 M The transaction you have submitted has already been processed.
5032 C You submitted an invalid city with your request. Please verify this parameter and retry the trans-action.
5033 C You submitted an invalid country with your request. Please verify this parameter and retry the transaction.
5034 C You submitted an invalid email address with your request. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-11
Response Codes May 2019
5035 C You submitted an invalid name with your request. Please verify this parameter and retry the transaction.
5036 C You submitted an invalid phone number with your request. Please verify this parameter and retry the transaction.
5037 C You submitted an invalid zip/postal code with your request. Please verify this parameter and retry the transaction.
5038 C You submitted an invalid state/province with your request. Please verify this parameter and retry the transaction.
5039 C You submitted an invalid street with your request. Please verify this parameter and retry the transaction.
5040 D Your merchant account is not configured for the transaction you attempted. Please contact Tech-nical Support for more information.
5041 M You submitted an invalid merchantData parameter. Please verify this parameter and retry the transaction.
5042 M The merchant reference number is missing or invalid or it exceeds the maximum permissible length. Please verify this parameter and retry the transaction.
5043 M You submitted an invalid account open date with your request. Please verify this parameter and retry the transaction.
5044 M You submitted an invalid customer ID with your request. Please verify this parameter and retry the transaction.
5045 M You submitted an invalid customer IP address with your request. Please verify this parameter and retry the transaction.
5046 M You submitted an invalid merchant SIC code with your request. Please verify this parameter and retry the transaction.
5047 M You submitted an invalid value for the previous customer parameter with your request. Please verify this parameter and retry the transaction.
5048 M You submitted an invalid product code with your request. Please verify this parameter and retry the transaction.
5049 M You submitted an invalid value for user data with your request. Please verify this parameter and retry the transaction.
5050 D An error occurred with your merchant account configuration. Please contact Technical Support.
5051 C You have submitted an invalid confirmation number. Please verify your parameter and retry.
5052 C You have submitted an invalid Zip/Postal code. Please verify your parameter and retry the trans-action.
5053 C You have submitted invalid personal ID information. Please verify your parameters and retry the transaction.
5054 M You cannot submit recurring billing elements with this operation type. Please verify that your request includes the correct operation type and retry the transaction.
5055 M You submitted an invalid ECI value. Please verify this parameter and retry the transaction.
5056 M An ECI value must be provided for 3D Secure authentication. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-12
May 2019 Response codes
5057 M You submitted a credit card brand that does not support 3D Secure authentication. Please verify this parameter and retry the transaction.
5058 M A CAVV value must be provided for 3D Secure authentication. Please verify this parameter and retry the transaction.
5059 M You submitted an invalid value for the currency request service.
5060 M You submitted an invalid recurringIndicator parameter with your request. Please verify this parameter and retry the transaction.
5061 M A security check failed while processing this transaction. Please retry the transaction. If the error persists, contact Technical Support.
5062 M You have submitted invalid characters as part of your request. Please verify that all parameters contain only characters that can be URL encoded, and retry the transaction.
5063 M You have submitted an invalid KEYWORD with your request. Please verify this parameter and retry the transaction."
5064 M You have submitted an invalid NETBANX_REFERENCE with your request. Please verify this param-eter and retry the transaction.
5065 M You have requested an invalid status change transition.
5066 M The external processing gateway for which your merchant account is configured does not support Independent Credits.
5067 M The external processing gateway for which your merchant account is configured does not support Credit Card Payments.
5068 M Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected.
5071 M You submitted a request that has invalid search parameters. Please verify your parameters and retry the transaction.
5074 M At least one of the parameters in your request is shorter than the minimum number of characters required. Please verify your parameters and retry the transaction.
5075 M At least one of the parameters in your request contains leading/trailing spaces. Please verify your parameters and retry the transaction.
5502 Either the payment token is invalid or the corresponding profile or bank account is not active.
7000 D The address you are trying to create already exists.
7001 M Unable to create address. Try again or contact Technical Support.
7002 M Unable to update address. Try again or contact Technical Support.
7003 M Unable to locate the specified address.
7004 M Unable to load address. Try again or contact Technical Support.
7005 M You have provided an invalid address type.
7006 M Unable to locate addresses for consumer.
7007 M Unable to load addresses. Try again or contact Technical Support.
7010 D The consumer you are trying to create already exists.
7011 M Unable to create consumer. Try again or contact Technical Support.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-13
Response Codes May 2019
7012 M Unable to update consumer. Try again or contact Technical Support.
7013 M Unable to locate the specified consumer.
7014 M Unable to load consumer. Try again or contact Technical Support.
7015 M You have specified an invalid consumer creation type.
7016 M You have specified an invalid consumer title.
7020 D The contact method you are trying to create already exists.
7021 M Unable to create contact method. Try again or contact Technical Support.
7022 M Unable to update contact method. Try again or contact Technical Support.
7023 M Unable to locate the specified contact method.
7024 M Unable to load contact method. Try again or contact Technical Support.
7025 M You have provided an invalid contact method type.
7026 M Unable to locate contact methods for consumer.
7027 M Unable to load contact methods. Try again or contact Technical Support.
7040 D The payment method you are trying to create already exists.
7041 M Unable to create payment method. Try again or contact Technical Support.
7042 M Unable to update payment method. Try again or contact Technical Support.
7043 M Unable to locate the specified payment method.
7044 M Unable to load payment method. Try again or contact Technical Support.
7045 M You have provided an invalid payment method type.
7046 M Unable to locate payment methods for consumer.
7047 M Unable to load payment methods. Try again or contact Technical Support.
7050 D The billing schedule you are trying to create already exists.
7051 M Unable to create billing schedule. Try again or contact Technical Support.
7052 M Unable to update billing schedule. Try again or contact Technical Support.
7053 M Unable to locate the specified billing schedule.
7054 M Unable to load billing schedule. Try again or contact Technical Support.
7055 M You have provided an invalid payment interval type.
7056 M Unable to locate billing schedules for consumer.
7057 M Unable to load billing schedules. Try again or contact Technical Support.
7058 M Billing amount must be greater than zero.
7059 M Unable to update billing schedule status. Try again or contact Technical Support.
7070 M Unable to execute the search operation. Try again or contact Technical Support.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-14
May 2019 Response codes
7080 M Unable to update records. Try again or contact Technical Support.
7090 D The consumer status you are trying to create already exists.
7091 M Unable to create consumer status. Try again or contact Technical Support.
7092 M Unable to update consumer status. Try again or contact Technical Support.
7093 M Unable to locate the specified consumer status.
7094 M Unable to load consumer status. Try again or contact Technical Support.
7095 M Unable to locate the merchant legal entity.
7096 M Unable to retrieve merchant legal entity. Try again or contact Technical Support.
7097 D An internal error occurred. Response Detail could not be generated.
7098 M You have provided an invalid credit card number.
7100 M The ddstatus you are trying to create for the paymentMethod already exists.
7101 M Unable to create the ddstatus for the paymentMethod. Try again or contact Technical Support.
7102 M Unable to update the ddstatus for the paymentMethod. Try again or contact Technical Support.
7103 M Unable to locate the specified ddstatus for the paymentMethod.
7104 M Unable to load the ddstatus for the paymentMethod. Try again or contact Technical Support.
7107 M The customer profile was successfully created but we were unable to load the email template.
7108 M The ccstatus you are trying to create for the paymentMethod already exists.
7109 M Unable to create the ccstatus for the paymentMethod. Try again or contact Technical Support.
7110 M Unable to update the ccstatus for the paymentMethod. Try again or contact Technical Support.
7111 M Unable to load the ccstatus for the paymentMethod. Try again or contact Technical Support.
8000 M Unable to perform operation. Try again or contact Technical Support.
8001 M You have submitted an invalid request. Please verify your parameters and retry.
8002 M Your request is missing the consumerInfo element.
8003 M Your request is missing a value for the firstName element.
8004 M Your request is missing a value for the lastName element.
8005 M Your request is missing the billingAddress/shippingAddress element.
8006 M Your request is missing billingAddress/shippingAddress information. There is no value for the street element.
8007 M Your request is missing billingAddress/shippingAddress information. There is no value for the city element.
8008 M Your request is missing billingAddress/shippingAddress information. There is no value for the zip element.
8009 M Your request is missing billingAddress/shippingAddress information. There is no value for the country element.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-15
Response Codes May 2019
8010 M Your request is missing billingAddress/shippingAddress information. There is no value for the state or region element.
8011 M Your request is missing the contactMethod element.
8012 M Your request is missing a home telephone number or a cell phone number or an email address for the type element.
8013 M Your request is missing the paymentMethod element.
8014 M Your request is missing a value for the id child element of the billingAddress element.
8015 M Your request is missing either the card or check child element of the paymentMethod element.
8016 M Your request is missing the card element.
8017 M Your request is missing a value for the cardNum element.
8018 M Your request is missing a value for the cardType element.
8019 M Your request is missing the cardExpiry element.
8020 M Your request is missing a value for the month element.
8021 M Your request is missing a value for the year element.
8022 M Your request is missing the check element.
8023 M Your request is missing a value for the accountNum element.
8024 M Your request is missing a value for the accountType element.
8025 M Your request is missing a value for the routingNum element.
8026 M Your request is missing a value for the bankName element.
8027 M Your request is missing a value for the checkNum element.
8028 M Your request is missing the billingSchedule element.
8029 M Your request is missing a value for the intervalCode element.
8030 M Your request is missing a value for the nextBillingDate element.
8031 M Your request is missing a value for the startDate element.
8032 M Your request is missing a value for the amount element.
8033 M Your request is missing the merchantAccount element.
8034 M Your request is missing a value for the accountNum element.
8035 M Your request is missing a value for the storeID element.
8036 M Your request is missing a value for the storePwd element.
8037 M The credentials supplied with the merchantAccount element could not be validated.
8038 M An internal error occurred. Please retry the request.
8039 M Your request is missing a value for the consumerId element.
8040 M Your request is missing a value for the title element.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-16
May 2019 Response codes
8041 M Your request is missing a value for the merchantRefNum child element of the consumerInfo ele-ment.
8042 M Your request is missing a value for the street2 element.
8043 M You have submitted an invalid address id element. It does not match the consumerId submitted with the request.
8044 M You have submitted an invalid contactMethod id element. It does not match the consumerId sub-mitted with the request.
8045 M Your request is missing a value for the paymentMethodId element.
8046 M Your request is missing a value for the ccHolderName element.
8047 M Your request is missing a value for the merchantRefNum child element of the paymentMethod ele-ment.
8048 M Your request is missing a value for the id child element of the billingSchedule element.
8049 M Your request is missing a value for the serviceName element.
8050 M Your request is missing a value for the statusCode element.
8051 M Your request is missing a value for the lastDayOfTheMonth element.
8052 M Your request is missing a value for the merchantRefNum child element of the billingSchedule ele-ment.
8053 M Your request contains two consumerId elements that don’t match.
8054 M You attempted an unsupported operation.
8055 M You have submitted an invalid endDate element.
8056 M You have submitted an invalid issueNumber element.
8057 M You have submitted an invalid statusCode element.
8058 M You have submitted an invalid intervalCode element.
8059 M You have submitted an invalid title element.
8060 M You have submitted an invalid cardType element.
8061 M You have submitted an invalid accountType element.
8062 M You have submitted an invalid state element.
8063 M You have submitted an invalid country element.
8064 M You have submitted an invalid startDate element.
8065 M You have submitted an invalid endDate element.
8066 M You have submitted an invalid nextBillingDate element.
8067 M The endDate cannot be before the startDate.
8068 M The nextBillingDate cannot be after the endDate.
8069 M The nextBillingDate cannot be before the startDate.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-17
Response Codes May 2019
8070 M You have submitted an invalid cardExpiry element.
8071 M You have submitted an invalid paymentMethod billingAddressId. Either it does not match the con-sumerId submitted with the request or it is the wrong address type.
8072 M You have submitted an invalid paymentMethod shippingAddressId. Either it does not match the consumerId submitted with the request or it is the wrong address type.
8073 M You have submitted an invalid contactMethod type element.
8074 M You have submitted an invalid paymentMethod id element. It does not match the consumerId submitted with the request.
8075 M You have submitted an invalid billingSchedule id element. It does not match the consumerId sub-mitted with the request.
8076 M You have submitted an invalid consumerId element. The consumer specified is not registered with this merchant.
8077 M You have submitted an invalid billingSchedule paymentMethodId element. The payment method identified is not registered with this consumer.
8078 D You have submitted a duplicate request within the last 24 hours.
8079 D You have submitted a file that has already been processed within the last 24 hours.
8080 M You have submitted an invalid record type. It is missing the recurringBillingDetails element.
8081 D You have submitted an empty file.
8082 M You have submitted an invalid request.
8083 M Your request is missing a value for the cvv element.
8084 M You have submitted an invalid cvv element.
8085 M Your request is missing a value for the Merchant Transaction ID element.
8086 M Your request is missing a value for the Transaction ID element.
8087 M You have submitted an invalid accountNum element.
8088 M You have submitted a record with an invalid number of fields.
8089 D You have submitted a file that exceeds the file size limit.
8090 M You have submitted an invalid Transaction Date element.
8091 M You have submitted an invalid ID Expiration element.
8092 M Your have submitted an unsupported transaction type for the Transaction Code element.
8093 M You have submitted an invalid billingSchedule element. Your request is either missing a payment-MethodId or missing a new paymentMethod element.
8094 M You have submitted an invalid paymentMethod element. Your request is either missing a bill-ingAddressId or missing a new billingAddress element.
8095 M You have submitted a file that exceeds the limit of 1000 records.
8096 M You have submitted an invalid transactionMode element. Please verify this parameter and retry the transaction.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-18
May 2019 Response codes
8100 M Your request is missing a value for the aggregateAccountNum element.
8101 M You have submitted an invalid aggregateAccountNum element.
8102 M You have submitted an invalid Version element.
8103 M You have submitted an invalid storeID element.
8104 M You have submitted an invalid storePwd element.
8105 M You have submitted an accountNum element that is not associated with the aggregateAccount-Num element.
8106 M You have submitted an invalid aggregateAccountNum element. No aggregated accounts were found.
8107 M Your request is missing a value for the intervalValue element.
8108 M You have submitted an invalid intervalValue element.
8109 M The intervalValue element cannot be provided with the defined intervalCode.
8110 M The value for the intervalValue element must be between 1 and 365.
8112 M You have submitted an invalid merchantAccount element. The merchant account number pro-vided is not set up for Recurring Billing.
8119 M Your request is missing a value for the userName element.
8120 M Your request is missing a value for the password element.
8121 M Your request is missing a value for the customerIp element.
8122 M Your request is missing a value for the siteUrl element.
8123 M Your request is missing a value for the keyword element.
8124 M Your request is missing a value for the welcomeEmail element.
8125 M An internal error occurred. The welcome email could not be generated.
8126 R You have submitted an invalid bank country in your request. Please verify your parameter and retry the transaction.
8127 M Your request is missing a value for the ddMandateReference child element of the billingSchedule element.
8128 M You have submitted an invalid mandate reference. Please verify your parameter and retry the transaction.
8129 M You have submitted an invalid financingType element. Please verify your parameter and retry the transaction.
8130 M You have submitted an invalid plan element. Please verify your parameter and retry the transac-tion.
8131 M You have submitted an invalid gracePeriod element. Please verify your parameter and retry the transaction.
8132 M You have submitted an invalid term element. Please verify your parameter and retry the transac-tion.
8133 M Your request is missing a value for the processingType element.
Table B-1: Response Codes (Continued)
Response Code Action Description
API Reference Guide for Web Services 1.0 B-19
Response Codes May 2019
Action codesThe transaction processor returns an action along with each response code. The meanings for the action codes are as follows:
• C = Consumer Parameter Error. The consumer has provided incorrect information. Ask the cus-tomer to correct the information.
• D = Do Not Retry
• M = Merchant Parameter Error. Your application has provided incorrect information. Verify your information.
8134 M Your request is missing a value for the appliedDate element.
8135 M Your request is missing a value for the echeckId element.
8136 M The purchase transaction that corresponds with the recurring billing record you are trying to cre-ate could not be located. The consumer and the recurring billing record were created but the wel-come email could not be sent.
8137 M Your merchant account is not configured for the transaction you attempted.
8138 M You submitted an invalid email address with your request.
8139 M The routing number length for BACS (Sort Code) should be 6 digits.
8140 M The routing number length for ACH should be 9 digits.
8141 M The routing number length for EFT (Institution ID/Transit Number) should be 8 digits.
8142 M The routing number length for NAB (Bank State Branch) should be 6 digits.
8143 M The routing number length for SEPA (BIC) should not exceed 11 characters.
8144 M The account number length for BACS should be 8 digits.
8145 M The account number length for ACH should not exceed 17 digits.
8146 M The account number length for EFT should not exceed 12 digits.
8147 M The account number length for NAB (Bank State Branch) should not exceed 9 digits.
8148 M The account number length for SEPA (IBAN) should not exceed 34 characters.
9000 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for load balancing.
9001 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for tier routing.
9002 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for sticky routing.
9003 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for bin country routing.
9004 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for brand routing.
9005 D Your transaction request could not be processed because your merchant account has no avail-able child accounts for keyword routing.
Table B-1: Response Codes (Continued)
Response Code Action Description
B-20
May 2019 Return codes
• R = Retry
Return codesThese are the codes used by the online banking e-payment system for identifying the various reasons a check or payment is returned. These codes are generated by customers’ banks (RDFI) to return items.
Table B-2: Return Codes
Code Description Bank Scheme
900 Validation Rejection EFT
901 Not sufficient funds (debits only) EFT
902 Cannot trace EFT
903 Payment stopped/recalled EFT
904 Post dated/stale dated EFT
905 Account closed EFT
906 Account transferred EFT
907 No chequing privileges EFT
908 Funds not cleared EFT
909 Currency/Account Mismatch EFT
910 Payor/payee deceased EFT
911 Account frozen EFT
912 Invalid/incorrect account number EFT
914 Incorrect payor/payee name EFT
915 Refused by payor/payee EFT
916 Not in accordance with Agreement - Personal EFT
917 Agreement Revoked - Personal EFT
918 No Pre-Notification - Personal EFT
919 Not in accordance with Agreement - Business EFT
920 Agreement Revoked - Business EFT
921 No Pre-Notification - Business EFT
922 Customer Initiated Return Credit Only EFT
990 Institution in Default EFT
998 No Return Agreement EFT
4 TRANSACTION TYPE is invalid or blank. See Appendix 3 for a list of CPA Transaction Types.
EFT
5 AMOUNT is blank, or not greater than zero. EFT
6 DUE DATE is invalid or blank. EFT
API Reference Guide for Web Services 1.0 B-21
Response Codes May 2019
7 INSTITUTION (route and/or transit) is not in the correct format, does not exist or is blank.
EFT
8 ACCOUNT NUMBER is not a valid format for the specified INSTITUTION. EFT
9 ITEM TRACE NO. is invalid. EFT
10 STORED TRANSACTION TYPE is invalid or blank. EFT
11 ORIGINATOR SHORT NAME is blank. EFT
12 PAYOR/PAYEE NAME is blank. EFT
13 ORIGINATOR LONG NAME is blank. EFT
14 Originating Direct Clearer ID is invalid or blank. EFT
15 CROSS REFERENCE is blank. EFT
16 INSTITUTION FOR RETURNS (route and/or transit) is invalid or blank. It should spec-ify your credit union.
EFT
19 Original item trace number is invalid or blank. EFT
21 DATA ELEMENT ID is invalid or blank. EFT
E Accepted but errors were noted EFT
M Rejected, message authentication code (MAC) failed EFT
P Partially accepted, at least one transaction set was rejected EFT
R Rejected EFT
W Rejected, assurance failed validity tests EFT
X Rejected, content after decryption could not be analyzed EFT
TR Rejected by 824 EFT
YE Transaction code unauthorised for originating Account BACS
0 Refer to Payer BACS
1 Instruction cancelled by payer BACS
2 Payer Deceased BACS
3 Account Transferred BACS
4 Advance Notice Disputed BACS
5 No Account BACS
6 No Instruction BACS
7 Amount Differs BACS
8 Amount not yet due BACS
9 Presentation Overdue BACS
A Service User Differs BACS
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
B-22
May 2019 Return codes
B Account Closed BACS
E Instruction amended BACS
AE Originating sort code and/or Account number invalid (bank originated) BACS
BE Originating sort code and/or Account number invalid (customer originated) BACS
CE Destination sort code and originating sort code and/or Account number invalid (bank originated)
BACS
DE Destination sort code and originating sort code and/or Account number invalid (cus-tomer originated)
BACS
EE Destination sort code invalid BACS
FE Account type and originating sort code and/or Account number invalid (bank origi-nated)
BACS
GE Account type and originating sort code and/or Account number invalid (customer originated)
BACS
HE Destination sort code and Account type and originating sort code and/or Account number invalid (bank originated)
BACS
IE Destination sort code and Account type and originating sort code and/or Account number invalid (customer originated)
BACS
JE Destination sort code and Account type invalid BACS
KE Account type invalid BACS
LE Destination Account number and destination Account name and other fields invalid BACS
ME Destination Account number and destination Account name invalid BACS
NE Contra record was amended BACS
OE Reference number was invalid BACS
PE Originating Account does not support the file currency BACS
QE Automated reversal due to an error BACS
RE Reversal of another item (same day) BACS
SE Automated recall BACS
TE Originating Account invalid and was substituted with the default main Account details, but this Account does not support the file currency (customer originated)
BACS
UE Unpaid direct debit reference was in error (bank originated) BACS
XE Originator's service user number invalid (bank originated) BACS
ZE Unpaid direct debit reference and other fields were in error (bank originated) BACS
1I Amount and / or date of Direct Debit differ from Advance Notice BACS
2I No Advance Notice received by Payer/or the amount quoted is disputed BACS
3I DDI cancelled by paying bank BACS
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
API Reference Guide for Web Services 1.0 B-23
Response Codes May 2019
4I Payer has cancelled DDI direct with service user BACS
5I AUDDIS service users only - No Instruction held. Payer disputes having given author-ity
BACS
6I AUDDIS service users only - Signature on DDI is fraudulent or not in accordance with account authorised signature(s)
BACS
7I Claim raised at service users request after Direct Debit applied to payers account BACS
8I Service user name disputed. Payer does not recognise service user collecting Direct Debit
BACS
CC Requested by originator BACS
0C Invalid details BACS
2C Beneficiary deceased BACS
3C Account transferred BACS
5C No account BACS
BC Account closed BACS
C Account transferred to a different branch of bank / building society BACS
D Advance notice disputed BACS
F Invalid account type BACS
G Bank will not accept Direct Debits on account BACS
H Instruction has expired BACS
I Payer reference is not unique BACS
K Instruction cancelled by paying bank BACS
L Incorrect payer's account details BACS
M Transaction code / user status incompatible BACS
N Transaction disallowed at payer's branch BACS
O Invalid reference BACS
P Payer's Name not present BACS
Q Service user's name blank BACS
R Instruction re-instated (maximum 2 months from original DDI cancellation date) BACS
AC01 Account identifier incorrect SEPA
UPAY Undue payment SEPA
AC06 Account blocked SEPA
AC13 Invalid debtor account type SEPA
AG01 Direct debit forbidden SEPA
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
B-24
May 2019 Return codes
AG02 Invalid bank operation code SEPA
AGNT Incorrect agent SEPA
AM04 Insufficient funds SEPA
AM05 Duplication SEPA
BE04 Missing creditor address SEPA
BE05 Unrecognized creditor SEPA
CURR Incorrect currency SEPA
CUST Recall by customer SEPA
CUTA Recall due to investigation request SEPA
DT01 Invalid date SEPA
DUPL Duplicate payment SEPA
ED05 Settlement failed SEPA
FF01 Invalid file format SEPA
FF05 Direct debit type incorrect SEPA
FRAD Fraud SEPA
MD01 No valid mandate SEPA
MD02 Mandate data missing or incorrect SEPA
MD06 Disputed authorized transaction SEPA
MD07 Debtor deceased SEPA
MS02 Refusal by debtor SEPA
MS03 Reason not specified SEPA
PY01 Not routable SEPA
RC01 Bank identifier incorrect SEPA
RR01 Missing debtor account or identification SEPA
RR02 Missing debtor name or address SEPA
RR03 Missing creditor name or address SEPA
RR04 Regulatory reason SEPA
SL01 Specific service offered by debtor agent SEPA
TECH Payment in error due to technical problem SEPA
TM01 Invalid cut off time SEPA
AC04 Account closed SEPA
RT not found ACH
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
API Reference Guide for Web Services 1.0 B-25
Response Codes May 2019
CONFIG Client configuration problem ACH
LIMIT The maximum amount per check was exceeded. ACH
INVACCT Invalid account type. ACH
INVDIR Invalid direction. ACH
NOPOP Merchant not configured or not allowed to run POP transactions - Electronic Check Conversion.
ACH
PAPER Paper draft and can't send paper. ACH
PARSE Parsing problem ACH
THOMSON Reject due to Thomson database. ACH
UNKMER Unknown merchant. ACH
DEMO Demonstration transaction/ or merchant. ACH
R90 Invalid MOD digit ACH
R91 Invalid ABA. Not nine (9) characters or numeric ACH
R92 ABA not active ACH
R93 Invalid Tran Code SEC combo ACH
R94 Invalid amount for pre-note Tran Code ACH
R95 Amount is zero (0) ACH
R96 Not a valid Tran code ACH
R97 Not a valid SEC code ACH
R98 Account decryption error ACH
R99 OFAC possible match ACH
R37 Source Document Presented for Payment ACH
R38 Stop Payment on Source Document ACH
R39 Improper Source Document ACH
R53 Item and ACH Entry Presented for Payment ACH
R75 Original Return not a Duplicate ACH
R76 No Errors Found ACH
R83 Foreign Receiving DFI Unable to Settle ACH
R84 Entry Not Processed by OGO ACH
R01 Insufficient funds ACH
R02 Account closed ACH
R03 No account/unable to locate ACH
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
B-26
May 2019 Return codes
R04 Invalid account number ACH
R05 Reserved ACH
R06 Return requested by ODFI ACH
R07 Authorization revoked Note 2 ACH
R08 Stop payment ACH
R09 Uncollected funds ACH
R10 Not authorizedNote 2 ACH
R11 Check truncation entry return ACH
R12 Branch sold to another DFI ACH
R13 RDFI not qualified to participate/or invalid route ACH
R14 Payee deceased ACH
R15 Beneficiary deceased ACH
R16 Account frozen ACH
R17 File record edit criteria ACH
R18 Improper effective entry date ACH
R19 Amount field error ACH
R20 Non transaction account ACH
R21 Invalid company ident. ACH
R22 Invalid individual ID number ACH
R23 Credit entry refused by receiver ACH
R24 Duplicate entry ACH
R25 Addenda error ACH
R26 Mandatory field error ACH
R27 Trace number error ACH
R28 Routing # check digit error ACH
R29 Corp cust. adviser not auth. ACH
R30 RDFI non-part truncation prob ACH
R31 Permissible return entry ACH
R32 RDFI non-settlement ACH
R33 Return of XCK entry ACH
R34 Limited participation DFI ACH
R35 Return of improper debit entry ACH
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
API Reference Guide for Web Services 1.0 B-27
Response Codes May 2019
*An initially cleared item can be returned as “Unauthorized”, “Authorized”, or “Authorization Revoked” for up to 60 days following the date of Presentment.
R36 Return of improper credit entry ACH
R40 Return of ENR entry by Fed. Gov. ACH
R41 Invalid transaction code ACH
R42 Routing #/check digit error ACH
R43 Inv. DFI acct. number ACH
R44 Inv. Individual ED number ACH
R45 Inv. individual name/company name ACH
R46 Inv. rep. payee indicator ACH
R47 Duplicate enrollment ACH
R50 State Law affecting RCK acceptance ACH
R51 Item is ineligible (RCK) ACH
R52 Stop payment on item (RCK) ACH
R61 Dishonor ACH
R62 Dishonor ACH
R63 Dishonor ACH
R64 Dishonor ACH
R65 Dishonor ACH
R66 Dishonor ACH
R67 Dishonor ACH
R68 Dishonor ACH
R69 Dishonor ACH
R70 Dishonor ACH
R71 ContestedNote 4 ACH
R72 ContestedNote 4 ACH
R73 ContestedNote 4 ACH
R74 ContestedNote 4 ACH
R80 Cross- border payment coding error ACH
R81 Non-participant in cross-border pgm. ACH
R82 Invalid foreign RDFI ID ACH
Table B-2: Return Codes (Continued)
Code Description Bank Scheme
B-28
APPENDIX C
Geographical Codes
Province codes Table C-1: Province Codes
Province Code
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland NL
Nova Scotia NS
Northwest Territories NT
Nunavut NU
Ontario ON
Prince Edward Island PE
Quebec QC
Saskatchewan SK
Yukon YT
API Reference Guide for Web Services 1.0 C-1
Geographical Codes May 2019
State codes Table C-2: State Codes
State Code State Code
Alabama AL Alaska AK
Arizona AZ Arkansas AR
California CA Colorado CO
Connecticut CT Delaware DE
District of Columbia DC Florida FL
Georgia GA Hawaii HI
Idaho ID Illinois IL
Indiana IN Iowa IA
Kansas KS Kentucky KY
Louisiana LA Maine ME
Maryland MD Massachusetts MA
Michigan MI Minnesota MN
Mississippi MS Missouri MO
Montana MT Nebraska NE
Nevada NV New Hampshire NH
New Jersey NJ New Mexico NM
New York NY North Carolina NC
North Dakota ND Ohio OH
Oklahoma OK Oregon OR
Pennsylvania PA Rhode Island RI
South Carolina SC South Dakota SD
Tennessee TN Texas TX
Utah UT Vermont VT
Virginia VA Washington WA
West Virginia WV Wisconsin WI
Wyoming WY United States Federal US
International IT Puerto Rico PR
U.S. Virgin Islands VI Northern Mariana Is. MP
Guam GU American Samoa AS
Palau PW Armed Forces Americas AA
C-2
May 2019 Country codes
Country codes
Armed Forces Europe AE Armed Forces Pacific AP
Table C-3: Country Codes
Country Code Country Code
Afghanistan AF Åland Islands AX
Albania AL Algeria DZ
American Samoa AS Andorra AD
Angola AO Anguilla AI
Antarctica AQ Antigua and Barbuda AG
Argentina AR Armenia AM
Aruba AW Australia AU
Austria AT Azerbaijan AZ
Bahamas BS Bahrain BH
Bangladesh BD Barbados BB
Belarus BY Belgium BE
Belize BZ Benin BJ
Bermuda BM Bhutan BT
Bolivia BO Bonaire, Sint Eustatius and Saba BQ
Bosnia and Herzegovina BA Botswana BW
Bouvet Island BV Brazil BR
British Indian Ocean Territory IO Brunei Darussalam BN
Bulgaria BG Burkina Faso BF
Burundi BI Cambodia KH
Cameroon CM Canada CA
Cape Verde CV Cayman Islands KY
Central African Republic CF Chad TD
Chile CL China CN
Christmas Island CX Cocos (Keeling) Islands CC
Colombia CO Comoros KM
Congo CG Congo, Democratic Republic of CD
Table C-2: State Codes (Continued)
State Code State Code
API Reference Guide for Web Services 1.0 C-3
Geographical Codes May 2019
Cook Islands CK Costa Rica CR
Côte D’Ivoire CI Croatia HR
Cuba CU Curaçao CW
Cyprus CY Czech Republic CZ
Denmark DK Djibouti DJ
Dominica DM Dominican Republic DO
Ecuador EC Egypt EG
El Salvador SV Equatorial Guinea GQ
Eritrea ER Estonia EE
Ethiopia ET Falkland Islands FK
Faroe Islands FO Fiji FJ
Finland FI France FR
French Guiana GF French Polynesia PF
French Southern Territories TF Gabon GA
Gambia GM Georgia GE
Germany DE Ghana GH
Gibraltar GI Greece GR
Greenland GL Grenada GD
Guadeloupe GP Guam GU
Guatemala GT Guernsey GG
Guinea GN Guinea-Bissau GW
Guyana GY Haiti HT
Heard and McDonald Islands HM Honduras HN
Hong Kong HK Hungary HU
Iceland IS India IN
Indonesia ID Iran (Islamic Republic of) IR
Iraq IQ Ireland IE
Isle of Man IM Israel IL
Italy IT Jamaica JM
Japan JP Jersey JE
Jordan JO Kazakhstan KZ
Kenya KE Kiribati KI
Table C-3: Country Codes (Continued)
Country Code Country Code
C-4
May 2019 Country codes
Korea, Democratic People’s Republic KP Korea, Republic of KR
Kuwait KW Kyrgyzstan KG
Lao People’s Democratic Republic LA Latvia LV
Lebanon LB Lesotho LS
Liberia LR Libyan Arab Jamahiriya LY
Liechtenstein LI Lithuania LT
Luxembourg LU Macau MO
Macedonia MK Madagascar MG
Malawi MW Malaysia MY
Maldives MV Mali ML
Malta MT Marshall Islands MH
Martinique MQ Mauritania MR
Mauritius MU Mayotte YT
Mexico MX Micronesia, Federated States of FM
Moldova, Republic of MD Monaco MC
Mongolia MN Montenegro ME
Montserrat MS Morocco MA
Mozambique MZ Myanmar MM
Namibia NA Nauru NR
Nepal NP The Netherlands NL
New Caledonia NC New Zealand NZ
Nicaragua NI Niger NE
Nigeria NG Niue NU
Norfolk Island NF Northern Mariana Islands MP
Norway NO Oman OM
Pakistan PK Palau PW
Palestinian Territory, Occupied PS Panama PA
Papua New Guinea PG Paraguay PY
Peru PE Philippines PH
Pitcairn PN Poland PL
Portugal PT Puerto Rico PR
Qatar QA Reunion RE
Table C-3: Country Codes (Continued)
Country Code Country Code
API Reference Guide for Web Services 1.0 C-5
Geographical Codes May 2019
Romania RO Russian Federation RU
Rwanda RW Saint Barthélemy BL
Saint Helena SH Saint Kitts and Nevis KN
Saint Lucia LC Saint Martin MF
Saint Vincent and the Grenadines VC Samoa WS
San Marino SM Sao Tome and Principe ST
Saudi Arabia SA Senegal SN
Serbia RS Seychelles SC
Sierra Leone SL Singapore SG
Sint Maarten SX Slovakia (Slovak Republic) SK
Slovenia SI Solomon Islands SB
Somalia SO South Africa ZA
South Georgia and the South Sandwich Islands GS South Sudan SS
Spain ES Sri Lanka LK
St. Pierre and Miquelon PM Sudan SD
Suriname SR Svalbard and Jan Mayen Islands SJ
Swaziland SZ Sweden SE
Switzerland CH Syrian Arab Republic SY
Taiwan TW Tajikistan TJ
Tanzania, United Republic of TZ Timor-Leste TL
Thailand TH Togo TG
Tokelau TK Tonga TO
Trinidad and Tobago TT Tunisia TN
Turkey TR Turkmenistan TM
Turks and Caicos Islands TC Tuvalu TV
Uganda UG Ukraine UA
United Arab Emirates AE United Kingdom GB
United States US United States Minor Outlying Islands UM
Uruguay UY Uzbekistan UZ
Vanuatu VU Vatican City State (Holy See) VA
Venezuela VE Vietnam VN
Virgin Islands (British) VG Virgin Islands (U.S.) VI
Table C-3: Country Codes (Continued)
Country Code Country Code
C-6
May 2019 Country codes
Wallis and Futuna Islands WF Western Sahara EH
Yemen YE Zambia ZM
Zimbabwe ZW
Table C-3: Country Codes (Continued)
Country Code Country Code
API Reference Guide for Web Services 1.0 C-7
Geographical Codes May 2019
C-8