MENU Navbar
Paywire Developer Documentation
C# VB cURL

Introduction

The Paywire Gateway implements different payment gateways, offering a simple integration with an increasing number of features.

Four integration options are made available:

  1. Application Programming Interface (API)
  2. Off Site Buy Page (OSBP)
  3. Checkout Page (via OSBP)
  4. OCX Control

The API option allows the developer to use the Paywire Gateway features within their own application. This option is the most flexible, but requires a more complex implementation. More information on the API is detailed in the API Reference.

The OSBP is the quickest integration option, favoured by most merchants and developers. For more information regarding OSBP, please refer to the OSBP Reference section.

The Checkout Page is a simple development solution to complete a transaction. Paywire can generate a checkout button by contacting support@paywire.com. For more information regarding the checkout, please refer to the Checkout Options section.

The OCX provides an easy-to-install component that can connect readers with the Paywire API or simplify integration with a built-in form that captures payment information. More information on the OCX is detailed in the OCX Reference.

URLs

The API and OSBP only accept HTTP POST.

Staging     https://dbstage1.paywire.com

Production    https://dbtranz.paywire.com

Authentication

Example:

<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      ...
   </TRANSACTIONHEADER>
  ...
</PAYMENTREQUEST>

Make sure to replace {clientId}, {key}, {username} and {password} with the relevant credentials provided to you by Payscout.

To authenticate with the Paywire API, OSBP or OCX simply include your 4 credentials in the XML payload.

If you do not have these credentials you may request them by emailing the support@paywire.com.

Common Structure

XML Requests

Common Request XML Elements:

<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID></PWCLIENTID>
      <PWKEY></PWKEY>
      <PWUSER></PWUSER>
      <PWPASS></PWPASS>
      <PWTRANSACTIONTYPE></PWTRANSACTIONTYPE>
   </TRANSACTIONHEADER>
   <CUSTOMER/>
</PAYMENTREQUEST>

The API, OSBP and OCX (using form) all have a similar XML request structure.

PAYMENTREQUEST is the parent element to a TRANSACTIONHEADER block, and a CUSTOMER block when processing a payment.

TRANSACTIONHEADER needs to always specify the Authentication, PWTRANSACTIONTYPE and PWVERSION parameters as children.

XML Responses

OSBP Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
   <PWINVOICENUMBER>0987654321234567889</PWINVOICENUMBER>
   <RESULT>APPROVAL</RESULT>
   <PWCLIENTID>0000000001</PWCLIENTID>
   <AUTHCODE>TAS709</AUTHCODE>
   <AVSCODE>N</AVSCODE>
   <CVVCODE>M</CVVCODE>
   <PAYMETH>C</PAYMETH>
   <PWUNIQUEID>596</PWUNIQUEID>
</PAYMENTRESPONSE>

API Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>A</PAYMETH>
    <PWUNIQUEID>112302</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXX4082</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>ACH</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

OSBP Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
   <PWINVOICENUMBER>0987654321234567889</PWINVOICENUMBER>
   <RESULT>DECLINED</RESULT>
   <RESTEXT>CVV2 MISMATCH</RESTEXT>
   <PWCLIENTID>0000000001</PWCLIENTID>
   <CVVCODE>N</CVVCODE>
   <PAYMETH>C</PAYMETH>
   <PWUNIQUEID>597</PWUNIQUEID>
</PAYMENTRESPONSE>

API Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>DECLINED</RESULT>
    <RESTEXT>  ERROR  0295   </RESTEXT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <AVSCODE>0</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>112301</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>VISA</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

The following XML parameters are returned by the OSBP and API, and the OCX when using the UI form.

Parameter Type Description
PWCLIENTID int ID associated with merchant, assigned by Paywire.
PWINVOICENUMBER string The Merchant's unique invoice number submitted in the transaction request.
RESULT string The result of the transaction: APPROVAL, SUCCESS, DECLINED, ERROR.
RESTEXT string Contains the error message.
AMOUNT int/decimal Amount of the transaction total including any adjustments and taxes. Max 7 digits, excluding decimals.
PWADJDESC string 'Consumer Fee'-enabled merchants only: The description for the service adjustment as set in the Merchant configuration.
PWADJAMOUNT int/decimal 'Consumer Fee'-enabled merchants only: Amount of the service adjustment. Max 7 digits, excluding decimals.
PWSALETAX int/decimal 'Consumer Fee'-enabled merchants only: Amount of the sales tax calculated based on the 'Sales Tax Flat Rate %' set in the merchant configuration. Max 7 digits, excluding decimals.
PWSALEAMOUNT int/decimal Original Sale Amount, before any markups or discounts. Max 7 digits, excluding decimals.
MASKEDACCOUNTNUMBER string The masked account number that the transaction was processed under.
PAYMETH string Method of payment that the transaction was processed with: E for web ACH, C for Card.
CCTYPE string The Card type used. This field is blank if PAYMETH is E.
AHNAME string The account holder's name that was supplied.
AHFIRSTNAME string The account holder's first name that was supplied.
AHLASTNAME string The account holder's last name that was supplied.
PWUNIQUEID string The unique ID assigned by Paywire associated with this transaction.
EMAIL string The user's email address that was supplied at the start of the transaction.
AUTHCODE string Authorization code associated with the transaction, if applicable.
PWCID string Paywire Customer Identifier associated with a transaction. If original request was to create a customer, then this will be the new customer ID.
AVSCODE string Transaction AVS code result. Refer to AVS Codes table
CVVCODE int Transaction CVV result: 1 for a match, 0 for a failure.
RECURRING int The recurring amount if the value under PWCTRANSTYPE is selected.

AVS Codes

The following are the possible values returned in the AVSCODE XML parameter:

Value Description
S Service not supported
E Not a mail/phone order
R Issuer system unavailable
U Address unavailable
Z No address or zip match
W 5-digit zip match only
A 9-digit zip match only
Y Address match only
X Exact match, 5-digit zip

Test Cards

The following are available for you to test with the Paywire gateway:

Card Scheme Number CVV
VISA 4761739001010267 999
mastercard 5413330089010608 998
Discover 6510000000000034 996

API Reference

Application programming interface ("API") is the alternate subroutine interface to the Off Site Buy Page. The API is primarily used by clients who wish to add payment acceptance methods to their existing application.

At this time, the Paywire API accepts requests in XML using HTTP POST only.

API Overview

Source Code Example:

protected string pwPost(string url, string xmlPayload) 
{ 
  HttpWebRequest req; 
  HttpWebResponse res; 
  try 
  { 
    req = (HttpWebRequest)WebRequest.Create(url); 
    req.Method = "POST"; 
    req.ContentType = "text/xml; charset=utf-8"; 

    req.ContentLength = xmlPayload.Length; 
    var sw = new StreamWriter(req.GetRequestStream()); 
    sw.Write(xmlPayload); 
    sw.Close(); 

    res = (HttpWebResponse)req.GetResponse(); 
    Stream responseStream = res.GetResponseStream(); 
    var streamReader = new StreamReader(responseStream); 

    //Read the response into an xml document 
    var xml = new XmlDocument(); 
    xml.LoadXml(streamReader.ReadToEnd()); 

    var result = xml.InnerXml;

    return result;
  } 
  catch (Exception ex) 
  { 
    throw;
  }  
} 
Private Function sendRequest(ByVal url As string, ByVal xmlPayload As string) As string
  Dim request As WebRequest = WebRequest.Create(url)
  Dim result As string = string.Empty

  request.Method = "POST"
  request.ContentLength = xmlPayload.Length
  request.ContentType = "text/xml"

  Dim writer As New StreamWriter(request.GetRequestStream(), System.Text.Encoding.UTF8)
  writer.Write(base64Encode(xmlPayload))
  writer.Close()

  Dim stream As Stream = request.GetResponse().GetResponseStream()
  Dim reader As New StreamReader(stream)
  Dim response As string = string.Empty

  response = reader.ReadToEnd()
  response = Server.UrlDecode(response)

  Return base64Decode(response)
End Function

Public Function base64Encode(ByVal data As string) As string
  Try
    Dim encData_byte As Byte() = New Byte(data.Length - 1) {}
    encData_byte = System.Text.Encoding.UTF8.GetBytes(data)
    Dim encodedData As string = Convert.ToBase64string(encData_byte)
    Return encodedData
  Catch e As Exception
    Throw New Exception("Error in base64Encode" + e.Message)
    End Try
  End Function

Public Function base64Decode(ByVal data As string) As string
  Try
    Dim encoder As New System.Text.UTF8Encoding()
    Dim utf8Decode As System.Text.Decoder = encoder.GetDecoder()
    Dim todecode_byte As Byte() = Convert.FromBase64string(data)
    Dim charCount As Integer = utf8Decode.GetCharCount(todecode_byte, 0, todecode_byte.Length)
    Dim decoded_char As Char() = New Char(charCount - 1) {}
    utf8Decode.GetChars(todecode_byte, 0, todecode_byte.Length, decoded_char, 0)
    Dim result As string = New [string](decoded_char)
    Return result
  Catch e As Exception
    Throw New Exception("Error in base64Decode" + e.Message)
  End Try
End Function  
$ curl 
  https://dbstage1.paywire.com/API/pwapi.aspx
  -X POST
  -H "Content-Type: text/xml" 
  -d "$XML_Payload"

xmlPayload is the only variable between different transaction types.

To use the Paywire API you will need to:

  1. Implement logic in your application to determine the transaction type required.
  2. Collect the necessary information from the customer (where applicable), which may include PCI data.
  3. Build an XML string including Authentication parameters and at minimum the mandatory fields for the transaction type being processed.
  4. Send an HTTP POST containing the XML string to the Paywire API endpoint.
  5. Receive an XML response to parse and use.

OSBP Process Flowchart

API Endpoints

The same OSBP endpoint is available for all requests, across all environments.

POST /API/pwapi.aspx
Content-Type: text/xml

API Transaction Types

The following transactions can be processed via the Paywire API.

Simply submit the relevant value in PWTRANSACTIONTYPE, along with the required XML parameters.

Value Description
SALE Charge a card or bank account (if applicable).
VOID Void a transaction. The transaction amount must match the amount of the original transaction, and the PWUNIQUEID must match the unique identifier associated with the transaction to void. The transaction must be in the current open batch to void it.
CREDIT Credit a transaction. The transaction amount must be equal to or less than the amount to credit, and the PWUNIQUEID must match the unique identifier associated with the transaction to credit. Only transactions in a closed batch with a status of SETTLED can be credited.
PREAUTH Pre-authorise a card.
GETCONSUMERFEE Input the sale amount to get adjustment, tax and total transaction amounts. Relevant for merchants configured with Cash Discount or Convenience Fees.
CREATECUSTOMER Creates a Customer in the Paywire Vault.
GETCUSTOKENS Lists tokens stored against a given Customer.
STORETOKEN Validate a card and return a token.
REMOVETOKEN Delete an existing token from Paywire.
BATCHINQUIRY Get the current open batch summary.
CLOSE Close the current open batch.
SEARCHTRANS Query the database for transaction results.
DELETERECURRING Delete a recurring plan.
SENDRECEIPT Sends a receipt for a given transaction.

API One-Time-Sale

Card Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <COMPANYNAME>The Company</COMPANYNAME>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <EMAIL>jd@example.com</EMAIL>
      <ADDRESS1>1 The Street</ADDRESS1>
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <ZIP>12345</ZIP>
      <COUNTRY>US</COUNTRY>
      <PRIMARYPHONE>1234567890</PRIMARYPHONE>
      <WORKPHONE>1234567890</WORKPHONE>
      <PWMEDIA>CC</PWMEDIA>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>02</EXP_MM>
      <EXP_YY>22</EXP_YY>
      <CVV2>123</CVV2>
   </CUSTOMER>
</PAYMENTREQUEST>

