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, favored 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

API/OCX 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 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.

OSBP Example:

<PAYMENTREQUEST>
   <TRANSACTIONHEADER>
      <PWCLIENTID>{clientId}</PWCLIENTID>
      <PWKEY>{key}</PWKEY>
      <AUTHTOKEN>4C2F8EE94CA2491AAB67EA6541CB17BA</AUTHTOKEN>
      ...
   </TRANSACTIONHEADER>
  ...
</PAYMENTREQUEST>

To authenticate with the OSBP first call Get Auth Token to retrieve an AUTHTOKEN, then submit it as a request parameter instead of PWUSER and PWPASS.

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 periodic amount if the value under PWCTRANSTYPE is selected.

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
TSYS 4012000098765439 123
FirstData 5413330089010608 123
MES 5413330089010608 123

Account Type Routing Number Account Number
Current/Savings 222224444 222224444 or any same digit number

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.

Currently, 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-authorize a card.
GETAUTHTOKEN Exchange your credentials for an AUTHTOKEN to use when calling the OSBP.
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 periodic 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>

RCC - Remotely Created Checks 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>
      <CARDPRESENT>FALSE</CARDPRESENT>
   </TRANSACTIONHEADER>
   <CUSTOMER>
      <REQUESTTOKEN>FALSE</REQUESTTOKEN>
      <PWMEDIA>ECHECK</PWMEDIA>
      <BANKACCTTYPE>CHECKING</BANKACCTTYPE>
      <SECCODE>ICL</SECCODE>
      <ROUTINGNUMBER>222224444</ROUTINGNUMBER>
      <ACCOUNTNUMBER>4242204082</ACCOUNTNUMBER>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <ADDRESS1>1 The Street</ADDRESS1>
      <ADDRESS2></ADDRESS2>
      <CITY>New York</CITY>
      <STATE>NY</STATE>
      <COUNTRY>US</COUNTRY>
      <ZIP>12345</ZIP>
   </CUSTOMER>
</PAYMENTREQUEST>

RCC - Remotely Created Checks 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>
    <PWSALETAX>0.00</PWSALETAX>
    <PWADJAMOUNT>0.00</PWADJAMOUNT>
    <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
    <AMOUNT>10.00</AMOUNT>
    <MACCOUNT>XXXXX6789</MACCOUNT>
    <CCTYPE>ACH</CCTYPE>
    <PWINVOICENUMBER>0987654321234567890</PWINVOICENUMBER>
</PAYMENTRESPONSE>

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

SALE transaction now supports RCC - Remotely Created Checks,
Remotely Created Checks, or RCC, is a broad term used to describe processing which clears transactions through bank-to-bank file transfer rather than through the ACH network.
Both RCC and ACH are used for web and phone transactions as well as one-time and recurring debits from bank accounts.
The customer experience for RCC and ACH is the same for the most part.
From the merchant's perspective, the process is almost identical.

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. (required for RCC)
LASTNAME string Account Holder's last name. (required for RCC)
COMPANYNAME string Customer's company name.
ADDRESS1 string Account Holder's primary address. (required for RCC)
ADDRESS2 string Account Holder's secondary address. (required for RCC)
CITY string Account Holder's city of residence. (required for RCC)
STATE

(✓)

 string Account Holder's state of residence. Required if configured with Convenience Fees. (required for RCC)
COUNTRY string Account Holder's country of residence. (required for RCC)
ZIP string Account Holder's address postal/zip code. (required for RCC)
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 ICL (for RCC)
DESCRIPTION string Transaction custom description message. 0/100

API Periodic 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 Periodic 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 Periodic 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 Periodic 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>

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>

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>

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 Auth Token

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>GETAUTHTOKEN</PWTRANSACTIONTYPE>
    </TRANSACTIONHEADER>
</PAYMENTREQUEST>
Parameter Required Type Description Validation
PWVERSION

✓

 int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

✓

 string Defines what transaction to process. GETAUTHTOKEN

Response Parameters

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>{clientId}</PWCLIENTID>
    <PWINVOICENUMBER>10070170834652361</PWINVOICENUMBER>
    <AUTHTOKEN>4C2F8EE94CA2491AAB67EA6541CB17BA</AUTHTOKEN>
</PAYMENTRESPONSE>
Parameter Type Description Options
RESULT string Status for the request. SUCCESS, ERROR
PWCLIENTID string Paywire-generated unique merchant identifier.
PWINVOICENUMBER string Identifier for this request.
AUTHTOKEN string The Authentication Token to be used when calling the OSBP.

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>
      <STATE>NY</STATE>
   </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 periodic payments handled outside Paywire. Submit this in the TRANSACTIONHEADER block. C: Regular Token Sale
I: First Payment of a Periodic Plan
R: Subsequent Periodic Payment
T: Last Payment of a Periodic 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
STATE

(✓)

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

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 Verification

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>VERIFICATION</PWTRANSACTIONTYPE>
      <PWSALEAMOUNT>0.00</PWSALEAMOUNT>
    </TRANSACTIONHEADER>
    <DETAILRECORDS />
   <CUSTOMER>
      <REQUESTTOKEN>FALSE</REQUESTTOKEN>
      <PWMEDIA>CC</PWMEDIA>
      <FIRSTNAME>John</FIRSTNAME>
      <LASTNAME>Doe</LASTNAME>
      <EMAIL>johndoe@email.com</EMAIL>
      <PRIMARYPHONE>7035551212</PRIMARYPHONE>
      <CARDNUMBER>4111111111111111</CARDNUMBER>
      <EXP_MM>12</EXP_MM>
      <EXP_YY>33</EXP_YY>
      <CVV2>123</CVV2>
      <ADDRESS1>1 The Street</ADDRESS1>
      <ZIP>12345</ZIP>
   </CUSTOMER>
</PAYMENTREQUEST>

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>APPROVAL</RESULT>
    <BATCHID>167792</BATCHID>
    <PWCLIENTID>0000000519</PWCLIENTID>
    <AUTHCODE>09636C</AUTHCODE>
    <AVSCODE>Z</AVSCODE>
    <CVVCODE>M</CVVCODE>
    <PAYMETH>C</PAYMETH>
    <PWUNIQUEID>4771740</PWUNIQUEID>
    <AMOUNT>0.00</AMOUNT>
    <MACCOUNT>XXXXXXXXXXXX8628</MACCOUNT>
    <CCTYPE>VISA</CCTYPE>
    <PWCUSTOMID2>b6d469d28fd33cf5acb627bcf6ca0496</PWCUSTOMID2>
</PAYMENTRESPONSE>

Verification transaction will confirm the billing address and ZIP code of a customer before submitting a sale.

Request Parameters

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.
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
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.
ADDRESS1 string Account Holder's primary address.
ZIP string Account Holder's address postal/zip code.
EMAIL string Account Holder's email address.
PRIMARYPHONE string Account Holder's primary phone number.

Response Parameters

Parameter Type Description Options
RESULT string China UnionPay transaction result.
BATCHID int Batch number.
PWCLIENTID string Paywire client ID.
AUTHCODE string Authorization code associated with the transaction.
AVSCODE string Transaction AVS code result. Refer to AVS Codes table
CVVCODE string CVV response code.
PAYMETH string Payment method.
PWUNIQUEID int The Paywire Unique ID returned in the Initialize response. 3
AMOUNT decimal Payment amount.
MACCOUNT string Masked credit card number.
CCTYPE string Credit card type.
PWCUSTOMID2 string Client custom ID.

API China UnionPay

