Introduction
The Paywire Gateway implements different payment gateways, offering a simple integration with an increasing number of features.
Four integration options are made available:
- Application Programming Interface (API)
- Off Site Buy Page (OSBP)
- Checkout Page (via OSBP)
- 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. |
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:
- Implement logic in your application to determine the transaction type required.
- Collect the necessary information from the customer (where applicable), which may include PCI data.
- Build an XML string including Authentication parameters and at minimum the mandatory fields for the transaction type being processed.
- Send an HTTP POST containing the XML string to the Paywire API endpoint.
- Receive an XML response to parse and use.
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) | ||
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. | ||
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><PWTOKENDETAIL><PWTOKEN>T2C5243173034401</PWTOKEN><PWMEDIA>CC</PWMEDIA><CCTYPE>MC</CCTYPE><MACCOUNT>XXXXXXXXXXXX0608</MACCOUNT><EXP_MM>02</EXP_MM><EXP_YY>22</EXP_YY></PWTOKENDETAIL></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. | ||
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:
- 023.472.201-01
- 242.189.959-15
- 843.345.449-83
- 885.870.260-38
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 phoneWeb : 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. | |
✓ |
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:
- 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.
- 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.
- 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:
- Optionally collect non-PCI customer information such as Name, Address and Contact information from your website.
- Create a Sale XML request string including Authentication parameters, Approval URL and Decline URL.
- Perform a HTTP POST with a HTML form containing the XML request string to the OSBP endpoint using the relevant URL.
- Customer is redirected to the Paywire OSBP, possibly with the option to choose a Payment Method.
- Customer completes or cancels the payment.
- 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 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. | ||
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. | |
✓ |
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:
- Ingenico IPP320
- Ingenico ICMP
OCX Installation
The latest version of the OCX can be downloaded here.
Once downloaded:
Run
Install.bat
as Administrator.OR
Run
pwIngOCXSetup.msi
as Administrator.
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);
}
To implement the OCX in your application:
- Add the
pwIngenicoOCX Control
to your list of UI components, available in the COM Components list once installed. - Insert the
pwIngenicoOCX Control
in your GUI. This enables you to utilize theAxpwIngenicoOCX
class containing methodIngenico_ProcessOnDemandOCX(string pARAS)
- 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. - The
Ingenico_ProcessOnDemandOCX
method will return an XML string with the results.
To process a transaction:
- Click the button (or otherwise) that calls
axpwIngenicoOCX.Ingenico_ProcessOnDemandOCX(string pARAS)
. - Complete the payment using a reader.
- The OCX will return a response based on the result of the request.
Visual Studio 2017 Example:
- Install the OCX as explained here.
- Navigate to the project you wish to add the OCX to.
- Open a Form in a 'Design' view.
- Open your Toolbox, right-click and click "Choose Items".
- Switch to the "COM Components" tab and locate the "pwIngenicoOCX Control" component. If not found you may need to browse for it.
- Tick the "pwIngenicoOCX Control" and it should now be available to use in the Toolbox.
- Add the "pwIngenicoOCX Control" component to your form, along with a button.
- Navigate to view the button code (double-click the button from the design page).
- 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. | |
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 | |||||||||||
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);
}
}
To implement the OCX in your application:
- Add the
pwIngenicoOCX Control
to your list of UI components, available in the COM Components list once installed. - Insert the
pwIngenicoOCX Control
in your GUI. This enables you to utilize theAxpwIngenicoOCX
class containing methodOcx_Init(string pARAS)
. - 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. - Add an event handler method for
AxpwIngenicoOCXLib._DpwIngenicoOCXEvents_DialogTransEventEvent
, which will includeresponsMsg
as the XML payment response.
To process a transaction:
- Click the button (or otherwise) that calls
axpwIngenicoOCX.Ocx_Init(string pARAS)
. - Click the
AxpwIngenicoOCX
control on your form to pull up the OCX form. - Populate the fields on the OCX form and click to process.
- The OCX will return a response based on the result of the request that is captured by your event handler.
Visual Studio 2017 Example:
- Install the OCX as explained here.
- Navigate to the project you wish to add the OCX to.
- Open a Form in a 'Design' view.
- Open your Toolbox, right-click and click "Choose Items".
- Switch to the "COM Components" tab and locate the "pwIngenicoOCX Control" component. If not found you may need to browse for it.
- Tick the "pwIngenicoOCX Control" and it should now be available to use in the Toolbox.
- Add the "pwIngenicoOCX Control" component to your form, along with a button.
- Navigate to view the button code (double-click the button from the design page).
- 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. - If using the UI form (
Ocx_Init
), add an event handler forAxpwIngenicoOCXLib._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. | ||
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 |
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. | ||
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".
The message at the bottom is configurable in the VPOS merchant admin page.
A Convenience Fee breakdown is displayed on the Payment Form:
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:
DISABLECF
- disables applying a 'Convenience Fee' for a given transaction.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:
- The merchant submits a One-Time-Sale request (that includes
REQUESTTOKEN
set toTRUE
if not using a card). - The merchant stores the
PWADJAMOUNT
andPWTOKEN
from the response to be used later. - In the subsequent sales, the merchant submits a Token Sale including the
PWADJAMOUNT
andPWTOKEN
tags with the respective values stored in (2), along with aPOSINDICATOR
ofP
.
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 |