E-Check Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <COMPANYNAME>The Company</COMPANYNAME>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <EMAIL>jd@example.com</EMAIL>
      <ADDRESS1>1 The Street</ADDRESS1>
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <ZIP>12345</ZIP>
      <COUNTRY>US</COUNTRY>
      <PRIMARYPHONE>1234567890</PRIMARYPHONE>
      <WORKPHONE>1234567890</WORKPHONE>
      <PWMEDIA>ECHECK</PWMEDIA>
      <BANKACCTTYPE>CHECKING</BANKACCTTYPE>
      <ROUTINGNUMBER>222224444</ROUTINGNUMBER>
      <ACCOUNTNUMBER>4242204082</ACCOUNTNUMBER>
   </CUSTOMER>
</PAYMENTREQUEST>

Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>A</PAYMETH>
    <PWUNIQUEID>112302</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXX4082</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>ACH</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>DECLINED</RESULT>
    <RESTEXT>  ERROR  0295   </RESTEXT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <AVSCODE>0</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>112301</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>VISA</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to process a Sale transaction, submit SALE in the <PWTRANSACTIONTYPE /> parameter along with the mandatory fields.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. SALE
PWSALEAMOUNT

int/decimal Amount of the transaction.
PWINVOICENUMBER string Merchant’s unique invoice number to be associated with this transaction. If not submitted, this will be generated by the gateway and returned in the XML response. 0/20, Alphanumeric
PWMEDIA

string Defines the payment method. Fixed options: CC and ECHECK.
CARDNUMBER

(✓)

int Card number to process payment with. Required only when CC is submitted in PWMEDIA.
EXP_MM

(✓)

string Card expiry month. Required only when CC is submitted in PWMEDIA. 2/2, >0, <=12
EXP_YY

(✓)

string Card expiry year. Required only when CC is submitted in PWMEDIA. 2/2
CVV2

(✓)

int Card Verification Value. Required only when CC is submitted in PWMEDIA. 3/4
BANKACCTTYPE

(✓)

string Type of Bank Account to process payment with. Required only when ECHECK is submitted in PWMEDIA. CHECKING, SAVINGS
ROUTINGNUMBER

(✓)

string Routing number of Bank Account to process payment with. Required only when ECHECK is submitted in PWMEDIA.
ACCOUNTNUMBER

(✓)

string Account number of Bank Account to process payment with. Required only when ECHECK is submitted in PWMEDIA.
ADDCUSTOMER bool Creates a customer and an associated token in the Paywire Vault and returns a PWCID and a PWTOKEN in the response when set to TRUE. Overrides REQUESTTOKEN if also submitted.
REQUESTTOKEN bool Creates a token in the Paywire Vault and returns a PWTOKEN in the response when set to TRUE. By default, when not submitted, a PWTOKEN is returned when CC is submitted in PWMEDIA but not for ECHECK.
PWCID string Paywire Customer Identifier. If REQUESTTOKEN is also submitted as TRUE, the created token will be associated with this customer.
PWTOKEN string Unique token representing a customer's card or account details stored on the Paywire Gateway. Use instead of submitting CARDNUMBER, EXP_MM, EXP_YY and CVV2 or ROUTINGNUMBER and ACCOUNTNUMBER.
CUSTOMERNAME string Full name of the customer, possibly different to the Account Holder.
FIRSTNAME string Account Holder's first name.
LASTNAME string Account Holder's last name.
COMPANYNAME string Customer's company name.
ADDRESS1 string Account Holder's primary address.
ADDRESS2 string Account Holder's secondary address.
CITY string Account Holder's city of residence.
STATE

(✓)

string Account Holder's state of residence. Required if configured with Convenience Fees.
COUNTRY string Account Holder's country of residence.
ZIP string Account Holder's address postal/zip code.
EMAIL string Account Holder's email address.
PRIMARYPHONE string Account Holder's primary phone number.
WORKPHONE string Account Holder's work phone number.
DISABLECF bool Overrides applying a Convenience Fee or Cash Discount when set to TRUE, if configured. Note that Sales Tax will also be disabled. Default: FALSE
ADJTAXRATE decimal Overrides the configured Sales Tax rate.
PWCUSTOMID1 string Custom third-party id to be associated with this transaction.
PWRECEIPTDESC string Extra information to be displayed on the receipt. 0/200
PWCASHIERID string Paywire-assigned cashier identifier.
SECCODE string SEC Code for ECHECK payments. 3/3
DESCRIPTION string Transaction custom description message. 0/100

API Recurring Sale

Request Example:

<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      ...
   </TRANSACTIONHEADER>
   <CUSTOMER>
      ...
   </CUSTOMER>
   <RECURRING>
      <STARTON>2018-01-01</STARTON>
      <FREQUENCY>W</FREQUENCY>
      <PAYMENTS>4</PAYMENTS>
   </RECURRING>
</PAYMENTREQUEST>

For brevity, parameters identical to the One-Time-Sale XML request structure have been summarized by ...

Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>000000001</PWCLIENTID>
    <AUTHCODE>012345</AUTHCODE>
    <AVSCODE>R</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>100896</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <EMAIL>jd@payscout.com</EMAIL>
    <CCTYPE>VISA</CCTYPE>
    <PWINVOICENUMBER>0987654321234567891</PWINVOICENUMBER>
    <RECURRINGID>113</RECURRINGID>
</PAYMENTRESPONSE>

Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>ERROR</RESULT>
    <RESTEXT>Invalid PAYMENTS</RESTEXT>
</PAYMENTRESPONSE>

In order to create a Recurring setup simply include the <RECURRING> block in addition to the One-Time-Sale parameters.

Parameter Required Type Description Validation
STARTON

Date Date the first payment must be charged. Date Format yyyy-mm-dd.
FREQUENCY

string The frequency at which recurring payments are charged. W: Weekly,
B: Bi-weekly,
M: Monthly,
H: Semi-monthly,
Q: Quarterly,
S: Semi-annual,
Y: Yearly
PAYMENTS

int Number of payments to process until the recurring setup is expired. 1/999

API PreAuth

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>PREAUTH</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567895</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWMEDIA>CC</PWMEDIA>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>12</EXP_MM>
      <EXP_YY>22</EXP_YY>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <AUTHCODE>092127</AUTHCODE>
    <AVSCODE>R</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>130909</PWUNIQUEID>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <CCTYPE>VISA</CCTYPE>
    <PWTOKEN>A39B7BD3NOK24CF12816</PWTOKEN>
    <PWINVOICENUMBER>0987654321234567895</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to process a Pre-Authorization transaction, submit PREAUTH in the <PWTRANSACTIONTYPE /> parameter. Mandatory fields are identical to the API One-Time-Sale.

API Void

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>VOID</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567892</PWINVOICENUMBER>
      <PWUNIQUEID>112301</PWUNIQUEID>
   </TRANSACTIONHEADER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>162</BATCHID>
    <PWCLIENTID>0000001403</PWCLIENTID>
    <PAYMETH>A</PAYMETH>
    <PWUNIQUEID>130903</PWUNIQUEID>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXX4082</MACCOUNT>
    <CCTYPE>ACH</CCTYPE>
    <PWINVOICENUMBER>0987654321234567892</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to process a Void transaction, submit VOID in the <PWTRANSACTIONTYPE /> parameter along with the mandatory fields.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. VOID
PWSALEAMOUNT

int/decimal Amount of original transaction. Must match.
PWINVOICENUMBER

string The merchants unique invoice number associated with this transaction.
PWUNIQUEID

int Unique transaction ID returned in the transaction response, associated with the transaction being voided.

API Credit

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>CREDIT</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567893</PWINVOICENUMBER>
      <PWUNIQUEID>130291</PWUNIQUEID>
   </TRANSACTIONHEADER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>112304</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>VISA</CCTYPE>
    <PWINVOICENUMBER>0987654321234567893</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to process a Credit transaction, submit CREDIT in the <PWTRANSACTIONTYPE /> parameter along with the mandatory fields.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. CREDIT
PWSALEAMOUNT

int/decimal Amount to refund. Less than or equal to the original transaction.
PWINVOICENUMBER

string The merchants unique invoice number associated with this transaction.
PWUNIQUEID

int Unique transaction ID returned in the transaction response, associated with the transaction being voided.
PWCUSTOMID1 string Custom third-party id to be associated with this transaction.

API Get Consumer Fee

Request Parameters

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>GETCONSUMERFEE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567896</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <ADJTAXRATE>15.00</ADJTAXRATE>
      <PWMEDIA>CC</PWMEDIA>
      <STATE>NY</STATE>
   </CUSTOMER>
</PAYMENTREQUEST>

For merchants configured with Cash Discount or Convenience Fees, submit GETCONSUMERFEE in the <PWTRANSACTIONTYPE /> parameter to retrieve the adjustment amount.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. GETCONSUMERFEE
PWSALEAMOUNT

int/decimal Sale amount.
PWINVOICENUMBER string The merchants unique invoice number associated with this transaction.
PWMEDIA

string Defines the payment method. Fixed options: CC and ECHECK.
DISABLECF bool Overrides applying Cash Discount or Convenience Fee when set to TRUE, if configured. Note that Sales Tax will also be disabled. Default: FALSE
ADJTAXRATE decimal Overrides the configured Sales Tax rate.
PWTOKEN string When submitted, returns customer or token details in the response.
STATE

(✓)

string Account Holder's state of residence. Required if configured with Convenience Fees.

Response Parameters

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>C</PAYMETH>
    <PWADJDESC>Convenience Fee</PWADJDESC>
    <PWSALETAX>0.00</PWSALETAX>
    <PWADJAMOUNT>5.00</PWADJAMOUNT>
    <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
    <AMOUNT>15.00</AMOUNT>
    <PWINVOICENUMBER>0987654321234567896</PWINVOICENUMBER>
    <CDSUMMARY>
        <MERCHANTNAME>Merchant ABC</MERCHANTNAME>
        <MID>987345098456</MID>
        <MERCHANTTYPE>F</MERCHANTTYPE>
        <ADJTAXRATE>0.00</ADJTAXRATE>
        <CARDSALESAMOUNT>10.00</CARDSALESAMOUNT>
        <CARDADJAMOUNT>5.00</CARDADJAMOUNT>
        <CARDTAXAMOUNT>0.00</CARDTAXAMOUNT>
        <CARDTRANSACTIONAMOUNT>15.00</CARDTRANSACTIONAMOUNT>
        <CARDAMOUNTBEFORETAX>15.00</CARDAMOUNTBEFORETAX>
        <CASHSALESAMOUNT>10.00</CASHSALESAMOUNT>
        <CASHADJAMOUNT>5.00</CASHADJAMOUNT>
        <CASHTAXAMOUNT>0.00</CASHTAXAMOUNT>
        <CASHTRANSACTIONAMOUNT>15.00</CASHTRANSACTIONAMOUNT>
        <CASHAMOUNTBEFORETAX>15.00</CASHAMOUNTBEFORETAX>
        <CDDESCRIPTIONVPOS>Attention: 
            <br />Please advise the payee or customer that a 'Convenience Fee' will be charged when paying on-line or over the phone. They can otherwise opt to pay in-store or by mail.
        </CDDESCRIPTIONVPOS>
        <CDDESCRIPTIONOSBP>Attention: 
            <br />Please be advised that a 'Convenience Fee' is charged when paying on-line or over the phone. You can otherwise opt to pay in-store or by mail.
        </CDDESCRIPTIONOSBP>
    </CDSUMMARY>    