Initialize Credit Card Transaction 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>INITIALIZE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>USD</CURRENCY>
        <PWINVOICENUMBER>testcup200504001</PWINVOICENUMBER>
        <REQUESTTOKEN>FALSE</REQUESTTOKEN>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <PWMEDIA>CC</PWMEDIA>
     <CARDNUMBER>6222821234560017</CARDNUMBER>
     <EXP_MM>12</EXP_MM>
     <EXP_YY>33</EXP_YY>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <FIRSTNAME>Sample</FIRSTNAME>
     <LASTNAME>Name</LASTNAME>
     </CUSTOMER>
  </PAYMENTREQUEST>

Initialize Credit Card Transaction Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>641</BATCHID>
      <PWCLIENTID>{clientId}</PWCLIENTID>     
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>2314876</PWUNIQUEID>
      <AHNAME>Sample Name</AHNAME>
      <AMOUNT>10.00</AMOUNT>
      <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
      <CCTYPE>CUP</CCTYPE>
      <PWCUSTOMID2>000000189897</PWCUSTOMID2>
      <PWINVOICENUMBER>testcup200504001</PWINVOICENUMBER>
      <ISDEBIT>FALSE</ISDEBIT>
      <CURRENCY>USD</CURRENCY>
  </PAYMENTRESPONSE>

Finalize Credit Card Transaction 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>FINALIZE</PWTRANSACTIONTYPE>
        <PWINVOICENUMBER>test_002</PWINVOICENUMBER>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <PWUNIQUEID>189897</PWUNIQUEID>
     <SECURECODE>111111</SECURECODE>
     <CVV2>123</CVV2>
     </CUSTOMER>
  </PAYMENTREQUEST>

Finalize Credit Card Transaction Response Example:

<?xml version="1.0" encoding="UTF-8"?>
    <PAYMENTRESPONSE>
        <RESULT>APPROVAL</RESULT>
        <BATCHID>641</BATCHID>
        <PWCLIENTID>{clientId}</PWCLIENTID>     
        <AUTHCODE>123456</AUTHCODE>
        <CVVCODE> </CVVCODE>
        <PAYMETH>C</PAYMETH>
        <PWUNIQUEID>189897</PWUNIQUEID>
        <AMOUNT>10.00</AMOUNT>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <CCTYPE>CUP</CCTYPE>
        <PWTOKEN>XXXXXXXXXXXXXXXXXXXX</PWTOKEN>
        <PWCUSTOMID2>00000023123456</PWCUSTOMID2>
        <PWINVOICENUMBER>test_002</PWINVOICENUMBER>
        <CURRENCY>USD</CURRENCY>
    </PAYMENTRESPONSE>

Initialize Debit Card Transaction 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>INITIALIZE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>USD</CURRENCY>
        <PWINVOICENUMBER>testcup200504005</PWINVOICENUMBER>
        <REQUESTTOKEN>FALSE</REQUESTTOKEN>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <PWMEDIA>CC</PWMEDIA>
     <CARDNUMBER>6250946000000016</CARDNUMBER>
     <EXP_MM>12</EXP_MM>
     <EXP_YY>33</EXP_YY>
     <PRIMARYPHONE>852-11112222</PRIMARYPHONE>
     <FIRSTNAME>Sample</FIRSTNAME>
     <LASTNAME>Name</LASTNAME>
     </CUSTOMER>
  </PAYMENTREQUEST>

Initialize Debit Card Transaction Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>641</BATCHID>
      <PWCLIENTID>{clientId}</PWCLIENTID>     
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>189899</PWUNIQUEID>
      <AHNAME>Sample Name</AHNAME>
      <AMOUNT>10.00</AMOUNT>
      <MACCOUNT>XXXXXXXXXXXX0016</MACCOUNT>
      <CCTYPE>CUP</CCTYPE>
      <PWCUSTOMID2>000000223154</PWCUSTOMID2>
      <PWINVOICENUMBER>testcup200504005</PWINVOICENUMBER>
      <ISDEBIT>TRUE</ISDEBIT>
      <CURRENCY>USD</CURRENCY>
  </PAYMENTRESPONSE>

Finalize Debit Card Request Transaction 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>FINALIZE</PWTRANSACTIONTYPE>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <PWUNIQUEID>189899</PWUNIQUEID>
     <SECURECODE>111111</SECURECODE>
     </CUSTOMER>
  </PAYMENTREQUEST>

Finalize Debit Card Transaction Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>641</BATCHID>
      <PWCLIENTID>{clientId}</PWCLIENTID>     
      <AUTHCODE>123456</AUTHCODE>
      <CVVCODE> </CVVCODE>
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>189899</PWUNIQUEID>
      <AHNAME>Sample Name</AHNAME>
      <AMOUNT>10.00</AMOUNT>
      <MACCOUNT>XXXXXXXXXXXX0016</MACCOUNT>
      <CCTYPE>CUP</CCTYPE>
      <PWTOKEN>XXXXXXXXXXXXXXXXXXXX</PWTOKEN>
      <PWCUSTOMID2>000000223154</PWCUSTOMID2>
      <PWINVOICENUMBER>20210170128760201</PWINVOICENUMBER>
      <CURRENCY>USD</CURRENCY>
  </PAYMENTRESPONSE>

Non-Secure Plus Token Sale Request Example:
Use the Token and PWUNIQUEID from the above finalize transaction response
Debit card is not allowed to process Non-SecurePlus payments. Union Pay will return decline in prod for debit cards.

<?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>testcup200504002</PWINVOICENUMBER>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <POSINDICATOR>R</POSINDICATOR>
     <PWUNIQUEID>192824</PWUNIQUEID>
     <PWMEDIA>CC</PWMEDIA>
     <PWTOKEN>3DD22D8DF80A4FB57360</PWTOKEN>
     </CUSTOMER>
  </PAYMENTREQUEST>

Non-Secure Plus Token Sale Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>691</BATCHID>
      <PWCLIENTID>{clientId}</PWCLIENTID>     
      <AUTHCODE></AUTHCODE>
      <CVVCODE> </CVVCODE>
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>192824</PWUNIQUEID>
      <AMOUNT>10.00</AMOUNT>
      <MACCOUNT>XXXXXXXXXXXX0016</MACCOUNT>
      <CCTYPE>CUP</CCTYPE>
      <PWTOKEN>3DD22D8DF80A4FB57360</PWTOKEN>
      <PWCUSTOMID2>000000223154</PWCUSTOMID2>
      <PWINVOICENUMBER>testcup200504002</PWINVOICENUMBER>
      <CURRENCY>USD</CURRENCY>
  </PAYMENTRESPONSE>

Sending a China UnionPay payment transaction to the gateway is a two-step process using two distinct transaction types consecutively: INITIALIZE and FINALIZE.

INITIALIZE - Initiate the SMS authentication request. The developer needs to pass the card number, exp date and the phone number via the tags below. In the INITIALIZE response, there will be an additional field: ISDEBIT=TRUE/FALSE that indicates if the card is a credit or debit card.

FINALIZE - Complete the CUP transaction with the unique id from the INITIALIZE response. The SMS Code sent to the customers mobile phone needs to be passed via the SECURECODE tag. If the card is a credit card (read from the INITIALIZE response), then the CVV2 is mandatory.

China UnionPay also supports two other transaction types: VOID and CREDIT for voiding transactions prior to settlement or refunding transactions after settlement. The syntax for these transaction types is the same as specified elsewhere in this document.

Initialize Request Parameters

Parameter Required Type Description Validation
PWVERSION

✓

 int The Paywire Gateway version number. 3
PWTRANSACTIONTYPE

✓

 string Defines what transaction to process. INITIALIZE
PWSALEAMOUNT

✓

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

✓

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

✓

 int Credit card number.
EXP_MM

✓

 string Card expiry month. 2/2, >0, <=12
EXP_YY

✓

 string Card expiry year. 2/2
PRIMARYPHONE

✓

 string Cell phone number to send SMS code.

Initialize Response Parameters

Parameter Type Description Options
RESULT string China UnionPay transaction result.
BATCHID int Batch number.
PWCLIENTID string Paywire client ID.
PAYMETH string Payment method.
PWUNIQUEID int The Paywire Unique ID returned in the Initialize response. 3
AHNAME string The account holder's name that was supplied.
AMOUNT decimal Payment amount.
MACCOUNT string Masked credit card number.
CCTYPE string Credit card type.
PWCUSTOMID2 string Client custom ID.
PWINVOICENUMBER string Client custom invoice number.
PWINVOICENUMBER string Client custom invoice number.
ISDEBIT Bool Indicate if the card is a debit or credit card. TRUE/FALSE
CURRENCY string Set the transaction currency. USD/CNY/EUR

Finalize Request Parameters

Parameter Required Type Description Validation
PWVERSION

✓

 int The Paywire Gateway version number. 3
PWINVOICENUMBER

✓

 string Client custom invoice number.
PWTRANSACTIONTYPE

✓

 string Defines what transaction to process. FINALIZE
PWUNIQUEID

✓

 int The Paywire Unique ID returned in the Initialize response. 3
SECURECODE

✓

 int The SMS code returned in the Initialize response. 3
CVV2

✓

 int Only required for credit cards, i.e. not debit cards. 3

Finalize Response Parameters

Parameter Type Description Options
RESULT string China UnionPay transaction result.
BATCHID int Batch number.
PWCLIENTID string Paywire client ID.
AUTHCODE string Authorization code associated with the transaction.
CVVCODE string CVV response code.
PAYMETH string Payment method.
PWUNIQUEID int The Paywire Unique ID returned in the Initialize response. 3
AHNAME string The account holder's name that was supplied.
AMOUNT decimal Payment amount.
MACCOUNT string Masked credit card number.
CCTYPE string Credit card type.
PWTOKEN string Token returned by the Paywire Gateway.
PWCUSTOMID2 string Client custom ID.
PWINVOICENUMBER string Client custom invoice number.
CURRENCY string Set the transaction currency. USD/CNY/EUR

China UnionPay Test Cards:

Credit:
6222821234560017 , Phone Number: 86-13012345678
Debit:
6250946000000016 , Phone Number: 852-11112222
Exp: 12/33
CVV: 123
SMS Code: 111111

API Brazil

Brazil Credit Card Sale Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWUSER>{username}</PWUSER>
        <PWPASS>{password}</PWPASS>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10</PWSALEAMOUNT>
        <PWINVOICENUMBER>test12345</PWINVOICENUMBER>
     </TRANSACTIONHEADER>	 
     <CUSTOMER>
        <REQUESTTOKEN>FALSE</REQUESTTOKEN>
        <PWMEDIA>CC</PWMEDIA>
        <FIRSTNAME>Silva</FIRSTNAME>
        <LASTNAME>Gonsalves</LASTNAME>
        <CARDNUMBER>4111111111111111</CARDNUMBER>
        <EXP_MM>12</EXP_MM>
        <EXP_YY>30</EXP_YY>
        <CVV2>699</CVV2>
        <TOTALINSTALLMENTS>1</TOTALINSTALLMENTS>
        <EMAIL>c41077766698466611827@sandbox.pagseguro.com.br</EMAIL>
     </CUSTOMER>	 
     <SECUREDATA>
        <CUSTOMERIP>177.69.0.82</CUSTOMERIP>
        <SELLERCHANNEL>web</SELLERCHANNEL>
        <PRODUCTSCATEGORY>Equipamentos de Esporte</PRODUCTSCATEGORY>
        <GENDER>F</GENDER>
        <CUSTOMERLOGIN>F</CUSTOMERLOGIN>
        <CUSTOMERNAME>Pedro</CUSTOMERNAME>
        <DOCUMENTTYPE>CPF</DOCUMENTTYPE>
        <DOCUMENT>09060697006</DOCUMENT>
        <BIRTHDATE>1986-04-05</BIRTHDATE>
        <FINGERPRINT>1573661233</FINGERPRINT>
     </SECUREDATA>	 
     <BILLINGINFO>
        <BILLINGDDD>32</BILLINGDDD>
        <BILLINGPHONE>962633862</BILLINGPHONE>
        <BILLINGSTREET>Rua Santa Mônica</BILLINGSTREET>
        <BILLINGNUMBER>281</BILLINGNUMBER>
        <BILLINGNEIGHBORHOOD>Parque Industrial San José</BILLINGNEIGHBORHOOD>
        <BILLINGCITY>Cotia</BILLINGCITY>
        <BILLINGSTATE>SP</BILLINGSTATE>
        <BILLINGZIPCODE>06715825</BILLINGZIPCODE>
        <BILLINGCOUNTRY>Brasil</BILLINGCOUNTRY>
     </BILLINGINFO>
     <PRODUCTLIST>
      <PRODUCT>
        <PRODUCTNAME>Produtox</PRODUCTNAME>
        <PRODUCTPRICE>10.00</PRODUCTPRICE>
        <PRODUCTQTY>1</PRODUCTQTY>
        <PRODUCTCODE>1234a56</PRODUCTCODE>
      </PRODUCT>
     </PRODUCTLIST>
  </PAYMENTREQUEST>

Brazil Credit Card Sale Response Example:

<?xml version="1.0" encoding="UTF-8"?>
      <PAYMENTRESPONSE>
          <RESULT>APPROVAL</RESULT>
          <BATCHID>73589</BATCHID>
          <PWCLIENTID>0000000540</PWCLIENTID>     
          <AUTHCODE>770323</AUTHCODE>
          <PAYMETH>C</PAYMETH>
          <PWUNIQUEID>4770323</PWUNIQUEID>
          <AMOUNT>10.00</AMOUNT>
          <MACCOUNT>XXXXXXXXXXXX8390</MACCOUNT>
          <CCTYPE>MC</CCTYPE>
          <PWTOKEN>DFED3F81124941526978</PWTOKEN>
          <PWCUSTOMID2>15919932357584290</PWCUSTOMID2>
          <PWINVOICENUMBER>test12131</PWINVOICENUMBER>
      </PAYMENTRESPONSE>

Brazil Boleto Sale Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWUSER>{username}</PWUSER>
        <PWPASS>{password}</PWPASS>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <PWTRANSACTIONTYPE>BOLETO</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10</PWSALEAMOUNT>
     </TRANSACTIONHEADER>
     <BOLETOREQUEST>
     <BR_EXPDATE>2020-12-06</BR_EXPDATE>
     <BR_CALLBACKURL>www.sample.com</BR_CALLBACKURL>
     <BR_INSTRUCTIONS>Sample Boleto Instruction</BR_INSTRUCTIONS>
     <BR_EMAIL>Sample.customer@test.com</BR_EMAIL>
     <BR_CUSTOMERNAME>Sample Customer</BR_CUSTOMERNAME>
     <BR_DOCUMENT>023.472.201-01</BR_DOCUMENT>
     <BR_ADDRESS_NUMBER>123</BR_ADDRESS_NUMBER>
     <BR_ADDRESS_STREET>Test Street</BR_ADDRESS_STREET>
     <BR_ADDRESS_COMPLEMENT>Apt 456</BR_ADDRESS_COMPLEMENT>
     <BR_ADDRESS_NEIGHBORHOOD>Jardins</BR_ADDRESS_NEIGHBORHOOD>
     <BR_ADDRESS_CITY>Sao Paulo</BR_ADDRESS_CITY>
     <BR_ADDRESS_STATE>SP</BR_ADDRESS_STATE>
     <BR_ADDRESS_ZIPCODE>06743725</BR_ADDRESS_ZIPCODE>
     <BR_ADDRESS_COUNTRY>Brazil</BR_ADDRESS_COUNTRY>
     <BR_SPLITMODE>FALSE</BR_SPLITMODE>
     </BOLETOREQUEST>
  </PAYMENTREQUEST>