</PAYMENTRESPONSE>
Parameter Type Description Options
RESULT string Status for the transaction. APPROVAL, SUCCESS, DECLINED, ERROR
PWCLIENTID string Paywire-generated unique merchant identifier.
PAYMETH string Describes the payment method. C: Card,
A: ACH
PWADJDESC string The description for the adjustment as set in the merchant config.
PWSALETAX decimal The tax amount calculated by the gateway, based on the Sales Tax rate set in the merchant config.
PWADJAMOUNT decimal The adjustment amount calculated by the gateway, based on the Adjustment rate or fixed amount set in the merchant config. This can be either the Cash Discount markdown or the Convenience Fee.
PWSALEAMOUNT decimal The Sale amount submitted in the request.
AMOUNT decimal The total amount of the transaction, including tax and any adjustments.
PWINVOICENUMBER string The merchants unique invoice number associated with this transaction.
MERCHANTNAME string Name of the merchant as set in the merchant config.
MID string The processor's merchant identifier.
MERCHANTTYPE string The type of merchant as set in the merchant config. A: General + Single SAP,
B: Medical,
C: General + Split SAP,
D: Remote Check + SAP Invoices,
E: Cash Discount,
F: Convenience Fees
ADJTAXRATE decimal The Sales Tax rate as set in the merchant config or submitted in the request.
CARDSALESAMOUNT decimal The Card Sale amount before tax and any adjustments. Relevant for Cash Discount.
CARDADJAMOUNT decimal The Adjustment amount for a Card transaction. Relevant for Cash Discount.
CARDTAXAMOUNT decimal The calculated Sales Tax amount for a Card transaction. Relevant for Cash Discount.
CARDTRANSACTIONAMOUNT decimal The total amount for a Card transaction after tax and any adjustments. Relevant for Cash Discount.
CARDAMOUNTBEFORETAX decimal The adjusted amount for a Card transaction before adding tax. Relevant for Cash Discount.
CASHSALESAMOUNT decimal The Cash Sale amount before tax and any adjustments. Relevant for Cash Discount.
CASHTAXAMOUNT decimal The calculated Sales Tax amount for a Cash transaction. Relevant for Cash Discount.
CASHTRANSACTIONAMOUNT decimal The total amount for a Cash transaction after tax and any adjustments. Relevant for Cash Discount.
CASHAMOUNTBEFORETAX decimal The adjusted amount for a Cash transaction before adding tax. Relevant for Cash Discount.
CDDESCRIPTIONVPOS string The descriptive text set in the merchant config. to be displayed on the VPOS payment page.
CDDESCRIPTIONOSBP string The descriptive text set in the merchant config. to be displayed on the OSBP payment page.
AHNAME string ACH Account Holder full name. Returned only when ECHECK in PWMEDIA and a valid PWTOKEN are submitted in the request.
MACCOUNT string Masked Card or Account number. Returned only when a valid PWTOKEN is submitted in the request.
ROUTINGNUMBER string U.S. Bank Account routing number. Returned only when ECHECK in PWMEDIA and a valid PWTOKEN are submitted in the request.
BANKACCTTYPE string Type of Bank Account. Returned only when ECHECK in PWMEDIA and a valid PWTOKEN are submitted in the request. CHECKING, SAVINGS
EXP_MM string Card Expiry month. Returned only when CC in PWMEDIA and a valid PWTOKEN are submitted in the request.
EXP_YY string Card Expiry year. Returned only when CC in PWMEDIA and a valid PWTOKEN are submitted in the request.
FIRSTNAME string Account Holder first name. Returned only when a valid PWTOKEN is submitted in the request.
LASTNAME string Account Holder last name. Returned only when a valid PWTOKEN is submitted in the request.

API Create Customer

Request Example

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
    <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <PWUSER>{username}</PWUSER>
        <PWPASS>{password}</PWPASS>
        <PWTRANSACTIONTYPE>CREATECUSTOMER</PWTRANSACTIONTYPE>
    </TRANSACTIONHEADER>
    <DETAILRECORDS />
    <CUSTOMER>
        <COMPANYNAME>Company ABC</COMPANYNAME>
        <FIRSTNAME>John</FIRSTNAME>
        <LASTNAME>Doe</LASTNAME>
        <EMAIL>jd@example.com</EMAIL>
        <ADDRESS1>1, The Street</ADDRESS1>
        <ADDRESS2>Unit 10</ADDRESS2>
        <CITY>Los Angeles</CITY>
        <STATE>CA</STATE>
        <ZIP>12345</ZIP>
        <COUNTRY>US</COUNTRY>
        <PRIMARYPHONE>1234567890</PRIMARYPHONE>
        <WORKPHONE>1234567890</WORKPHONE>
        <DESCRIPTION>Description</DESCRIPTION>
        <PWCUSTOMID1>AA000123</PWCUSTOMID1>
    </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PWCID>P0000000001</PWCID>
    <PWCUSTOMID1>AA000123</PWCUSTOMID1>
    <PWINVOICENUMBER>0987654321234127820</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To create a customer in the Paywire Vault submit CREATECUSTOMER in the <PWTRANSACTIONTYPE /> parameter. The gateway will return a customer identifier in <PWCID> if successful.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. CREATECUSTOMER
COMPANYNAME string Customer's company name.
ADDRESS1 string Customer's primary address.
ADDRESS2 string Customer's secondary address.
CITY string Customer's city of residence.
STATE string Customer's state of residence.
COUNTRY string Customer's country of residence.
ZIP string Customer's address postal/zip code.
EMAIL string Customer's email address.
PRIMARYPHONE string Customer's primary phone number.
WORKPHONE string Customer's work phone number.
DESCRIPTION string Customer description. 0/100
PWCUSTOMID1 string Custom third-party id to be associated with this customer.

API List Customer Tokens

Request Example

<PAYMENTREQUEST>
    <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <PWUSER>{username}</PWUSER>
        <PWPASS>{password}</PWPASS>
        <PWTRANSACTIONTYPE>GETCUSTOKENS</PWTRANSACTIONTYPE>
    </TRANSACTIONHEADER>
    <DETAILRECORDS />
    <CUSTOMER>
        <PWCID>P0000000001</PWCID>
    </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PWCID>P0000000001</PWCID>
    <TOKENLIST>&lt;PWTOKENDETAIL&gt;&lt;PWTOKEN&gt;T2C5243173034401&lt;/PWTOKEN&gt;&lt;PWMEDIA&gt;CC&lt;/PWMEDIA&gt;&lt;CCTYPE&gt;MC&lt;/CCTYPE&gt;&lt;MACCOUNT&gt;XXXXXXXXXXXX0608&lt;/MACCOUNT&gt;&lt;EXP_MM&gt;02&lt;/EXP_MM&gt;&lt;EXP_YY&gt;22&lt;/EXP_YY&gt;&lt;/PWTOKENDETAIL&gt;</TOKENLIST>
    <PWINVOICENUMBER>19157753802663200</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To list tokens stored against a customer in the Paywire Vault submit GETCUSTOKENS in the <PWTRANSACTIONTYPE /> parameter, along with the relevant <PWCID>. The gateway will return the tokens in <TOKENLIST> if successful.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. GETCUSTOKENS
PWCID

string Identifier for Customer stored in the Paywire Vault.

API Store Token

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>STORETOKEN</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567897</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWMEDIA>CC</PWMEDIA>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>02</EXP_MM>
      <EXP_YY>22</EXP_YY>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <AVSCODE>0</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>130310</PWUNIQUEID>
    <AMOUNT>0.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <CCTYPE>VISA</CCTYPE>
    <PWTOKEN>56A6603A4141234A2817</PWTOKEN>
    <PWINVOICENUMBER>0987654321234567897</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to store a customer's payment details (card or e-check) submit STORETOKEN in the <PWTRANSACTIONTYPE /> parameter. The gateway will return a token in <PWTOKEN> if successful.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. STORETOKEN
PWSALEAMOUNT

int/decimal Set to 0, otherwise a SALE is processed.
PWINVOICENUMBER

string The merchants unique invoice number associated with this transaction.
PWMEDIA

string Defines the payment method. Fixed options: CC and ECHECK.
CARDNUMBER

int Card number to be stored. Required only when CC is submitted in PWMEDIA.
EXP_MM

string Card expiry month. Required only when CC is submitted in PWMEDIA. 2/2, >0, <=12
EXP_YY

string Card expiry year. Required only when CC is submitted in PWMEDIA. 2/2
ROUTINGNUMBER

(✓)

string Routing number of Bank Account being stored. Required only when ECHECK is submitted in PWMEDIA.
ACCOUNTNUMBER

(✓)

string Account number of Bank Account being stored. Required only when ECHECK is submitted in PWMEDIA.
BANKACCTTYPE

(✓)

string Type of Bank Account to process payment with. Required only when ECHECK is submitted in PWMEDIA. CHECKING, SAVINGS
ADDCUSTOMER bool Creates a customer in the Paywire Vault associated with the token, and returns a PWCID in the response when set to TRUE.
PWCID string Paywire Customer Identifier. When submitted, the created token will be associated with this customer.

API Token Sale

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>20</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567898</PWINVOICENUMBER>  
      <POSINDICATOR/>
      <PWADJAMOUNT/>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWMEDIA>CC</PWMEDIA>
      <PWTOKEN>56A6603A41444122817</PWTOKEN>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <AUTHCODE>081257</AUTHCODE>
    <AVSCODE>R</AVSCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>120115</PWUNIQUEID>
    <AMOUNT>20.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <CCTYPE>VISA</CCTYPE>
    <PWTOKEN>56A6603A41444122817</PWTOKEN>
    <PWINVOICENUMBER>0987654321234567898</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To process a SALE using a token, simply replace the Card or E-Check payment details with the <PWTOKEN> parameter returned by the gateway when storing tokens. Otherwise, the same mandatory fields as the API One-Time-Sale apply.

Parameter Required Type Description Validation
PWTOKEN

string Token returned by the Paywire Gateway.
POSINDICATOR string Used in conjunction with Token Sales to apply Convenience Fees or Cash Discount for recurring payments handled outside Paywire. Submit this in the TRANSACTIONHEADER block. C: Regular Token Sale
I: First Payment of a Recurring Plan
R: Subsequent Recurring Payment
T: Last Payment of a Recurring Plan
P: Periodic Payment
PWADJAMOUNT decimal Adjustment amount. Used to set the Convenience Fee amount to be charged for this transaction. Allowed only when submitted with POSINDICATOR set to P. Submitting amounts larger than that configured for the merchant will be ignored. >0

API Remove Token

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>REMOVETOKEN</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567899</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWCTRANSTYPE>3</PWCTRANSTYPE>
      <PWMEDIA>CC</PWMEDIA>
      <PWTOKEN>56A6603A41444122817</PWTOKEN>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>C</PAYMETH>
    <AMOUNT>0.00</AMOUNT>
    <PWINVOICENUMBER>0987654321234567899</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To remove a token, submit REMOVETOKEN in the <PWTRANSACTIONTYPE /> parameter along with the token to delete in <PWTOKEN />.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. REMOVETOKEN
PWTOKEN

string Token returned by the Paywire Gateway.

API Batch Inquiry

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>BATCHINQUIRY</PWTRANSACTIONTYPE>
      <PWINVOICENUMBER>0987654321234567900</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER />
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <BATCHID>1</BATCHID>
    <SALESTOTAL>109.31</SALESTOTAL>
    <SALESRECS>10</SALESRECS>
    <CREDITAMT>0.00</CREDITAMT>
    <CREDITRECS>0</CREDITRECS>
    <NETCRAMT>109.31</NETCRAMT>
    <NETCRRECS>10</NETCRRECS>
    <VOIDAMT>2.25</VOIDAMT>
    <VOIDRECS>4</VOIDRECS>
    <PWINVOICENUMBER>0987654321234567900</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To get information on the open batch, submit BATCHINQUIRY in the <PWTRANSACTIONTYPE /> parameter. This will return summary information.

Parameter Required Type Description Validation
PWTRANSACTIONTYPE

string Defines what transaction to process. BATCHINQUIRY

API Close Batch

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>CLOSE</PWTRANSACTIONTYPE>
      <PWINVOICENUMBER>0987654321234567901</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <SALESTOTAL>109.31</SALESTOTAL>
    <SALESRECS>10</SALESRECS>
    <CREDITAMT>0.00</CREDITAMT>
    <CREDITRECS>0</CREDITRECS>
    <NETCRAMT>109.31</NETCRAMT>
    <NETCRRECS>10</NETCRRECS>
    <VOIDAMT>2.25</VOIDAMT>
    <VOIDRECS>4</VOIDRECS>
    <PWINVOICENUMBER>0987654321234567901</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To close an open batch for settlement, submit CLOSE in the <PWTRANSACTIONTYPE /> parameter.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. CLOSE

API Search Transactions