Brazil Boleto Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>73589</BATCHID>
      <PWCLIENTID>0000000540</PWCLIENTID>     
      <AUTHCODE>770323</AUTHCODE>
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>4770323</PWUNIQUEID>
      <AMOUNT>10.00</AMOUNT>
      <CCTYPE>BOLETO</CCTYPE>
      <PWCUSTOMID2>15919933554093388</PWCUSTOMID2>
      <PWINVOICENUMBER>20164162228202123</PWINVOICENUMBER>
      <BR_BARCODE>00099828700000010009999250040933880799999990</BR_BARCODE>
      <BR_DIGITABLELINE>00099.99921 50040.933884 07999.999902 9 82870000001000</BR_DIGITABLELINE>
      <BR_URL>https://transactionsandbox.pagador.com.br/post/pagador/reenvia.asp/93fa2074-3cfc-4d17-b490-2daf19a65367</BR_URL>
  </PAYMENTRESPONSE>

Brazil Boleto Split Mode - Step 1 - Get Boleto Cost Example:

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

Brazil Boleto Split Mode - Step 1 - Boleto Cost Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <PWCLIENTID>0000000540</PWCLIENTID>     
      <PAYMETH>C</PAYMETH>
      <AMOUNT>1.80</AMOUNT>
      <PWINVOICENUMBER>20164162228202123</PWINVOICENUMBER>
  </PAYMENTRESPONSE>

Brazil Boleto Split Mode - Step 2 - Send Boleto Split Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWUSER>{username}</PWUSER>
        <PWPASS>{password}</PWPASS>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <PWTRANSACTIONTYPE>BOLETO</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10</PWSALEAMOUNT>
     </TRANSACTIONHEADER>
     <BOLETOREQUEST>
     <BR_EXPDATE>2020-12-06</BR_EXPDATE>
     <BR_CALLBACKURL>www.sample.com</BR_CALLBACKURL>
     <BR_INSTRUCTIONS>Sample Boleto Instruction</BR_INSTRUCTIONS>
     <BR_EMAIL>Sample.customer@test.com</BR_EMAIL>
     <BR_CUSTOMERNAME>Sample Customer</BR_CUSTOMERNAME>
     <BR_DOCUMENT>023.472.201-01</BR_DOCUMENT>
     <BR_ADDRESS_NUMBER>123</BR_ADDRESS_NUMBER>
     <BR_ADDRESS_STREET>Test Street</BR_ADDRESS_STREET>
     <BR_ADDRESS_COMPLEMENT>Apt 456</BR_ADDRESS_COMPLEMENT>
     <BR_ADDRESS_NEIGHBORHOOD>Jardins</BR_ADDRESS_NEIGHBORHOOD>
     <BR_ADDRESS_CITY>Sao Paulo</BR_ADDRESS_CITY>
     <BR_ADDRESS_STATE>SP</BR_ADDRESS_STATE>
     <BR_ADDRESS_ZIPCODE>06743725</BR_ADDRESS_ZIPCODE>
     <BR_ADDRESS_COUNTRY>Brazil</BR_ADDRESS_COUNTRY>
     <BR_SPLITMODE>TRUE</BR_SPLITMODE>
     <BR_SPLITS>
     <BR_SPLIT_ITEM>
     <BR_SPLITS_DOCUMENT>843.345.449-83</BR_SPLITS_DOCUMENT>
     <BR_SPLITS_VALUE>5</BR_SPLITS_VALUE>
     </BR_SPLIT_ITEM>
     <BR_SPLIT_ITEM>
     <BR_SPLITS_DOCUMENT>885.870.260-38</BR_SPLITS_DOCUMENT>
     <BR_SPLITS_VALUE>3.20</BR_SPLITS_VALUE>
     </BR_SPLIT_ITEM>
     </BR_SPLITS>
     </BOLETOREQUEST>
  </PAYMENTREQUEST>

Brazil Boleto Split Mode - Step 2 - Get Boleto Split Response Example:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
      <RESULT>APPROVAL</RESULT>
      <BATCHID>73589</BATCHID>
      <PWCLIENTID>0000000540</PWCLIENTID>     
      <AUTHCODE>770324</AUTHCODE>
      <PAYMETH>C</PAYMETH>
      <PWUNIQUEID>4770323</PWUNIQUEID>
      <AMOUNT>10.00</AMOUNT>
      <CCTYPE>BOLETO</CCTYPE>
      <PWCUSTOMID2>15919933554093388</PWCUSTOMID2>
      <PWINVOICENUMBER>20164162228202123</PWINVOICENUMBER>
      <BR_BARCODE>00099828700000010009999250040933880799999990</BR_BARCODE>
      <BR_DIGITABLELINE>00099.99921 50040.933884 07999.999902 9 82870000001000</BR_DIGITABLELINE>
      <BR_URL>https://transactionsandbox.pagador.com.br/post/pagador/reenvia.asp/93fa2074-3cfc-4d17-b490-2daf19a65367</BR_URL>
  </PAYMENTRESPONSE>

API Brazil has 3 transactions, Credit Card Sale, Brazil Boleto Sale and Brazil Boleto Split Mode, The Brazil Boleto Sale and Brazil Boleto Split Mode transactions are associated with Boleto. Boleto is basically a paper payment invoice that a customer carries into a bank and pays. The bank routes the customer's payment back to the merchant.

BOLETO issues a Boleto to a customer which basically redirects the customer to a link that displays the Boleto for printing. GETBOLETOFEE gets the fee associated with a Boleto that the customer pays.

The Paywire gateway can also process regular credit card transactions as per the examples provided.

Probably the most important field associated with Brazil processing for all payment types is BR_DOCUMENT which is the Brazilian equivalent of the US Social Security number - the CPF. This field is required for any transactions associted with settled funds which are to be transferred out of Brazil.

Below are some test CPF account numbers:

Brazil Credit Sale Parameters

Parameter Required Type Description Validation
CUSTOMER

✓

 Object This is the existing customer data group same with all other payment types
TOTALINSTALLMENTS Int The number of installments when the payment is initiated by the merchant Must greater than 0 if this tag exists
SECUREDATA

✓

 object This group is used to verify customer identity for fraud prevention
CUSTOMERIP

✓

 string The IP address of the customer Must be a valid IPv4 address in the current version.
SELLERCHANNEL

✓

 enum The sale channel of the transaction. Call Center: purchases made over the phone
Web: purchases made by web
Portal: purchases from web portals
Quiosque: purchases from retail stores
Movel: purchases made by mobile devices
PRODUCTSCATEGORY

✓

 enum The product category Animais e Bichos de Estimação: Pets
Roupas e Acessórios: Clothing and Accessories
Negócios e Indústria: Business and Industry
Câmeras e Óticas: Cameras and Optics
Eletrônicos: Eletronics
Comidas, Bebidas e Cigarro: Food, Drinks and Cigars
Móveis: Furniture
Ferramentas: Tools
Saúde e Beleza: Health and Beauty
Casa e Jardim: House and Garden
Malas e Bagagens: Bags and Luggage’s
Adulto: Adult
Armas e Munição: Weapons and Ammunition
Materiais de Escritório: Office Supplies
Religião e Cerimoniais: Religion and Ceremonial
Software: Software
Equipamentos de Esporte: Sports Equipment
Brinquedos e Jogos: Toys and Games
Veículos e Peças: and Parts
Livros: Books
DVDs e Vídeos: DVDs and Videos
Revistas e Jornais: Magazines and Newspapers
Música: Music
Outras Categorias Não Especificada: Others Categories Not specified
GENDER

✓

 enum Customer gender M: Male
F: Female
CUSTOMERLOGIN

✓

 string The customer's login username from the merchant's payment system Length 1 ~ 100
CUSTOMERNAME

✓

 string The customer's full name Length 1 ~ 34
DOCUMENTTYPE

✓

 enum The document type CPF or CNPJ
DOCUMENT

✓

 string The document number Length 11~14
BIRTHDATE

✓

 string The customer's birth date Date format: YYYY-MM-DD
FINGERPRINT

✓

 string The information to identify the customer device, generated by integrating with the 3rd party fraud prevention systems Length 1 ~ 100
BILLINGINFO

✓

 object The billing info of the customer
BILLINGDDD

✓

 string The 2-digit Brazil area code for the phone number Always 2 digits, 00 is not accepted
BILLINGPHONE

✓

 string The billing phone number Length 8 ~ 11
BILLINGSTREET

✓

 string The billing address street Length 1 ~ 70
BILLINGNUMBER

✓

 string The billing address number Length 1 ~ 10
BILLINGNEIGHBORHOOD

✓

 string The billing address neighborhood Length 1 ~ 50
BILLINGCITY

✓

 string The billing address city Length 1 ~ 50
BILLINGSTATE

✓

 string The billing address state/district 2 digit state code, for example, SP (São Paulo)
BILLINGZIPCODE

✓

 string The billing address zip code 8 digit zip code, only numbers accepted
BILLINGCOUNTRY

✓

 string The billing address country Length 1 ~ 35
SHIPPINGINFO object The shipping info of the customer, if not applicable, the entire SHIPPINGINFO group should not appear in the request message. If SHIPPINGINFO is attached in the request, all data elements are required.
SHIPPINGNAME

✓

 string The recipient's name Length 1 ~ 34
SHIPPINGMETHOD

✓

 enum The shipping method SameDay: delivery at the same day
NextDay:delivery at the next day
TwoDay: delivery in 2 days
ThreeDay: delivery in 3 days
LowCost: Low cost delivery
Pickup: receive in the store
Other: other
None: services or signature
SHIPPINGDDD

✓

 string The 2-digit Brazil area code for the phone number Always 2 digits, 00 is not accepted
SHIPPINGPHONE

✓

 string The shipping phone number Length 8 ~ 11
SHIPPINGSTREET

✓

 string The shipping address street Length 1 ~ 70
SHIPPINGNUMBER

✓

 string The shipping address number Length 1 ~ 10
SHIPPINGNEIGHBORHOOD

✓

 string The shipping address neighborhood Length 1 ~ 50
SHIPPINGCITY

✓

 string The shipping address city Length 1 ~ 50
SHIPPINGSTATE

✓

 string The shipping address state/district 2 digit state code, for example, SP (São Paulo)
SHIPPINGZIPCODE

✓

 string The shipping address zip code 8 digit zip code, only numbers accepted
SHIPPINGCOUNTRY

✓

 string The shipping address country Length 1 ~ 35
PRODUCTLIST

✓

 object The product details, can contain multiple PRODUCT items in the list
PRODUCT

✓

 object The product item object
PRODUCTNAME

✓

 string The product name Length 4 ~ 100
PRODUCTPRICE

✓

 decimal The product unit price For example: 10.00
PRODUCTQTY

✓

 decimal The product quantity
PRODUCTCODE

✓

 string The product code or SKU Length 1 ~ 100

Boleto Specific Request Parameters

Parameter Required Type Description Validation
BR_EXPDATE

✓

 string Last date that this document could be accepted by the bank system, format: yyyy-MM-dd.
BR_CALLBACKURL

✓

 string Call back URL from the merchant.
BR_INSTRUCTIONS

✓

 string Instructions for the bank and customer to be included in the bank slip.
BR_EMAIL

✓

 string Email for sending the bank slip.
BR_CUSTOMERNAME

✓

 string Credit card number.
BR_DOCUMENT

✓

 string Document number. For Brazilians, the expected document will be C.P.F. or CNPJ - Data format can be 023.472.201-01 or 02347220101.
BR_ADDRESS_STREET

✓

 string
BR_ADDRESS_NUMBER

✓

 string
BR_ADDRESS_COMPLEMENT

✓

 string
BR_ADDRESS_ZIPCODE

✓

 string
BR_ADDRESS_NEIGHBORHOOD

✓

 string
BR_ADDRESS_CITY

✓

 string
BR_ADDRESS_STATE

✓

 string
BR_ADDRESS_COUNTRY

✓

 string
BR_SPLITMODE

✓

 string
BR_SPLITS string
BR_SPLIT_ITEM string
BR_SPLITS_DOCUMENT string
BR_SPLITS_VALUE decimal

Boleto Specific Response Parameters

Parameter Type Description Options
BR_BARCODE String Barcode string.
BR_DIGITABLELINE String Digitable line.
BR_URL String Boleto download URL.

Boleto Split Mode Request Parameters

Parameter Required Type Description Validation
BR_EXPDATE

✓

 string Last date that this document could be accepted by the bank system, format: yyyy-MM-dd.
BR_CALLBACKURL

✓

 string Call back URL from the merchant.
BR_INSTRUCTIONS

✓

 string Instructions for the bank and customer to be included in the bank slip.
BR_EMAIL

✓

 string Email for sending the bank slip.
BR_CUSTOMERNAME

✓

 string Credit card number.
BR_DOCUMENT

✓

 string Document number. For Brazilians, the expected document will be C.P.F. or CNPJ - Data format can be 023.472.201-01 or 02347220101.
BR_ADDRESS_STREET

✓

 string
BR_ADDRESS_NUMBER

✓

 string
BR_ADDRESS_COMPLEMENT

✓

 string
BR_ADDRESS_ZIPCODE

✓

 string
BR_ADDRESS_NEIGHBORHOOD

✓

 string
BR_ADDRESS_CITY

✓

 string
BR_ADDRESS_STATE

✓

 string
BR_ADDRESS_COUNTRY

✓

 string
BR_SPLITMODE

✓

 string
BR_SPLITS string
BR_SPLIT_ITEM string
BR_SPLITS_DOCUMENT string
BR_SPLITS_VALUE decimal

Boleto Split Mode Response Parameters

Parameter Type Description Options
BR_BARCODE string Barcode string.
BR_DIGITABLELINE string Digitable line.
BR_URL string Boleto download URL.

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>
      <XOPTION>TRUE</XOPTION>
   </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
XOPTION Bool Show the search result in XML or escaped XML. Options: TRUE or FALSE
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. See Transaction Result values.
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 periodic identifier returned when creating a periodic 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.

Transaction Result values

Value Description
SUCCESS Pull transactions with result CAPTURED, SETTLED, APPROVED, PENDING
UNSUCCESS Pull transactions with result DECLINED, ERROR, REJECTED, CHARGEBACK
CAPTURED Successful transactions that have not settled.
SETTLED Settled transactions.
APPROVED Successful pre-auth transactions.
DECLINED Declined transactions.
VOIDED Voided transactions.
ERROR Transactions failed due to error.
REJECTED Transactions been rejected by the processor at settlement time.
PENDING Transactions been settled, but not yet received settlement confirmation.
CHARGEBACK Credit card charge back or ACH return.