Request Parameters

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SEARCHTRANS</PWTRANSACTIONTYPE>
   </TRANSACTIONHEADER>
   <SEARCHCONDITION>
      <COND_DATEFROM>2018-10-01 00:00</COND_DATEFROM>
      <COND_DATETO>2018-10-26 14:00</COND_DATETO>
      <COND_UNIQUEID />
      <COND_BATCHID />
      <COND_TRANSAMT />
      <COND_TRANSTYPE>ALL</COND_TRANSTYPE>
      <COND_RESULT>ALL</COND_RESULT>
      <COND_CARDTYPE>VISA</COND_CARDTYPE>
   </SEARCHCONDITION>
</PAYMENTREQUEST>

To search transactions within the gateway submit SEARCHTRANS in the <PWTRANSACTIONTYPE /> parameter along with the desired <SEARCHCONDITION /> values.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. SEARCHTRANS
COND_DATEFROM DateTime Search date range from. Date Format yyyy-mm-dd HH:MM.
COND_DATETO DateTime Search date range to. Date Format yyyy-mm-dd HH:MM.
COND_UNIQUEID int Search by transaction Unique ID returned by the gateway.
COND_BATCHID string Search by Batch Id returned by the gateway
COND_TRANSAMT int/decimal Search by transaction amount.
COND_TRANSTYPE string Search by transaction type. Fixed options: ALL, SALE, CREDIT, VOID
COND_RESULT string Search by transaction result returned by the gateway. Fixed options: ALL, SUCCESS, DECLINED, VOIDED, SETTLED, CAPTURED, VERIFIED, REJECTED, ERROR
COND_CARDTYPE string Search by the card type used for the transaction. Fixed options: ALL, VISA, MC, DISC, AMEX, ACH, REMOTE
COND_LASTFOUR int Search by the last four digits of the account or card used in the transaction searched. 4/4
COND_CUSTOMERID string Search by the Paywire customer identifier returned when creating a token.
COND_RECURRINGID int Search by the recurring identifier returned when creating a recurring plan.
COND_PWINVOICENUMBER string Search by the merchant-submitted or Paywire-generated unique invoice number associated with the transaction. 0/20, Alphanumeric
COND_PWCUSTOMID1 string Search by the custom third-party identifier associated with the transaction.

Response Parameters

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <SEARCHRESULT>&lt;PWPAYDETAIL&gt;&lt;PWUID&gt;130554&lt;/PWUID&gt;&lt;BATCHID&gt;149&lt;/BATCHID&gt;&lt;TRANSTYPE&gt;SALE&lt;/TRANSTYPE&gt;&lt;CARDTYPE&gt;VISA&lt;/CARDTYPE&gt;&lt;CARDNUM&gt;X0267&lt;/CARDNUM&gt;&lt;TRANSAMOUNT&gt;10.00&lt;/TRANSAMOUNT&gt;&lt;ADJAMOUNT&gt;0.00&lt;/ADJAMOUNT&gt;&lt;TIPAMOUNT&gt;0.00&lt;/TIPAMOUNT&gt;&lt;TAXAMOUNT&gt;0.00&lt;/TAXAMOUNT&gt;&lt;CREDITAMOUNT&gt;0.00&lt;/CREDITAMOUNT&gt;&lt;AUTHCODE&gt;024587&lt;/AUTHCODE&gt;&lt;RESULT&gt;VOIDED&lt;/RESULT&gt;&lt;NAME&gt;John Doe&lt;/NAME&gt;&lt;RECURRINGID&gt;0&lt;/RECURRINGID&gt;&lt;TRANSTIME&gt;10/03/2018 01:58 PM&lt;/TRANSTIME&gt;&lt;PWINVOICENUMBER&gt;001001001001&lt;/PWINVOICENUMBER&gt;&lt;/PWPAYDETAIL&gt;&lt;PWPAYDETAIL&gt;&lt;PWUID&gt;130555&lt;/PWUID&gt;&lt;BATCHID&gt;149&lt;/BATCHID&gt;&lt;ORGTRANSID&gt;130554&lt;/ORGTRANSID&gt;&lt;TRANSTYPE&gt;VOID&lt;/TRANSTYPE&gt;&lt;CARDTYPE&gt;VISA&lt;/CARDTYPE&gt;&lt;CARDNUM&gt;X0267&lt;/CARDNUM&gt;&lt;TRANSAMOUNT&gt;10.00&lt;/TRANSAMOUNT&gt;&lt;ADJAMOUNT&gt;0.00&lt;/ADJAMOUNT&gt;&lt;TIPAMOUNT&gt;0.00&lt;/TIPAMOUNT&gt;&lt;TAXAMOUNT&gt;0.00&lt;/TAXAMOUNT&gt;&lt;CREDITAMOUNT&gt;0.00&lt;/CREDITAMOUNT&gt;&lt;AUTHCODE&gt;024587&lt;/AUTHCODE&gt;&lt;RESULT&gt;VOIDED&lt;/RESULT&gt;&lt;NAME&gt; &lt;/NAME&gt;&lt;RECURRINGID&gt;0&lt;/RECURRINGID&gt;&lt;TRANSTIME&gt;10/03/2018 01:59 PM&lt;/TRANSTIME&gt;&lt;PWINVOICENUMBER&gt;001001001001&lt;/PWINVOICENUMBER&gt;&lt;/PWPAYDETAIL&gt; ... </SEARCHRESULT>
    <PWINVOICENUMBER>18312144115956459</PWINVOICENUMBER>
</PAYMENTRESPONSE>

The SEARCHRESULT value has been summarized by ... for brevity.

The gateway will return the following parameters in the XML reponse:

Parameter Type Description Options
PWUID int Unique transaction ID associated with the transaction(s) being searched.
BATCHID int Unique identifier for the batch containing the transaction(s) being searched.
ORGTRANSID string Relevant only for VOID and CREDIT results: original unique transaction ID of a referenced transaction.
TRANSTYPE string The type of transaction(s) being searched. See API Transaction Types
CARDTYPE string The type of card the transaction(s) being searched were processed with.
CARDNUM int Last four digits of the card or account number used to complete the transaction(s) being searched.
TRANSAMOUNT decimal Amount of transaction(s) being searched.
ADJAMOUNT decimal Adjustment amount of transaction.
TIPAMOUNT decimal Tip amount of transaction.
TAXAMOUNT decimal Tax amount of transaction.
CREDITAMOUNT decimal Relevant only for refunded transactions: the amount credited back to the customer.
DESCRIPTION string Transaction custom description message.
AUTHCODE string Authorization code associated with the Authorization transaction.
RESULT string Status for the transaction. APPROVAL, SUCCESS, DECLINED, ERROR
NAME string Account holder full name.
CUSTOMERID string Paywire customer identifier associated with a token.
RECURRINGID int Recurring identifier of a recurring plan that a transaction forms part of.
TRANSTIME DateTime Timestamp of the transaction.
PWINVOICENUMBER string Merchant’s unique invoice number to be associated with this transaction. If not submitted, this will be generated by the gateway and returned in the XML response.
PWCUSTOMID1 string Custom third-party id to be associated with this transaction.
PWCUSTOMID2 string Processor-specific transaction unique identifier. Not always applicable.
PWCUSTOMID3 string Processor-specific ACH transaction split-fee paydetail identifier. Not always applicable.
POSINDICATOR string Used in conjunction with Token Sales to apply Convenience Fees or Cash Discount for recurring payments handled outside Paywire. C: Regular Token Sale
I: First Payment of a Recurring Plan
R: Subsequent Recurring Payment
T: Last Payment of a Recurring Plan

API Send Receipt

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SENDRECEIPT</PWTRANSACTIONTYPE>
      <PWUNIQUEID>112302</PWUNIQUEID>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <EMAIL>jd@example.com</EMAIL>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PWINVOICENUMBER>18312144115956459</PWINVOICENUMBER>
</PAYMENTRESPONSE>

To send a receipt for an existing transaction, submit SENDRECEIPT in the <PWTRANSACTIONTYPE /> parameter along with the required parameters.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. SENDRECEIPT
PWUNIQUEID

int Unique transaction ID returned in the transaction response, associated with the transaction to send a receipt for.
EMAIL

string Account Holder's email address.

API Level 3 Processing

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <COMPANYNAME>The Company</COMPANYNAME>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <EMAIL>jd@example.com</EMAIL>
      <ADDRESS1>1 The Street</ADDRESS1>
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <ZIP>12345</ZIP>
      <COUNTRY>US</COUNTRY>
      <PRIMARYPHONE>1234567890</PRIMARYPHONE>
      <WORKPHONE>1234567890</WORKPHONE>
      <PWMEDIA>CC</PWMEDIA>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>02</EXP_MM>
      <EXP_YY>22</EXP_YY>
      <CVV2>123</CVV2>
   </CUSTOMER>
   <LEVEL3>
      <DUTYAMOUNT>1.00</DUTYAMOUNT>
      <DISCOUNTAMOUNT>0.55</DISCOUNTAMOUNT>
      <SHIPAMOUNT>2.50</SHIPAMOUNT>
      <SHIPFROMZIP>09876</SHIPFROMZIP>
      <SHIPTOZIP>12345</SHIPTOZIP>
      <DESTCOUNTRYCODE>US</DESTCOUNTRYCODE>
      <LINEITEMCOUNT>2</LINEITEMCOUNT>
      <PONUMBER>A0L3112FF4</PONUMBER>
      <MERCHANTTAXID>837431974973</MERCHANTTAXID>
      <CUSTOMERTAXID>444264662642</CUSTOMERTAXID>
      <COMMODITYCODE>50340000</COMMODITYCODE>
      <LINEITEMS>
         <LINEITEM>
            <ITEM_DESCRIPTION>Frozen Berries</ITEM_DESCRIPTION>
            <ITEM_CODE>00003154</ITEM_CODE>
            <ITEM_QUANTITY>2</ITEM_QUANTITY>
            <ITEM_UNITMEASURE>Each</ITEM_UNITMEASURE>
            <ITEM_UNITCOST>3.00</ITEM_UNITCOST>
            <ITEM_TAXAMOUNT>0.60</ITEM_TAXAMOUNT>
            <ITEM_TAXRATE>10.00</ITEM_TAXRATE>
            <ITEM_DISCOUNTIND/>
            <ITEM_DISCOUNT>0.33</ITEM_DISCOUNT>
            <ITEM_TOTALAMOUNT>6.27</ITEM_TOTALAMOUNT>
            <ITEM_COMMODITYCODE>50340000</ITEM_COMMODITYCODE>
            <ITEM_TAXTYPE/>
            <ITEM_NETGROSSIND/>
            <ITEM_EXTAMOUNT/>
         </LINEITEM>
         <LINEITEM>
            <ITEM_DESCRIPTION>Frozen Apples</ITEM_DESCRIPTION>
            <ITEM_CODE>00003102</ITEM_CODE>
            <ITEM_QUANTITY>1</ITEM_QUANTITY>
            <ITEM_UNITMEASURE>Each</ITEM_UNITMEASURE>
            <ITEM_UNITCOST>4.00</ITEM_UNITCOST>
            <ITEM_TAXAMOUNT>0.40</ITEM_TAXAMOUNT>
            <ITEM_TAXRATE>10.00</ITEM_TAXRATE>
            <ITEM_DISCOUNTIND/>
            <ITEM_DISCOUNT>0.22</ITEM_DISCOUNT>
            <ITEM_TOTALAMOUNT>4.18</ITEM_TOTALAMOUNT>
            <ITEM_COMMODITYCODE>50340000</ITEM_COMMODITYCODE>
            <ITEM_TAXTYPE/>
            <ITEM_NETGROSS_IND/>
            <ITEM_EXTAMOUNT/>
         </LINEITEM>         
      </LINEITEMS>
   </LEVEL3>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>1</BATCHID>
    <PWCLIENTID>0000000001</PWCLIENTID>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>112387</PWUNIQUEID>
    <AHNAME>John Doe</AHNAME>
    <AMOUNT>10.45</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
    <EMAIL>jd@example.com</EMAIL>
    <CCTYPE>VISA</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

The payment card processing system is set up on three levels:

  1. Level 1 transactions for domestic card holders using personal cards.
    • Data includes standard card information such as the card number, card expiration date, billing address, zip code and invoice number.
  2. Level 2 transactions for domestic corporate cards.
    • Data required to qualify for this level includes a summary of applicable taxes, customer references and purchase order numbers on top of Level 1 data.
  3. Level 3 transactions for government-issued credit cards or corporate cards.
    • Data to include line item details with product codes, description, quantity, and unit costs on top of Level 1 and Level 2 data.

In order to process Level 3 transactions, please include the required fields below with each payment request.

The following need to be submitted in the LEVEL3 block:

Parameter Required Type Description Validation
DUTYAMOUNT

int Duty amount in the transaction.
DISCOUNTAMOUNT

(✓)

int/decimal The discount amount applied to the transaction. Required when processing a transaction using VISA.
SHIPAMOUNT

int/decimal The shipping cost in the total transaction amount.
SHIPFROMZIP

string The originator's ZIP code. 1/9
SHIPTOZIP

string The destination's ZIP code. 1/9
DESTCOUNTRYCODE

string The destination's country code. 2/3, ISO-3166 codes
LINEITEMCOUNT

int Count of line items being submitted. 1/999
PONUMBER string Purchase Order number for the transaction. 0/60
MERCHANTTAXID

(✓)

string Merchant VAT tax number. Required when processing a transaction using VISA. 0/20
CUSTOMERTAXID

(✓)

string Customer VAT registration number. Required when processing a transaction using VISA. 0/20
COMMODITYCODE

(✓)

string Summary Commodity Code. Required when processing a transaction using VISA. 0/4

The following need to be submitted in the LINEITEM tags within LINEITEMS, nested under the LEVEL3 block.

Parameter Required Type Description Validation
ITEM_DESCRIPTION

string Description of the item. 1/35
ITEM_CODE

(✓)

string Product code, identifier or SKU. Required when processing a transaction using VISA or mastercard. 0/12
ITEM_QUANTITY

decimal Product quantity.
ITEM_UNITMEASURE

(✓)

string Unit of measure for the line item. Required when processing a transaction using VISA or mastercard. 0/12
ITEM_UNITCOST

string Cost of item per unit of measure before tax/discount. 1/12
ITEM_TAXAMOUNT

(✓)

string Tax amount for item. Required when processing a transaction using VISA or mastercard. 0/12
ITEM_TAXRATE

(✓)

decimal Tax rate for item. Required when processing a transaction using VISA or mastercard.
ITEM_DISCOUNTIND

(✓)

string Identifies whether a discount has been applied. Required when processing a transaction using mastercard. Options: Y, N
ITEM_DISCOUNT

(✓)

string Discount per item. Required when processing a transaction using VISA or mastercard. 0/12
ITEM_TOTALAMOUNT

(✓)

string Total amount of this line item. Required when processing a transaction using VISA. 0/12
ITEM_COMMODITYCODE

(✓)

string Commodity Code. Required when processing a transaction using VISA. 0/12
ITEM_TAXTYPE

(✓)

string Tax type. Required when processing a transaction using mastercard. 0/4
ITEM_NETGROSSIND

(✓)

string Indicates whether the submitted amount is Net or Gross. Required when processing a transaction using mastercard. Options:
N - Net,
G - Gross
ITEM_EXTAMOUNT

(✓)

string Extended item amount. Required when processing a transaction using mastercard.

OSBP Reference

The OSBP expedites integration with the Paywire Gateway, moving PCI out-of-scope by collecting all card and ACH data on an externally hosted PCI-Certified payment page.

OSBP Overview

Source Code Example:


// not possible using cURL

// Sending Page
protected void PaymentButton(object sender, EventArgs e)
{
     string url = "https://dbstage1.paywire.com/OSBP/pwosbp.aspx";
     string content = {XML Payload};
     if !(content == "")
     {
         httpPostForm(content, url);
     }
}

private void httpPostForm(string content, string url)
{
     System.Web.HttpContext.Current.Response.Clear();
     System.Web.HttpContext.Current.Response.Write("<html><head></head>");
     System.Web.HttpContext.Current.Response.Write(string.Format("<body onload=\"document.{0}.submit();\">", "newForm"));
     System.Web.HttpContext.Current.Response.Write("<form name=\"newForm\" target=\"_parent\" method=\"POST\" action=\"" + url + "\">");
     System.Web.HttpContext.Current.Response.Write(string.Format("<input type=hidden name=\"PWREQUEST\"value=\"{0}\">", base64Encode(content)));
     System.Web.HttpContext.Current.Response.Write("</form>");
     System.Web.HttpContext.Current.Response.Write("</body></html>");
}

public string base64Encode(string data)
{
     try
     {
          byte[] encData_byte = new byte[data.Length];
          encData_byte = System.Text.Encoding.UTF8.GetBytes(data);
          string encodedData = Convert.ToBase64string(encData_byte);
          return encodedData;
     }
     catch (Exception e)
     {
         throw new Exception("Error in base64Encode" + e.Message);
     }
}


// Receiving Page
protected void Page_Load(object sender, EventArgs e)
{
     string requeststring = "";
     StreamReader reader = new StreamReader(this.Request.InputStream);
     requeststring = reader.ReadToEnd();
     requeststring = requeststring.Substring(11);
     requeststring = Server.UrlDecode(requeststring);
     Label1.Text = base64Decode(requeststring);
}

public string base64Decode(string data)
{
     try
     {
          System.Text.UTF8Encoding encoder = new System.Text.UTF8Encoding();
          System.Text.Decoder utf8Decode = encoder.GetDecoder();
          byte[] todecode_byte = Convert.FromBase64string(data);
          int charCount = utf8Decode.GetCharCount(todecode_byte, 0, todecode_byte.Length);
          char[] decoded_char = new char[charCount];
          utf8Decode.GetChars(todecode_byte, 0, todecode_byte.Length, decoded_char, 0);
          string result = new string(decoded_char);
          return result;
     }
     catch (Exception e)
     {
          throw new Exception("Error in base64Decode" + e.Message);
     }
}
' Sending Page
Protected Sub Button1_Click(ByVal sender As Object, ByVal e As EventArgs) Handles Button1.Click
  Dim url As string = "https://dbstage1.paywire.com/OSBP/pwosbp.aspx"
  Dim content As string = {XML Payload}
  If TextBox1.Text = "" Then
  Else
  HTTPPostForm(content, url)
  End If
End Sub