Response Parameters

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>0000010218</PWCLIENTID>
    <SEARCHRESULT>
        <PWPAYDETAIL>
            <PWUID>281195</PWUID>
            <BATCHID>526</BATCHID>
            <TRANSTYPE>SALE</TRANSTYPE>
            <CARDTYPE>VISA</CARDTYPE>
            <CARDNUM>X1111</CARDNUM>
            <SALEAMOUNT>30.00</SALEAMOUNT>
            <TRANSAMOUNT>30.00</TRANSAMOUNT>
            <ADJAMOUNT>0.00</ADJAMOUNT>
            <TIPAMOUNT>0.00</TIPAMOUNT>
            <TAXAMOUNT>0.00</TAXAMOUNT>
            <CREDITAMOUNT>0.00</CREDITAMOUNT>
            <AUTHCODE>281195</AUTHCODE>
            <RESULT>CAPTURED</RESULT>
            <NAME>Test Customer</NAME>
            <RECURRINGID>0</RECURRINGID>
            <TRANSTIME>11/09/2020 05:54 PM</TRANSTIME>
            <PWINVOICENUMBER>test12345</PWINVOICENUMBER>
            <PWCUSTOMID2>16049624941775886</PWCUSTOMID2>
            <SETTLEMENTDATE>2021-01-12</SETTLEMENTDATE>
        </PWPAYDETAIL>
        <PWPAYDETAIL>
            <PWUID>281195</PWUID>
            <BATCHID>526</BATCHID>
            <TRANSTYPE>SALE</TRANSTYPE>
            <CARDTYPE>MC</CARDTYPE>
            <CARDNUM>X8390</CARDNUM>
            <SALEAMOUNT>30.00</SALEAMOUNT>
            <TRANSAMOUNT>30.00</TRANSAMOUNT>
            <ADJAMOUNT>0.00</ADJAMOUNT>
            <TIPAMOUNT>0.00</TIPAMOUNT>
            <TAXAMOUNT>0.00</TAXAMOUNT>
            <CREDITAMOUNT>0.00</CREDITAMOUNT>
            <AUTHCODE>281198</AUTHCODE>
            <RESULT>CAPTURED</RESULT>
            <NAME>Sample Name</NAME>
            <RECURRINGID>0</RECURRINGID>
            <TRANSTIME>11/09/2020 05:57 PM</TRANSTIME>
            <PWINVOICENUMBER>test12346</PWINVOICENUMBER>
            <PWCUSTOMID2>16049626269154343</PWCUSTOMID2>
            <SETTLEMENTDATE>2021-01-12</SETTLEMENTDATE>
         </PWPAYDETAIL>
    </SEARCHRESULT>
</PAYMENTRESPONSE>

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

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

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. See Transaction Result values.
NAME string Account holder full name.
CUSTOMERID string Paywire customer identifier associated with a token.
RECURRINGID int Periodic identifier of a periodic 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 periodic payments handled outside Paywire. C: Regular Token Sale
I: First Payment of a Periodic Plan
R: Subsequent Periodic Payment
T: Last Payment of a Periodic Plan
SETTLEMENTDATE Date Transaction settlement date. YYYY-MM-DD

API Search Chargeback

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>SEARCHCB</PWTRANSACTIONTYPE>
      <XOPTION>TRUE</XOPTION>
   </TRANSACTIONHEADER>
   <SEARCHCONDITION>
      <COND_DATEFROM>2020-12-01</COND_DATEFROM>
      <COND_DATETO>2020-12-31</COND_DATETO>
      <COND_CBTYPE>ALL</COND_CBTYPE>
      <COND_INSTITUTION>ALL</COND_INSTITUTION>
      <COND_UNIQUEID />
    </SEARCHCONDITION>
</PAYMENTREQUEST>

To search Chargeback transactions within the gateway, submit SEARCHCB 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. SEARCHCB
XOPTION Bool Show the search result in XML or escaped XML. Options:
TRUE
FALSE
COND_DATEFROM DateTime Search date range from. Date Format YYYY-MM-DD.
COND_DATETO DateTime Search date range to. Date Format YYYY-MM-DD.
COND_CBTYPE

✓

 string Chargeback Search Options. Options:
ALL
CHARGEBACK
RETRIEVAL
REJECT
COND_INSTITUTION

✓

 string Chargeback Search Options. Options:
ALL: Search for Chargebacks for all the MIDS in the institution.
CURRENT: Search for Chargebacks for the current MID only.

Response Parameters

Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
    <RESULT>SUCCESS</RESULT>
    <PWCLIENTID>{clientId}</PWCLIENTID>
    <SEARCHRESULT>
        <PWCBDETAIL>
            <MID>635464646541</MID>
            <EXTERNALMID>941000131267890</EXTERNALMID>
            <PWUID>4771769</PWUID>
            <CARDTYPE>CUP</CARDTYPE>
            <NAME>TEST NAME</NAME>
            <RETURNDATE>2021-01-14</RETURNDATE>
            <RESULT>CHARGEBACK</RESULT>
            <RETURNAMOUNT>5.00</RETURNAMOUNT>
            <RETURNCODE>4502</RETURNCODE>
            <RESPONSETEXT>Transaction was Settled but Cash/Goods/Services were not Received</RESPONSETEXT>
            <CBCYCLE>1</CBCYCLE>
            <CBCURRENCY>USD</CBCURRENCY>
            <CBTRACENUM>808485</CBTRACENUM>
            <TRAMOUNT>100.00</TRAMOUNT>
            <TRCURRENCY>USD</TRCURRENCY>
            <TRDATETIME>2021-01-12 11:51:53</TRDATETIME>
            <PWINVOICENUBMER>trans_test_002</PWINVOICENUBMER>
            <CARDDATA>622222xxxxxx1234</CARDDATA>
            <DESCRIPTOR>Sample Merchant Sample City USA</DESCRIPTOR>
        </PWCBDETAIL>
        <PWCBDETAIL>
            <MID>635464646123</MID>
            <EXTERNALMID>941000131212345</EXTERNALMID>
            <PWUID>4771711</PWUID>
            <CARDTYPE>CUP</CARDTYPE>
            <NAME> </NAME>
            <RETURNDATE>2020-12-05</RETURNDATE>
            <RESULT>CHARGEBACK</RESULT>
            <RETURNAMOUNT>10.00</RETURNAMOUNT>
            <RETURNCODE>9706</RETURNCODE>
            <RESPONSETEXT>Special Adjustment - Other</RESPONSETEXT>
            <CBCYCLE>1</CBCYCLE>
            <CBCURRENCY>USD</CBCURRENCY>
            <CBTRACENUM>702147</CBTRACENUM>
            <TRAMOUNT>100.00</TRAMOUNT>
            <TRCURRENCY>USD</TRCURRENCY>
            <TRDATETIME>2021-01-05 18:03:24</TRDATETIME>
            <PWINVOICENUBMER>trans_test_002</PWINVOICENUBMER>
            <CARDDATA>622222xxxxxx1234</CARDDATA>
            <DESCRIPTOR>Test Merchant Test City USA</DESCRIPTOR>
        </PWCBDETAIL>
    </SEARCHRESULT>
</PAYMENTRESPONSE>

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

Parameter Type Description Options
MID int Merchant Identifier.
EXTERNALMID int External Merchant Identifier.
PWUID int Unique transaction ID associated with the transaction(s) being searched.
CARDTYPE string The type of card the transaction(s) being searched were processed with.
NAME string Account holder full name.
RETURNDATE Date Timestamp of the Search transaction. YYYY-MM-DD
RESULT string Status for the transaction. See Transaction Result values.
RETURNAMOUNT decimal Return Amount of transaction(s) being searched.
RETURNCODE string Return code associated with the transaction.
RESPONSETEXT string Response Text of the Transaction.
CBCYCLE int Chargeback Cycle. Currently it is always "1"
CBCURRENCY string Chargeback Currency. USD / EUR / CNY
CBTRACENUM int Trace number for each chargeback record.
TRAMOUNT decimal Original transaction amount.
TRCURRENCY string Original transaction currency. USD / EUR / CNY
TRDATETIME Datetime Original transaction date time. YYYY-MM-DD HH:mm:ss
PWINVOICENUBMER int Original transaction invoice number, provided by merchant. Length 0~60
CARDDATA int Card number first 6 and last 4 number of the card will be displayed. Example:123456xxxxxx1234
DESCRIPTOR string Descriptor showing on customer's bank statement. Length 0~41

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.

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 behaviors 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 Periodic, 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>
      <AUTHTOKEN>4C2F8EE94CA2491AAB67EA6541CB17BA</AUTHTOKEN>
      <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>

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>
      <AUTHTOKEN>4C2F8EE94CA2491AAB67EA6541CB17BA</AUTHTOKEN>
      <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 Periodic 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 Periodic 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 periodic 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 periodic 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.