Private Sub HTTPPostForm(ByVal content As string, ByVal url As string)
  System.Web.HttpContext.Current.Response.Clear()
  System.Web.HttpContext.Current.Response.Write("<html><head></head>")
  System.Web.HttpContext.Current.Response.Write(string.Format("<body onload=""document.{0}.submit();"">", "newForm"))
  System.Web.HttpContext.Current.Response.Write("<form name=""newForm"" target=""_parent""method=""POST"" action=""" & url & """>")
  System.Web.HttpContext.Current.Response.Write(string.Format("<input type=hidden name=""PWREQUEST""value=""{0}"">", base64Encode(content)))
  System.Web.HttpContext.Current.Response.Write("</form>")
  System.Web.HttpContext.Current.Response.Write("</body></html>")
End Sub

Public Function base64Encode(ByVal data As string) As string
  Try
    Dim encData_byte As Byte() = New Byte(data.Length - 1) {}
    encData_byte = System.Text.Encoding.UTF8.GetBytes(data)
    Dim encodedData As string = Convert.ToBase64string(encData_byte)
    Return encodedData
  Catch e As Exception
    Throw New Exception("Error in base64Encode" + e.Message)
  End Try
End Function


' Receiving Page   
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
  Dim requeststring As string = ""
  Dim reader As New StreamReader(Me.Request.InputStream)
  requeststring = reader.ReadToEnd()
  requeststring = requeststring.Substring(11)
  requeststring = Server.UrlDecode(requeststring)
  Label1.Text = base64Decode(requeststring)
End Sub

Public Function base64Decode(ByVal data As string) As string
  Try
    Dim encoder As New System.Text.UTF8Encoding()
    Dim utf8Decode As System.Text.Decoder = encoder.GetDecoder()
    Dim todecode_byte As Byte() = Convert.FromBase64string(data)
    Dim charCount As Integer = utf8Decode.GetCharCount(todecode_byte, 0, todecode_byte.Length)
    Dim decoded_char As Char() = New Char(charCount - 1) {}
    utf8Decode.GetChars(todecode_byte, 0, todecode_byte.Length, decoded_char, 0)
    Dim result As string = New [string](decoded_char)
    Return result
  Catch e As Exception
    Throw New Exception("Error in base64Decode" + e.Message)
  End Try
End Function

XML Payload is the only variable between different transaction types.

To process payments using the Paywire OSBP, you must:

  1. Optionally collect non-PCI customer information such as Name, Address and Contact information from your website.
  2. Create a Sale XML request string including Authentication parameters, Approval URL and Decline URL.
  3. Perform a HTTP POST with a HTML form containing the XML request string to the OSBP endpoint using the relevant URL.
  4. Customer is redirected to the Paywire OSBP, possibly with the option to choose a Payment Method.
  5. Customer completes or cancels the payment.
  6. The Paywire OSBP returns a HTTP POST with an XML response to the Approval or Decline URL, depending on the result of the transaction.

OSBP Process Flowchart

OSBP Endpoints

The same OSBP endpoint is available for all requests, across all environments.

POST /OSBP/pwosbp.aspx

Content-Type: text/xml

OSBP Transaction Types

The Paywire OSBP only supports SALE transactions. Please use the API to post Voids and Credits.

Value Description
SALE Charge a card or bank account (if applicable).

OSBP PWCTRANSTYPE

Use this to define pre-set behaviours for the chosen Transaction Type.

Value Description
3 One-time transaction only. No customer record created.
4 Process a Sale or Authorization and add a new token for OSBP and VPOS usage.
5 Recurring, add a new token for OSBP and VPOS usage.

OSBP One-Time-Sale

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
      <PWAPPROVALURL>https://send.paywire.com/Receive.aspx</PWAPPROVALURL>
      <PWDECLINEURL>https://send.paywire.com/Receive.aspx</PWDECLINEURL>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWCTRANSTYPE>3</PWCTRANSTYPE>
      <COMPANYNAME>The Company</COMPANYNAME>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <ADDRESS1>1 The Street</ADDRESS1>
      <ADDRESS2 />
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <ZIP>12345</ZIP>
      <COUNTRY>US</COUNTRY>
      <EMAIL>jd@example.com</EMAIL>
      <PRIMARYPHONE>410-516-8000</PRIMARYPHONE>
   </CUSTOMER>
</PAYMENTREQUEST>

Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
  <RESULT>APPROVAL</RESULT>
  <AMOUNT>10.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
  <PAYMETH>C</PAYMETH>
  <CCTYPE>VISA</CCTYPE>
  <AHNAME>John Doe</AHNAME>
  <AHFIRSTNAME>John</AHFIRSTNAME>
  <AHLASTNAME>Doe</AHLASTNAME>
  <PWUNIQUEID>130820</PWUNIQUEID>
  <BATCHID>1</BATCHID>
  <EMAIL>jd@example.com</EMAIL>
  <AUTHCODE>074572</AUTHCODE>
  <AVSCODE>R</AVSCODE>
</PAYMENTRESPONSE>

Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
   <RESULT>DECLINED</RESULT>
   <RESTEXT>CVV2 MISMATCH</RESTEXT>
   <BATCHID>1</BATCHID>
   <PWCLIENTID>0000000001</PWCLIENTID>
   <AUTHCODE />
   <AVSCODE>0</AVSCODE>
   <PAYMETH>C</PAYMETH>
   <PWUNIQUEID>130822</PWUNIQUEID>
   <AHNAME>John Doe</AHNAME>
   <AMOUNT>10.00</AMOUNT>
   <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
   <EMAIL>jd@example.com</EMAIL>
   <CCTYPE>VISA</CCTYPE>
   <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

In order to process a Sale transaction, submit SALE in the <PWTRANSACTIONTYPE /> parameter along with the mandatory fields.

Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string SALE Fixed options.
PWSALEAMOUNT

int/decimal Amount of the transaction.
PWINVOICENUMBER string The merchants unique invoice number associated with this transaction. If not submitted, this will be generated by the gateway and returned in the XML response. 0/20, Alphanumeric
PWAPPROVALURL

string A URL on the Merchant's website that the return XML data will be posted to if transaction is approved.
PWDECLINEURL

string A URL on the Merchant's website that the return XML data will be posted to if transaction is declined or any error occurs.
PWFORWARD string Defines which payment page to forward the user to. If no value is submitted, the user is redirected to a payment selection page. Options: CC, ECHECK
CVREQ bool Defines whether to request the card CVV on the payment form. A value of FALSE will hide the CVV field.
DETAILAMOUNT int The detail amount for SAP interface associated with this line item. Required for specific Merchant IDs.
PWCID string Paywire Customer Identifier. This should be stored in the merchant database for future use. When submitted with PWCTRANSTYPE values of 4 or 5, associates the created token with this customer. When not submitted for the same PWCTRANSTYPE, a customer is created in the Paywire Vault and a PWCID is returned in the response.
PWCTRANSTYPE

string Transaction sub-type, allowing for different activities. Fixed options: OSBP PWCTRANSTYPE
COMPANYNAME string Company name of the customer.
FIRSTNAME string Account Holder's first name.
LASTNAME string Account Holder's last name.
ADDRESS1 string Account Holder's primary address.
ADDRESS2 string Account Holder's secondary address.
CITY string Account Holder's city of residence.
STATE

(✓)

string Account Holder's state of residence. Required if configured with Convenience Fees.
COUNTRY string Account Holder's country of residence.
ZIP string Account Holder's address postal/zip code.
EMAIL string Account Holder's email address.
PRIMARYPHONE string Account Holder's primary phone number.
WORKPHONE string Account Holder's work phone number.
CUSTOMERNAME string Full name of the customer, possibly different to the Account Holder.
DISABLECF bool Overrides applying a Convenience Fee or Cash Discount when set to TRUE, if configured. Note that Sales Tax will also be disabled. Default: FALSE
ADJTAXRATE decimal Overrides the configured Sales Tax rate.
PWCUSTOMID1 string Custom third-party id to be associated with this transaction.
PWRECEIPTDESC string Extra information to be displayed on the receipt. 0/200
PWCASHIERID string Paywire-assigned cashier identifier.
SECCODE string SEC Code for ECHECK payments. 3/3

OSBP Store Token Only

Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>0.00</PWSALEAMOUNT>
      <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
      <PWAPPROVALURL>https://send.paywire.com/Receive.aspx</PWAPPROVALURL>
      <PWDECLINEURL>https://send.paywire.com/Receive.aspx</PWDECLINEURL>
      <AUTHONLY>TRUE</AUTHONLY>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWCTRANSTYPE>4</PWCTRANSTYPE>
      <COMPANYNAME>The Company</COMPANYNAME>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <ADDRESS1>1 The Street</ADDRESS1>
      <ADDRESS2 />
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <ZIP>12345</ZIP>
      <COUNTRY>US</COUNTRY>
      <EMAIL>jd@example.com</EMAIL>
      <PRIMARYPHONE>410-516-8000</PRIMARYPHONE>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <PWCLIENTID>000000001</PWCLIENTID>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
    <RESULT>APPROVAL</RESULT>
    <AMOUNT>0.00</AMOUNT>
    <PWSALETAX>0.00</PWSALETAX>
    <PWADJAMOUNT>0.00</PWADJAMOUNT>
    <PWSALEAMOUNT>0.00</PWSALEAMOUNT>
    <MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT>
    <PAYMETH>C</PAYMETH>
    <CCTYPE>MC</CCTYPE>
    <AHNAME>John Doe</AHNAME>
    <AHFIRSTNAME>John</AHFIRSTNAME>
    <AHLASTNAME>Doe</AHLASTNAME>
    <PWUNIQUEID>173372</PWUNIQUEID>
    <BATCHID>1</BATCHID>
    <EMAIL>jd@example.com</EMAIL>
    <PWTOKEN>T040C8E2F56E835</PWTOKEN>
    <PWCUSTOMID2>6bb43696ab8fosq98e228284d684612</PWCUSTOMID2>
    <PWCID>P0000001234</PWCID>
</PAYMENTRESPONSE>

To create a token without processing a sale, include a value of TRUE in AUTHONLY along with PWCTRANSTYPE value of 4 and PWSALEAMOUNT of 0.00.

Parameter Required Type Description Validation
AUTHONLY

bool Processes an Authorization only when a value of TRUE is submitted.
PWSALEAMOUNT

int/decimal Amount of the transaction. A value of zero needs to be submitted when AUTHONLY is set to TRUE. 0 or 0.00
PWCTRANSTYPE

string Submit 4 to store a token. 4

OSBP Recurring Sale

Request Example:

<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      ...
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <PWCTRANSTYPE>5</PWCTRANSTYPE>
      ...
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <EMAIL>jd@example.com</EMAIL>
   </CUSTOMER>
   <RECURRING>
      <STARTON>2018-01-01</STARTON>
      <FREQUENCY>W</FREQUENCY>
      <PAYMENTS>4</PAYMENTS>
   </RECURRING>
</PAYMENTREQUEST>

For brevity, parameters identical to the One-Time-Sale XML request structure have been summarized by ...

Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
  <RESULT>APPROVAL</RESULT>
  <AMOUNT>10.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
  <PAYMETH>C</PAYMETH>
  <CCTYPE>VISA</CCTYPE>
  <AHNAME>John Doe</AHNAME>
  <AHFIRSTNAME>John</AHFIRSTNAME>
  <AHLASTNAME>Doe</AHLASTNAME>
  <PWUNIQUEID>123456</PWUNIQUEID>
  <BATCHID>1</BATCHID>
  <EMAIL>jd@example.com</EMAIL>
  <AUTHCODE>0987654</AUTHCODE>
  <PWCID>P0000000001</PWCID>
  <AVSCODE>R</AVSCODE>
  <RECURRING>VISA</RECURRING>
  <RECURRINGID>115</RECURRINGID>
</PAYMENTRESPONSE>

Declined Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <PWINVOICENUMBER>001001_20181003100218</PWINVOICENUMBER>
  <RESULT>ERROR</RESULT>
  <RESTEXT>OSBPXML: Invalid FREQUENCY Value</RESTEXT>
</PAYMENTRESPONSE>

In order to create a Recurring setup submit 5 in the <PWCTRANSTYPE> parameter and include the <RECURRING> block in addition to the One-Time-Sale parameters.

Parameter Required Type Description Validation
PWCTRANSTYPE

string 5 Fixed options: OSBP PWCTRANSTYPE.
STARTON

Date Date the first payment must be charged. Date Format: yyyy-mm-dd.
FREQUENCY

string The frequency at which recurring payments are charged. W: Weekly,
B: Bi-weekly,
M: Monthly,
H: Semi-monthly,
Q: Quarterly,
S: Semi-annual,
Y: Yearly
PAYMENTS

int Number of payments to process until the recurring setup is expired. 1/999
FIRSTNAME

string Account Holder's first name.
LASTNAME

string Account Holder's last name.
EMAIL

string Account Holder's email address.

Checkout Options

Checkout Page

The OSBP payment checkout page is displayed to customers to complete their purchase and is customizable by the Paywire team.

A checkout item would be created that consists of all of the following info:

Product Name

Product Description

Product Price

Return URL - located in merchant website/server

Once the above info is provided, Payscout can generate a test button for you to try out.

Checkout page example:

Simple Checkout

Our simple checkout option allows developers to use a single button for checkout. By contacting support@paywire.com we can generate a checkout button to your standards and specifications.

This basic example embeds the URL in an HTML button:

OCX Reference

The Paywire OCX provides a few methods which easily enables an application to communicate with the Paywire API. This can either capture the payment data from an Ingenico reader or using an in-built UI form.

Compatible readers:

OCX Installation

The latest version of the OCX can be downloaded here.

Once downloaded:

OCX Using Reader

private void button1_Click(object sender, EventArgs e)
{
  var xmlStr = $"<PWTYPE>XML</PWTYPE>
                <TRANSTYPE>SALE</TRANSTYPE>
                <CONNECTTO>COM5</CONNECTTO>
                <PWCLIENTID>{clientId}</PWCLIENTID>
                <PWKEY>{key}</PWKEY>
                <PWUSER>{username}</PWUSER>
                <PWPASS>{password}</PWPASS>
                <AMOUNT>10.00</AMOUNT>
                <URL>dbstage1</URL>";
  var result = axpwIngenicoOCX1.Ingenico_ProcessOnDemandOCX(xmlStr);

  Console.WriteLine(result);
}

OCX Reader Process Flowchart

To implement the OCX in your application:

  1. Add the pwIngenicoOCX Control to your list of UI components, available in the COM Components list once installed.
  2. Insert the pwIngenicoOCX Control in your GUI. This enables you to utilize the AxpwIngenicoOCX class containing method Ingenico_ProcessOnDemandOCX(string pARAS)
  3. Bind a button (or otherwise) from your form that calls axpwIngenicoOCX.Ingenico_ProcessOnDemandOCX(string pARAS). An XML string based on the type of payment to be processed needs to be passed to this method.
  4. The Ingenico_ProcessOnDemandOCX method will return an XML string with the results.

To process a transaction:

  1. Click the button (or otherwise) that calls axpwIngenicoOCX.Ingenico_ProcessOnDemandOCX(string pARAS).
  2. Complete the payment using a reader.
  3. The OCX will return a response based on the result of the request.

Visual Studio 2017 Example:

  1. Install the OCX as explained here.
  2. Navigate to the project you wish to add the OCX to.
  3. Open a Form in a 'Design' view.
  4. Open your Toolbox, right-click and click "Choose Items".
  5. Switch to the "COM Components" tab and locate the "pwIngenicoOCX Control" component. If not found you may need to browse for it.
  6. Tick the "pwIngenicoOCX Control" and it should now be available to use in the Toolbox.
  7. Add the "pwIngenicoOCX Control" component to your form, along with a button.
  8. Navigate to view the button code (double-click the button from the design page).
  9. Modify the button's event handler method to call axpwIngenicoOCX.Ingenico_ProcessOnDemandOCX(string pARAS), passing in the relevant XML request payload in the available parameter.

Transaction Processing

Sale Request Example:

  <PWTYPE>XML</PWTYPE>
  <TRANSTYPE>SALE</TRANSTYPE>
  <CONNECTTO>COM5</CONNECTTO>
  <PWCLIENTID>{clientId}</PWCLIENTID>
  <PWKEY>{key}</PWKEY>
  <PWUSER>{user}</PWUSER>
  <PWPASS>{pass}</PWPASS>
  <AMOUNT>1.00</AMOUNT>
  <URL>dbstage1</URL>

Void Request Example:

  <PWTYPE>XML</PWTYPE>
  <TRANSTYPE>VOID</TRANSTYPE>
  <CONNECTTO>COM5</CONNECTTO>
  <PWCLIENTID>{clientId}</PWCLIENTID>
  <PWKEY>{key}</PWKEY>
  <PWUSER>{user}</PWUSER>
  <PWPASS>{pass}</PWPASS>
  <AMOUNT>1.00</AMOUNT>
  <URL>dbstage1</URL>
  <UID>11373</UID>

Store Token Request Example:

  <PWTYPE>XML</PWTYPE>
  <TRANSTYPE>STORETOKEN</TRANSTYPE>
  <CONNECTTO>COM5</CONNECTTO>
  <PWCLIENTID>{clientId}</PWCLIENTID>
  <PWKEY>{key}</PWKEY>
  <PWUSER>{user}</PWUSER>
  <PWPASS>{pass}</PWPASS>
  <AMOUNT>0.00</AMOUNT>
  <URL>dbstage1</URL>

Token Sale Request Example:

  <PWTYPE>XML</PWTYPE>
  <TRANSTYPE>TOKENSALE</TRANSTYPE>
  <CONNECTTO>COM5</CONNECTTO>
  <PWCLIENTID>{clientId}</PWCLIENTID>
  <PWKEY>{key}</PWKEY>
  <PWUSER>{user}</PWUSER>
  <PWPASS>{pass}</PWPASS>
  <AMOUNT>1.00</AMOUNT>
  <URL>dbstage1</URL>
  <TOKEN>0A20D1AE85BC6E3F</TOKEN>

To process different transaction types submit the relevant value in parameter TRANSTYPE along with the required parameters as defined below:

Parameter Type Description Validation
PWTYPE string XML
TRANSTYPE string Defines what transaction to process. SALE,
PREAUTH,
CREDIT,
VOID,
STORETOKEN,
REMOVETOKEN,
TOKENSALE,
TOKENPREAUTH,
TOKENCREDIT,
BATCHINQUIRY,
CLOSE
CONNECTTO string The COM port or TCP port that the reader is connected to. COM, TCP
PWCLIENTID string Authentication credential provided to you by Payscout.
PWKEY string Authentication credential provided to you by Payscout.
PWUSER string Authentication credential provided to you by Payscout.
PWPASS string Authentication credential provided to you by Payscout.
AMOUNT decimal Amount of transaction being processed.
URL string Sub-domain of the Paywire environment you wish to process to. dbstage1, dbtranz
UID int Unique ID of original transaction.
POSTTIMEOUT int Time out in seconds for the API request from the OCX to the Paywire Gateway Default: 120
ISDEBIT int Defines if card is a debit card. 1 indicates that it is. 0, 1 ; Default: 0
ISEMVFALLBACK int Set this option to 1 for the reader to allow the customer to swipe the card in cases where the EMV chip is broken. 0, 1
ENTRYTIMEOUT int Time out in seconds to wait for the customer to complete input on each page displayed by the reader. Default: 60
ALLOWZIP int Submitting 1 will set the reader to display a ZIP Code input screen to the customer when they opt to key-in the card number. 0, 1
INVOICE string The merchants unique invoice number associated with this transaction.
ADDRESS1 string Account Holder's address line 1.
ADDRESS2 string Account Holder's address line 2.
CITY string Account Holder's city of residence..
COUNTRY string Account Holder's country of residence.
COUNTY string Account Holder's county of residence.
NAME string Account Holder's name.
ZIP int Account Holder's address postal/zip code.
STATE string Account Holder's state of residence.
EMAIL string Account Holder's email address.
PHONE int Account Holder's contact phone number.
TOKEN string Token returned by Paywire when performing a STORETOKEN request.
AUTHCODE string Authorization code returned by the Paywire gateway or elsewhere.

Required Parameters per Transaction Type

Parameter
SALE
PREAUTH
CREDIT
VOID
STORETOKEN
REMOVETOKEN
TOKENSALE
TOKENPREAUTH
TOKENCREDIT
BATCHINQUIRY
CLOSE
PWTYPE

TRANSTYPE

CONNECTTO

PWCLIENTID

PWKEY

PWUSER

PWPASS

AMOUNT

URL

UID

POSTTIMEOUT
ISDEBIT
ISEMVFALLBACK
ENTRYTIMEOUT
ALLOWZIP
INVOICE
ADDRESS1
ADDRESS2
CITY
COUNTRY
COUNTY
NAME
ZIP
STATE
EMAIL
PHONE
TOKEN

AUTHCODE

OCX Responses using Reader

Errors

Error Code Error Message Description String Example
701 CONNECT ERROR Returned when a reader is not connected via the method provided in the CONNECTTO parameter. <RESULT>ERROR</RESULT>
<ERRORCODE>701</ERRORCODE>
<ERRORMESSAGE>CONNECT ERROR</ERRORMESSAGE>

OCX Using Form

    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();

            axpwIngenicoOCX.Visible = false;    // Always make sure to initialize the OCX parameter before clicking the OCX control button                                                                                                   
            axpwIngenicoOCX.DialogTransEvent += new AxpwIngenicoOCXLib._DpwIngenicoOCXEvents_DialogTransEventEventHandler(AxpwIngenicoOCX_DialogTransEvent);    // This is the response event of the OCX Payment UI
        }

        private void AxpwIngenicoOCX_DialogTransEvent(object sender, AxpwIngenicoOCXLib._DpwIngenicoOCXEvents_DialogTransEventEvent e)
        {
            txtResponse.Text = e.responsMsg;    // Handle Payment Response
        }

        private void buttonInit_Click(object sender, EventArgs e)
        {
            axpwIngenicoOCX.Visible = true;
            axpwIngenicoOCX.Ocx_Init(txtRequest.Text);
        }
    }

OCX Form Process Flowchart

To implement the OCX in your application:

  1. Add the pwIngenicoOCX Control to your list of UI components, available in the COM Components list once installed.
  2. Insert the pwIngenicoOCX Control in your GUI. This enables you to utilize the AxpwIngenicoOCX class containing method Ocx_Init(string pARAS).
  3. Bind a button (or otherwise) from your form that calls axpwIngenicoOCX.Ocx_Init(string pARAS). An XML string based on the type of payment to be processed needs to be passed to this method.
  4. Add an event handler method for AxpwIngenicoOCXLib._DpwIngenicoOCXEvents_DialogTransEventEvent, which will include responsMsg as the XML payment response.

To process a transaction:

  1. Click the button (or otherwise) that calls axpwIngenicoOCX.Ocx_Init(string pARAS).
  2. Click the AxpwIngenicoOCX control on your form to pull up the OCX form.
  3. Populate the fields on the OCX form and click to process.
  4. The OCX will return a response based on the result of the request that is captured by your event handler.

Visual Studio 2017 Example:

  1. Install the OCX as explained here.
  2. Navigate to the project you wish to add the OCX to.
  3. Open a Form in a 'Design' view.
  4. Open your Toolbox, right-click and click "Choose Items".
  5. Switch to the "COM Components" tab and locate the "pwIngenicoOCX Control" component. If not found you may need to browse for it.
  6. Tick the "pwIngenicoOCX Control" and it should now be available to use in the Toolbox.
  7. Add the "pwIngenicoOCX Control" component to your form, along with a button.
  8. Navigate to view the button code (double-click the button from the design page).
  9. Modify the button's event handler method to call axpwIngenicoOCX.Ocx_Init(string pARAS), passing in the relevant XML request payload in the available parameter.
  10. If using the UI form (Ocx_Init), add an event handler for AxpwIngenicoOCXLib._DpwIngenicoOCXEvents_DialogTransEventEvent to handle the OCX response.

Transaction Types

The XML structure for the OCX is similar to that of the API, including a TRANSACTIONHEADER and a CUSTOMER block.

Only following transactions can be processed using the Paywire OCX.

Value Description
SALE Charge a card or bank account (if applicable).
STORETOKEN Validate a card and return a token.

Simply submit the relevant value in PWTRANSACTIONTYPE, along with the required XML parameters.

OCX One-Time-Sale

One-Time-Sale Request Example:

<PAYMENTREQUEST>
  <TRANSACTIONHEADER>
    <PWVERSION>3</PWVERSION>
    <PWUSER>{user}</PWUSER>
    <PWPASS>{password}</PWPASS>
    <PWCLIENTID>{client_id}</PWCLIENTID>
    <PWKEY>{key}</PWKEY>
    <URL>dbstage1</URL>
    <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
    <PWSALEAMOUNT>10</PWSALEAMOUNT>
    <PWINVOICENUMBER>0987654321234567800</PWINVOICENUMBER>
  </TRANSACTIONHEADER>
  <CUSTOMER>
    <FIRSTNAME>John</FIRSTNAME>
    <LASTNAME>Doe</LASTNAME>
    <EMAIL>jd@example.com</EMAIL>
    <STATE>CT</STATE>
    <ZIP>06105</ZIP>
    <PWMEDIA>CC</PWMEDIA>
    <REQUESTTOKEN>TRUE</REQUESTTOKEN>
  </CUSTOMER>
</PAYMENTREQUEST>
Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. SALE
PWCLIENTID

string Authentication credential provided to you by Payscout.
PWKEY

string Authentication credential provided to you by Payscout.
PWUSER

string Authentication credential provided to you by Payscout.
PWPASS

string Authentication credential provided to you by Payscout.
URL

string Sub-domain of the Paywire environment you wish to process to. local, dbstage1, dbtranz
PWTRANSACTIONTYPE

string Defines what transaction to process. SALE, STORETOKEN
PWSALEAMOUNT

int/decimal Payment amount to be processed.
PWINVOICENUMBER string The merchant's unique invoice number associated with this transaction. If not submitted, this will be generated by the gateway and returned in the XML response. 0/60
FIRSTNAME string Account Holder's first name.
LASTNAME string Account Holder's last name.
ADDRESS1 string Account Holder's primary address.
ADDRESS2 string Account Holder's secondary address.
CITY string Account Holder's city of residence.
STATE

(✓)

string Account Holder's state of residence. Required if configured with Convenience Fees.
ZIP string Account Holder's address postal/zip code.
COUNTRY string Account Holder's country of residence.
PRIMARYPHONE string Account Holder's primary phone number.
WORKPHONE string Account Holder's work phone number.
EMAIL string Account Holder's email address.
PWMEDIA

string Defines the payment method. CC, ECHECK
REQUESTTOKEN bool Returns a PWTOKEN in the response when set to TRUE.
DISABLECF bool Overrides applying a Convenience Fee or Cash Discount when set to TRUE, if configured. Note that Sales Tax will also be disabled. Default: FALSE
ADJTAXRATE decimal Overrides the configured Sales Tax rate.
PWCUSTOMID1 string Custom third-party id to be associated with this transaction.
DESCRIPTION string Transaction custom description message. 0/100
PWCID string Paywire Customer Identifier. If REQUESTTOKEN is also submitted as TRUE, the created token will be associated with this customer.

OCX Recurring Sale

Recurring Sale Request Example:

<?xml version="1.0"?>
<PAYMENTREQUEST>
  <TRANSACTIONHEADER>
    <PWVERSION>3</PWVERSION>
    <PWUSER>{user}</PWUSER>
    <PWPASS>{password}</PWPASS>
    <PWCLIENTID>{client_id}</PWCLIENTID>
    <PWKEY>{key}</PWKEY>
    <URL>dbstage1</URL>
    <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
    <PWSALEAMOUNT>10</PWSALEAMOUNT>
    <PWINVOICENUMBER>0987654321234567801</PWINVOICENUMBER>
  </TRANSACTIONHEADER>
  <CUSTOMER>
    <FIRSTNAME>John</FIRSTNAME>
    <LASTNAME>Doe</LASTNAME>
    <EMAIL>jd@example.com</EMAIL>
    <STATE>CT</STATE>
    <ZIP>06105</ZIP>
    <PWMEDIA>ECHECK</PWMEDIA>
  </CUSTOMER>
  <RECURRING>
    <STARTON>2/6/2019 12:00:00 AM</STARTON>
    <FREQUENCY>M</FREQUENCY>
    <PAYMENTS>3</PAYMENTS>
  </RECURRING>
</PAYMENTREQUEST>

In order to create a Recurring setup simply include the <RECURRING> block in addition to the One-Time-Sale parameters.

Parameter Required Type Description Validation
STARTON

Date Date the first payment must be charged. mm/dd/yyyy hh:mm:ss a.
FREQUENCY

string The frequency at which recurring payments are charged. W: Weekly,
B: Bi-weekly,
M: Monthly,
H: Semi-monthly,
Q: Quarterly,
S: Semi-annual,
Y: Yearly
PAYMENTS

int Number of payments to process until the recurring setup is expired. 1/999
EMAIL string Account Holder's email address. Required either in the XML payload to the Ocx_Init method or submitted via the form.

OCX Store Token

Store Token Request Example:

<PAYMENTREQUEST>
  <TRANSACTIONHEADER>
    <PWVERSION>3</PWVERSION>
    <PWUSER>{user}</PWUSER>
    <PWPASS>{password}</PWPASS>
    <PWCLIENTID>{client_id}</PWCLIENTID>
    <PWKEY>{key}</PWKEY>
    <URL>dbstage1</URL>
    <PWTRANSACTIONTYPE>STORETOKEN</PWTRANSACTIONTYPE>
    <PWSALEAMOUNT>0</PWSALEAMOUNT>
    <PWINVOICENUMBER>0987654321234567802</PWINVOICENUMBER>
  </TRANSACTIONHEADER>
  <CUSTOMER>
    <FIRSTNAME>John</FIRSTNAME>
    <LASTNAME>Doe</LASTNAME>
    <EMAIL>jd@example.com</EMAIL>
    <STATE>CT</STATE>
    <ZIP>06105</ZIP>
    <PWMEDIA>CC</PWMEDIA>
    <REQUESTTOKEN>TRUE</REQUESTTOKEN>
  </CUSTOMER>
</PAYMENTREQUEST>
Parameter Required Type Description Validation
PWVERSION

int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

string Defines what transaction to process. STORETOKEN
PWCLIENTID

string Authentication credential provided to you by Payscout.
PWKEY

string Authentication credential provided to you by Payscout.
PWUSER

string Authentication credential provided to you by Payscout.
PWPASS

string Authentication credential provided to you by Payscout.
URL

string URL subdomain of the Paywire environment you wish to process to. local, dbstage1, dbtranz
PWTRANSACTIONTYPE

string Defines what transaction to process. SALE, STORETOKEN
PWSALEAMOUNT int/decimal Amount of transaction being processed.
PWINVOICENUMBER string The merchants unique invoice number associated with this transaction. If not submitted, this will be generated by the gateway and returned in the XML response. 0/60
FIRSTNAME string Account Holder's first name.
LASTNAME string Account Holder's last name.
ZIP string Account Holder's address postal/zip code.
STATE string Account Holder's state of residence.
EMAIL string Account Holder's email address.
PWMEDIA

string Defines the payment method. CC, ECHECK
PWCID string Paywire Customer Identifier. If REQUESTTOKEN is also submitted as TRUE, the created token will be associated with this customer.

OCX Token Sale

Token Sale Request Example:

<PAYMENTREQUEST>
  <TRANSACTIONHEADER>
    <PWVERSION>3</PWVERSION>
    <PWUSER>{user}</PWUSER>
    <PWPASS>{password}</PWPASS>
    <PWCLIENTID>{client_id}</PWCLIENTID>
    <PWKEY>{key}</PWKEY>
    <URL>dbstage1</URL>
    <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
    <PWSALEAMOUNT>10</PWSALEAMOUNT>
    <PWINVOICENUMBER>0987654321234567803</PWINVOICENUMBER>
  </TRANSACTIONHEADER>
  <CUSTOMER>
    <PWTOKEN>A00001xa</PWTOKEN>
    <FIRSTNAME>John</FIRSTNAME>
    <LASTNAME>Doe</LASTNAME>
    <EMAIL>jd@example.com</EMAIL>
    <STATE>CT</STATE>
    <ZIP>06105</ZIP>
    <PWMEDIA>ECHECK</PWMEDIA>
  </CUSTOMER>
</PAYMENTREQUEST>

To process a Sale for a pre-existing card, account or customer, include the PWTOKEN value in parameter PWTOKEN in place of the Card or Bank Account details. For a Recurring Sale include the RECURRING block at the end as you would for a normal Recurring Sale.

Parameter Required Type Description Validation
PWTOKEN

string Can either represent a Card Token or the Paywire Customer ID
POSINDICATOR string Used in conjunction with Token Sales to apply Convenience Fees or Cash Discount for recurring payments handled outside Paywire. Submit this in the TRANSACTIONHEADER block. C: Regular Token Sale
I: First Payment of a Recurring Plan
R: Subsequent Recurring Payment
T: Last Payment of a Recurring Plan
P: Periodic Payment
PWADJAMOUNT decimal Adjustment amount. Used to set the Convenience Fee amount to be charged for this transaction. Allowed only when submitted with POSINDICATOR set to P. Submitting amounts larger than that configured for the merchant will be ignored. >0

OCX Responses using Form

One-Time-Sale Approved Response Example:

<PAYMENTRESPONSE>
  <RESULT>APPROVAL</RESULT>
  <BATCHID>1</BATCHID>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <AUTHCODE>123456</AUTHCODE>
  <AVSCODE>N</AVSCODE>
  <CVVCODE>N</CVVCODE>
  <PAYMETH>C</PAYMETH>
  <PWUNIQUEID>895362</PWUNIQUEID>
  <AHNAME>John Doe</AHNAME>
  <PWADJDESC>Convenience Fee</PWADJDESC>
  <PWSALETAX>0.00</PWSALETAX>
  <PWADJAMOUNT>10.00</PWADJAMOUNT>
  <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
  <AMOUNT>110.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT>
  <EMAIL>jd@sample.com</EMAIL>
  <CCTYPE>MC</CCTYPE>
  <PWTOKEN>841521B1BF514A4A3S34</PWTOKEN>
  <PWCUSTOMID2>24e59759870l3g9an3f4271beaas4g2a</PWCUSTOMID2>
  <PWINVOICENUMBER>0987654321234567800</PWINVOICENUMBER>
</PAYMENTRESPONSE>

Recurring Sale Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <RESULT>APPROVAL</RESULT>
  <BATCHID>1</BATCHID>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <PAYMETH>C</PAYMETH>
  <PWUNIQUEID>123456</PWUNIQUEID>
  <AHNAME>John Doe</AHNAME>
  <AMOUNT>110.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT>
  <EMAIL>jd@sample.com</EMAIL>
  <CCTYPE>MC</CCTYPE>
  <PWTOKEN>0PH5A58C17F0491BS076</PWTOKEN>
  <PWCUSTOMID2>1v1e2b1e408v4cd6b8dsnr3bfcfd2a6</PWCUSTOMID2>
  <PWINVOICENUMBER>0987654321234567801</PWINVOICENUMBER>
  <RECURRINGID>48</RECURRINGID>
</PAYMENTRESPONSE>

Token Sale Approved Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <RESULT>APPROVAL</RESULT>
  <BATCHID>182</BATCHID>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <AUTHCODE>T66984</AUTHCODE>
  <AVSCODE>N</AVSCODE>
  <PAYMETH>C</PAYMETH>
  <PWUNIQUEID>131303</PWUNIQUEID>
  <AHNAME>John Doe</AHNAME>
  <PWADJDESC>Convenience Fee</PWADJDESC>
  <PWSALETAX>0.00</PWSALETAX>
  <PWADJAMOUNT>10.00</PWADJAMOUNT>
  <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
  <AMOUNT>110.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT>
  <EMAIL>test@sample.com</EMAIL>
  <CCTYPE>MC</CCTYPE>
  <PWTOKEN>12FE3B1D364FF9B20156</PWTOKEN>
  <PWCUSTOMID2>743f4h616d4976818a6a130ef1c01a54</PWCUSTOMID2>
  <PWINVOICENUMBER>0987654321234567803</PWINVOICENUMBER>
</PAYMENTRESPONSE>

Declined Response Example:

<PAYMENTRESPONSE>
  <RESULT>DECLINED</RESULT>
  <RESTEXT>CVV2 Mismatch</RESTEXT>
  <BATCHID>1</BATCHID>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <AVSCODE>N</AVSCODE>
  <CVVCODE>N</CVVCODE>
  <PAYMETH>C</PAYMETH>
  <PWUNIQUEID>895363</PWUNIQUEID>
  <AHNAME>John Doe</AHNAME>
  <AMOUNT>110.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT>
  <EMAIL>jd@sample.com</EMAIL>
  <CCTYPE>MC</CCTYPE>
  <PWCUSTOMID2>24e59759870l3g9an3f4271beaas4g2a</PWCUSTOMID2>
  <PWINVOICENUMBER>0987654321234567800</PWINVOICENUMBER>
</PAYMENTRESPONSE>

Error Response Example:

<PAYMENTRESPONSE>
  <RESULT>ERROR</RESULT>
  <RESTEXT>CONNECTION ERROR 0</RESTEXT>
</PAYMENTRESPONSE>

Much like the API, the OCX will return with an XML response containing RESULT and RESTEXT.

Response Parameter Description Options
RESULT Describes the result of the transaction request. APPROVAL, SUCCESS, DECLINED, ERROR
RESTEXT Described why the transaction has returned an error or was declined. Not returned when RESULT is APPROVAL or SUCCESS.

Errors

Convenience Fees

Paywire also offers a Convenience Fee solution with all integration options, wherein customers are charged a fixed fee per transaction, significantly cutting down merchants' processing costs.

For enrolled merchants, this is configured on the gateway by Paywire and will require that STATE is submitted with each payment. There are a few U.S. states that do not allow convenience fees. The gateway will by default assess a Convenience Fee if the STATE submitted is not one these.

The Paywire OSBP will display the below box throughout if the STATE submitted in the request is found to be a "Fee-State".

OSBP CF Box

The message at the bottom is configurable in the VPOS merchant admin page.

A Convenience Fee breakdown is displayed on the Payment Form:

OSBP CF Breakdown

Approved Response Example:


<PAYMENTRESPONSE>
...
    <AMOUNT>110.00</AMOUNT>
    <PWSALETAX>0.00</PWSALETAX>
    <PWADJAMOUNT>10.00</PWADJAMOUNT>
    <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
...
</PAYMENTRESPONSE>

The OSBP and API responses will also include the Convenience Fee breakdown where relevant.

Two parameters are provided to override the setup via OSBP, API and OCX:

  1. DISABLECF - disables applying a 'Convenience Fee' for a given transaction.
  2. ADJTAXRATE - overrides the configured Tax Rate to the submitted value.

Merchant-Managed Periodic Billing

First Sale Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
  </TRANSACTIONHEADER>
  <DETAILRECORDS />
  <CUSTOMER>
      <STATE>CT</STATE>
      <PWMEDIA>CC</PWMEDIA>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>02</EXP_MM>
      <EXP_YY>22</EXP_YY>
  </CUSTOMER>
</PAYMENTREQUEST>

First Sale Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
  <RESULT>APPROVAL</RESULT>
  <BATCHID>1</BATCHID>
  <PWCLIENTID>0000000001</PWCLIENTID>
  <AUTHCODE>B1246A</AUTHCODE>
  <AVSCODE>N</AVSCODE>
  <PAYMETH>C</PAYMETH>
  <PWUNIQUEID>446331</PWUNIQUEID>
  <PWSALETAX>0.00</PWSALETAX>
  <PWADJAMOUNT>0.00</PWADJAMOUNT>
  <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
  <AMOUNT>100.00</AMOUNT>
  <MACCOUNT>XXXXXXXXXXXX1111</MACCOUNT>
  <CCTYPE>VISA</CCTYPE>
  <PWTOKEN>EEF46WF47AC34341209</PWTOKEN>
  <PWCUSTOMID2>cd3d19cf2123dfe469df07a2c75c8245b</PWCUSTOMID2>
  <PWINVOICENUMBER>19181234094754503</PWINVOICENUMBER>
</PAYMENTRESPONSE>

When processing transactions with merchant-managed Periodic Billing Plans that utilize the Paywire Token feature, the merchant is responsible for storing the Convenience Fee amount charged on the first sale.

This same amount must be submitted in PWADJAMOUNT along with a POSINDICATOR value of P.

This ensures that, in case the Convenience Fee configured for a given merchant changes during the course of the customer's Periodic Billing Plan, the Convenience Fee charged is not altered.

The following outlines the steps that can be taken for each Periodic Billing Plan:

  1. The merchant submits a One-Time-Sale request (that includes REQUESTTOKEN set to TRUE if not using a card).
  2. The merchant stores the PWADJAMOUNT and PWTOKEN from the response to be used later.
  3. In the subsequent sales, the merchant submits a Token Sale including the PWADJAMOUNT and PWTOKEN tags with the respective values stored in (2), along with a POSINDICATOR of P.

Subsequent Sale Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTREQUEST>
  <TRANSACTIONHEADER>
      <PWVERSION>3</PWVERSION>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <PWUSER>{username}</PWUSER>
      <PWPASS>{password}</PWPASS>
      <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>100.00</PWSALEAMOUNT>
      <POSINDICATOR>P</POSINDICATOR>
      <DISABLECF>TRUE</DISABLECF>
  </TRANSACTIONHEADER>
  <CUSTOMER>
      <PWTOKEN>EEF2547BDAC34E642009</PWTOKEN>
      <PWMEDIA>CC</PWMEDIA>
      <STATE>AZ</STATE>
  </CUSTOMER>
</PAYMENTREQUEST>