OSBP China UnionPay

CUP OSBP #1: Request: Secure Plus One-Time Sale 

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>CHS</LANGUAGE>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>3</PWCTRANSTYPE>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #1: Response: Secure Plus One-Time Sale

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <AUTHCODE>
        </AUTHCODE>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000191599</PWCUSTOMID2>
  </PAYMENTRESPONSE>

CUP OSBP #2: Request: Secure Plus Sale and save customer with token - New Customer (no PWCID):

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>CHS</LANGUAGE>
        <FORCESAVETOKEN>TRUE</FORCESAVETOKEN>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>4</PWCTRANSTYPE>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #2 Example transaction notes:
Set FORCESAVETOKEN to FALSE to allow the customer to decide whether to save token.

CUP OSBP #2: Response: Secure Plus Sale and save customer with token - New Customer (no PWCID):

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>696</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000194342</PWCUSTOMID2>
        <PWCID>P0000007087</PWCID>
  </PAYMENTRESPONSE>

CUP OSBP #2 Response transaction notes:
PWCID: P0000007087 (The Payscout Customer ID represents for a customer.)
PWTOKEN: TFC0206A817A7459 (The Payscout Token represents for a payment method. A customer can have multiple payment methods.)
PWUNIQUEID: 191601 (The Transaction Unique ID to be used for the non-secureplus subsequent transactions.)

CUP OSBP #3: Request: Secure Plus Token Sale - No Customer/PWCID involved, merchant to manage payment token:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>CHS</LANGUAGE>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>1</PWCTRANSTYPE>
     <PWTOKEN>TFC0206A817A7459</PWTOKEN>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #3 Request transaction notes:
PWTOKEN is the one derived from CUP OSBP #2.

CUP OSBP #3: Response: Secure Plus Token Sale - No Customer/PWCID involved, merchant to manage payment token:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>696</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000194342</PWCUSTOMID2>
  </PAYMENTRESPONSE>

CUP OSBP #4: Request: Secure Plus Sale and add new token to existing customer (with PWCID) - Paywire to manage the customer saved token. Merchant only manages the Custommer ID (PWCID):

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>CHS</LANGUAGE>
        <FORCESAVETOKEN>FALSE</FORCESAVETOKEN>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>4</PWCTRANSTYPE>
     <PWCID>P0000007087</PWCID>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #4 Request transaction notes:
PWCID from CUP OSBP #2.

CUP OSBP #4: Response: Secure Plus Sale and add new token to existing customer (with PWCID) - Paywire to manage the customer saved token. Merchant only manage Custoemr ID (PWCID):

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>691</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000192085</PWCUSTOMID2>
        <PWCID>P0000007087</PWCID>
  </PAYMENTRESPONSE>

CUP OSBP #5: Request: Token Sale - with PWCID:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>ENG</LANGUAGE>
        <FORCESAVETOKEN>FALSE</FORCESAVETOKEN>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>2</PWCTRANSTYPE>
     <PWCID>P0001272164</PWCID>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #5 Request transaction notes:
PWCID from CUP OSBP #2.

CUP OSBP #5: Response: Token Sale - with PWCID:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>696</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000192085</PWCUSTOMID2>
        <PWCID>P0001272164</PWCID>
  </PAYMENTRESPONSE>

CUP OSBP #6: Request: Non Secure Plus Recurring/Customer Sale - First Transaction:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>ENG</LANGUAGE>
        <FORCESAVETOKEN>TRUE</FORCESAVETOKEN>
        <NONSECUREPLUS>TRUE</NONSECUREPLUS>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>4</PWCTRANSTYPE>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #6: Response: Non Secure Plus Recurring/Customer Sale - First Transaction:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>696</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000192085</PWCUSTOMID2>
        <PWCID>P000000A074</PWCID>
  </PAYMENTRESPONSE>

CUP OSBP #7: Request: Non Secure Plus Recurring/Customer Sale - Subsequent Transaction:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTREQUEST>
     <TRANSACTIONHEADER>
        <PWVERSION>3</PWVERSION>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWKEY>{key}</PWKEY>
        <AUTHTOKEN>{authtoken}</AUTHTOKEN>
        <PWTRANSACTIONTYPE>SALE</PWTRANSACTIONTYPE>
        <PWSALEAMOUNT>10.00</PWSALEAMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <PWAPPROVALURL>https://www.clientdomain.com/approval</PWAPPROVALURL>
        <PWDECLINEURL>https://www.clientdomain.com/decline</PWDECLINEURL>
        <ISCUP>TRUE</ISCUP>
        <LANGUAGE>ENG</LANGUAGE>
        <NONSECUREPLUS>TRUE</NONSECUREPLUS>
     </TRANSACTIONHEADER>
     <CUSTOMER>
     <FIRSTNAME>John</FIRSTNAME>
     <LASTNAME>Doe</LASTNAME>
     <PRIMARYPHONE>86-13012345678</PRIMARYPHONE>
     <PWCTRANSTYPE>1</PWCTRANSTYPE>
     <PWTOKEN>TFC0206A817A7459</PWTOKEN>
     <PWUNIQUEID>191601</PWUNIQUEID>
     </CUSTOMER>
  </PAYMENTREQUEST>

CUP OSBP #7 Request transaction notes:
PWTOKEN and PWUNIQUEID from CUP OSBP #6

CUP OSBP #7: Response: Non Secure Plus Recurring/Customer Sale - Subsequent Transaction:

<?xml version="1.0" encoding="UTF-8"?>
  <PAYMENTRESPONSE>
        <PWCLIENTID>{clientId}</PWCLIENTID>
        <PWINVOICENUMBER>testcup001</PWINVOICENUMBER>
        <RESULT>APPROVAL</RESULT>
        <AMOUNT>10.00</AMOUNT>
        <CURRENCY>CNY</CURRENCY>
        <MACCOUNT>XXXXXXXXXXXX0017</MACCOUNT>
        <PAYMETH>C</PAYMETH>
        <CCTYPE>CUP</CCTYPE>
        <AHNAME>John Doe</AHNAME>
        <AHFIRSTNAME>John</AHFIRSTNAME>
        <AHLASTNAME>Doe</AHLASTNAME>
        <PWUNIQUEID>191601</PWUNIQUEID>
        <BATCHID>696</BATCHID>
        <AUTHCODE></AUTHCODE>
        <PWTOKEN>TFC0206A817A7459</PWTOKEN>
        <CVVCODE> </CVVCODE>
        <PWCUSTOMID2>000000192085</PWCUSTOMID2>
   </PAYMENTRESPONSE>

The China UnionPay OSBP is multilingual and supports display and processing of multiple currencies. Please see the table below for a list of fields that are specific to the China UnionPay OSBP:

Parameter Required Type Description Validation
AUTHTOKEN

✓

 string The Authentication Token to be used when calling the OSBP.
ISCUP

✓

 string Must set to TRUE for China UnionPay transactions. TRUE
CURRENCY

✓

 string Set the transaction currency. USD/CNY/EUR
LANGUAGE

✓

 string Switch language for the CUP OSBP. CHS/ENG
FORCESAVETOKEN

✓

 string Available for PWCTRANSTYPE = 2 or 4, default is TRUE, Set to FALSE to allow the customer to decide save the token or not. TRUE/FALSE
NONSECUREPLUS

✓

 string Only available for PWCTRANSTYPE = 1 or 4. The user must manage the customer token and the transaction ID of the first transaction. Set to TRUE if the client wants to process token sales as non-secureplus with no SMS code verification for subsequent transactions. Debit card not supported. When this is set to TRUE, must provide the PWUNIQUEID of the first transaction in the subsequent transaction request. TRUE/FALSE

China UnionPay Test Cards:

Credit Card:
6222821234560017, Phone Number: 86-13012345678
Debit:
6250946000000016, Phone Number: 852-11112222
Exp: 12/33
CVV: 123
SMS Code: 111111

OSBP Brazil

The Brazil OSBP has two fields specific to this payment type:

Parameter Required Type Description Validation
BR_DOCUMENT

✓

 string For Brazilians bank slip the expected document will be C.P.F. or CNPJ - Data format can be 023.472.201-01 or 02347220101.
TOTALINSTALLMENTS string The total number of installment payments for a periodic payment.

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 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 like 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 Periodic Sale

Periodic 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 Periodic 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 periodic 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 periodic 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 Periodic Sale include the RECURRING block at the end as you would for a normal Periodic 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 periodic payments handled outside Paywire. Submit this in the TRANSACTIONHEADER block. C: Regular Token Sale
I: First Payment of a Periodic Plan
R: Subsequent Periodic Payment
T: Last Payment of a Periodic 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>

Periodic 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>

Appendix

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

CVV Codes

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

Value Description
M Match
P Not Processed
G Verification unavailable due to international issuer non-participation (Visa only)
N No match

SMS Decline Codes

SMS Decline Code Decline Message
S00 Success
S01 Transaction failed. For details please inquire overseas service hotline
S02 System is not started or temporarily down, please try again later
S03 Transaction communication time out, please initiate inquiry transaction
S05 Transaction has been accepted, please inquire about transaction result shortly
S06 System is busy, please retry it later.
S10 Message format error
S11 Verify signature error
S12 Repeat transaction
S13 Message transaction key element missing
S30 Transaction failed, please try using other UnionPay card for payment or contact overseas service hotline
S31 Merchant state incorrect. The payment is not completed within the order timeout
S32 No such transaction right
S33 Transaction amount exceeds limit
S34 Could not find this transaction
S35 Original transaction does not exist or state is incorrect
S36 Does not match original transaction information
S37 Max number of inquiries exceeded or too frequent operations
S38 UnionPay risk constraint
S39 Transaction is not within the acceptance time range
S42 Balance deduction successful but transaction exceeded payment time limit
S43 Business not allowed, please contact overseas service hotline for help.
S44 Wrong number entered or business not opened, please contact overseas service hotline for help
S45 The original transaction has been refunded or cancelled successfully
S60 Transaction failure, for details, please inquire with your issuer
S61 Card number entered is invalid, please double check and enter
S62 Transaction failed, issuer does not support this merchant, please change to another bank card
S63 Card state is incorrect
S64 Card balance is insufficient
S65 Error with PIN, expiration date, or CVN2 entered, transaction failure
S66 Cardholder identity information or mobile number entered are incorrect, verification failure
S67 Limit on number of PIN entry attempts exceeded
S68 Your bank card currently does not support this business, please inquire with your bank or overseas service hotline for help
S69 Time limit on entry exceeded, transaction failure
S70 Transaction has been redirected, waiting for cardholder input
S71 Dynamic password or SMS verification code validation failure
S72 You have not signed up for UnionPay card-not-present payment service at the bank counter or on your personal online bank, please go to a bank counter or access your online banking to activate it or contact overseas service hotline for help
S73 Payment card has exceeded expiration date
S76 Requires encryption verification for activation
S77 Bank card has not been activated for authenticated payment
S78 Issuer transaction rights limited, for details please contact your issuer
S79 The bank card is valid, but issuer does not support SMS verification
S80 Transaction failed and the token has expired
S81 Monthly accumulated transaction counter (amount) exceeded
S82 PIN needs to be verified
S84 PIN is required but not submitted
S85 Transaction failed, the marketing rules are not met
S86 QRC status error
S87 Token has exceeded its maximum number of use
S88 QRC not found
S89 No Token found, invalid TR status or invalid Token status
S98 File does not exist
S99 General error
SA6 Partial success. Successful transaction with defect

Authorization Decline Codes

Authorization Decline Code Message
A00 Approve. Successful transaction
A01 Decline. The cardholder should contact the Issuer.
A03 Decline. Invalid merchant
A04 Pick-up. This card is picked up
A05 Decline. The cardholder's certification fails.
A10 Partial amount approved
A11 Approve. VIP
A12 Decline. Invalid transaction
A13 Decline. Invalid amount
A14 Decline. Invalid card number
A15 Decline. No Issuer matching this card
A16 Approve. Update the third magnetic track.
A1A Decline, The transaction need additional customer authentication
A20 Decline. Update the QRC
A21 Decline. This card has not been initialized or it is a dormant card.
A22 Decline. Suspected malfunction related transaction error
A25 Decline. There is no original transaction and please contact the Issuer
A30 Decline. Format error
A34 Pick-up. Fraudulent card, pickup card
A38 Decline. The number of PIN entry attempts is beyond the limit, and please contact the Issuer.
A40 Decline. Transaction that is not supported by the Issuer
A41 Pick-up. The card reported for loss is captured now (ATM). Lost card, please pick up it (POS).
A43 Pick-up. This card is captured (ATM). Please contact the Issuer. Stolen card, please pick it up (POS)
A45 Decline. Please use IC card
A51 Decline. Insufficient available balance
A54 Decline. The card expires.
A55 Decline. Wrong PIN
A57 Decline. This card is not allowed for the transaction.
A58 Decline. The Issuer does not allow this card to be used for this
A59 Decline. Error in the card verification
A61 Decline. The transaction amount exceeds the limit.
A62 Decline. Restricted card
A64 Decline. The transaction amount does not match the original transaction amount
A65 Decline. Exceed the limit for times of withdrawal
A68 Decline. The transaction times out. Please retry it
A75 Decline. The number of PIN tries exceeds the limit
A90 Decline. The daily cutoff of the system is in progress. Please retry it later.
A91 Decline. The Issuer status is abnormal. Please retry it later
A92 Decline. The connectivity of Issuer is abnormal. Please retry it later
A94 Decline. Rejected for duplicated transaction. Please retry it later
A96 Decline. Rejected for switching center malfunction. Please retry it later.
A97 Decline. The terminal number has not been registered
A98 Decline. The Issuer is time out.
A99 Decline. Error in PIN format. Please re-sign in
AA0 Decline. Error in MAC verification. Please resign in
AA1 Reserved
AA2 Approve. The transaction is successful. Please confirm it with the fund transfer-in bank
AA3 Decline. The recipient’s account number is incorrect for the fund transfer-in bank.
AA4 Approve. The transaction is successful. Please confirm it with the fund transfer-in bank
AA5 Approve. The transaction is successful. Please confirm it with the fund transfer-in bank
AA6 Approve. The transaction is successful. Please confirm it with the fund transfer-in bank
AA7 Security processing failure
AB1 Decline. No debt for this service
AC1 Decline. The state of the Acquirer is illegal.
AD1 Incorrect IIN
AD2 Date Error
AD3 Invalid file type
AD4 File processed
AD5 No such file
AD6 Not supported by Receiver
AD7 File locked
AD8 Unsuccessful
AD9 Incorrect file length
ADA File decompression error
ADB File name error
ADC File cannot be received
AF1 File record format error
AF2 File record repeated
AF3 File record not existing
AF4 File record error
AN1 Decline. The unregistered account exceeds the limit.
AP1 Decline. Contact number (e.g. mobile phone number) cannot be found.
AY1 Approve
AY3 Approve
AZ1 Decline
AZ3 Decline
C# VB cURL