Gateway API

Introduction

This document provides technical specifications for processing financial transactions through Paysafe Solutions Transaction Gateway Host by interfacing with the Gateway API.

The audiences of this document are for business analysts and software programmers who design, implement, and support the intended system.

Gateway API

Gateway API is a server side application that provides a direct link to the Paysafe Solutions Transaction Gateway Host. All communications between the client machines and the Gateway API takes place over a Hypertext Transfer Protocol (HTTP) over a 128-bit Secure Socket Layer (HTTPS) on the Internet. Any device or platform with the ability to originate an HTTPS connection can perform financial transactions through the Gateway API.

The request is constructed using name/value pairs as defined per transaction type. The response received would also be in name/value pairs as defined per transaction type.

Test Transaction Information

To verify your transactions processed successfully, log on to the Payment XP gateway at www.paymentxp.com. The credentials are below.

Field	Value
URL	www.paymentxp.com
Username	10012
Password	Password@3

Test transactions can be submitted with the following information:

Card Type	Card Number
Merchant ID	10012
Merchant Key	c22a63ee-2e7a-4ace-96ac-0958dc8d953f
Hosted Payment Key	1QZYRLqw0vbL6gZTinRv+WqfZF/jIrYDALbMppssqHRKKmtatc+kmCIjumfpqipE
Visa	4111111111111111
MasterCard	5431111111111111
Discover	6011601160116611
American Express	341111111111111
Credit Card Expiration	Use any date beyond today's date in MMYY format
Bank Routing Number* You may use the routing number provided here or any other valid routing number	325070760
ACH Account Number	1234567890

How to settle a Transaction to Test Refunds

1. Login into paymentxp.com
2. Click on Reports>Transaction Detail
3. Locate the transaction you would like to settle in order to test a refund
4. Click on the Transaction ID number
5. Click the Settle button

Token Methods

Credit Card Transactions

NOTE: The token will expire in 20 minutes after initialization.

Description: This method returns a Token that can be used to perform various credit card transactions through the functions below. The Token will replace the values passed in the GetToken method to be used with these functions.

Resource Url: https://webservice.paymentxp.com/wh/GetToken.aspx

Method: POST

Request

ACH Transactions

NOTE: The token will expire in 20 minutes after initialization.

Description: GetToken for ACH Transactions

Resource Url: https://webservice.paymentxp.com/wh/GetToken.aspx

Method: POST

Request

Hosted Payment

NOTE: The token will expire in 20 minutes after initialization.

Description: GetToken for Payment Hosted

Resource Url: https://webservice.paymentxp.com/wh/GetToken.aspx

Method: POST

Request

Customer Hosted

NOTE: The token will expire in 20 minutes after initialization.

Description: GetToken for Customer Hosted

Resource Url: https://webservice.paymentxp.com/wh/GetToken.aspx

Method: POST

Request

Credit Card Methods

CreditCardAuthorization

Description: This method authorizes a credit card transaction by requesting an authorization number from the card issuer. An approved authorization means that the transaction dollar amount has been reserved for usage but not yet deducted from the cardholder’s account. Funds are not settled (transferred to the merchant) until the CreditCardSettle() method is called using the authorization number returned by this method.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCapture

Description: This method captures (transfers to the merchant) a transaction previously authorized with the Authorize() method. Captured transactions are scheduled for settlement at the determined batch time.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCharge

Description: This method performs both authorization and settlement into one operation.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCredit

Description: This method credits a credit card account with an originating Settle or Charge transaction. The credit is based on a prior transaction performed through either CreditCardSettle() or CreditCardCharge().

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardVoid

Description: This method cancels a previously completed Authorization or Charge transaction. A transaction that has already been settled using the CreditCardSettle() method cannot be voided, but instead do perform a Credit on the account.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardAdjust

Description: This method modifies the Transaction Amount of a previously processed CreditCardCharge(), CreditCardAuthorization(), or AddCustomerCCCharge(). This method can be used to modify the captured amount up to the original Transaction Amount. To Adjust over the original Transaction Amount, contact your Integration Specialist for more details.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCaptureOnly

Description: This method creates a credit card transaction for settlement by with an offline authorization number from the card issuer. An approved authorization through other means is required to be submitted.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCreditBlind

Description: This method credits a credit card without the need of an originating Sales Transaction. Contact your Integration Specialist for more details.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardCloseBatch

Description: This method can only be used when the settlement time is set to MANUAL. This method will initiate a batch closure and schedule the batch for settlement. Contact your Integration Specialist for more details.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

AddCustomerCCCharge

Description: This method creates a credit card charge transaction from a customer record.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardHosted

Description: Use this method to let Paysafe perform collection of sensitive credit card information on our secure servers.

Resource Url: https://webservice.paymentxp.com/wh/EnterPayment.aspx

Method: POST

Request

CreditCardReBill

Description: Use this method to re-process a historical transaction.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardRecurringCharge

Description: This method schedules a credit card charge via a recurring payment. In most cases, CreditCardRebill() Method is preferred.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

CreditCardRecurringUpdate

Description: This method updates an existing recurring rule in the database.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

GetCreditCardTransaction

Description: This method retrieves a credit card transaction record from the database.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

Credit Card Batch File Upload

To use this interface option, all transaction data must be correctly formatted and saved in a batch file. Batch files can be formatted as comma-delimited. Our program polls the FTP directories every fifteen minutes to look for files that have been uploaded for processing.

FTP

Upon request, we will issue you a test account for development and testing. Once you’ve been certified, a production account will be created for you. The certification process includes the following steps:

• Create a test batch file
• Send the test file to Paysafe' FTP server
• Notify Paysafe' Integration Department that the file has been uploaded
• Our developer will validate the batch file by running it against a test database
• If the file contains errors, the developer will notify you; otherwise, you will receive production account via email.

All files sent to us via SFTP shall be encrypted using PGP. Please contact us to obtain a free version of the PGP software and our public PGP key.

Batch File

Credit Card File Specification (Comma-Delimited)

The following guidelines shall be used for formatting transaction data sent in a comma-delimited batch file.

Parameter	Type	Length	Description
*Description	Text	50	Purpose of transaction.
*Trans Code	Text	2	312 = Credit Card Charge, 314 = Credit Card Refund
*CardNumber	Text	76	Identifies the cardholder’s account number. Not required for a refund transaction.
*ExpirationDateMMYY	Text	4	Identifies the cardholder’s account expiration date (format: MMYY).
*TransactionAmount	Numeric	9	Identifies the transaction’s total amount in US dollars.
BillingNameFirst	Text	50	The first name of the cardholder.
BillingNameLast	Text	50	The last name of the cardholder.
BillingAddress	Text	50	The billing address of the cardholder. Used to check for AVS identification.
BillingCity	Text	50	The billing city of the cardholder.
BillingState	Text	25	The billing state of the cardholder.
BillingZipCode	Text	10	The billing zip code of the cardholder. Used to check for AVS identification.
BillingCountry	Text	50	The billing country of the cardholder.
EmailAddress	Text	50	The e-mail address of the cardholder.
PhoneNumber	Text	10	The phone number of the cardholder.
ClerkID	Text	15	The cashier/clerk who initiated the transaction.
ReferenceNumber	Text	50	The merchant/customer transaction identifier.
OrigTransID	Numeric	19	This is the TransactionID value for the original transaction. (Use for refunds).
ShippingAddress1	Text	50	The shipping address for the product(s) purchased in the transaction.
ShippingAddress2	Text	50	The shipping address for the product(s) purchased in the transaction.
ShippingCity	Text	50	The shipping city for the product(s) purchased in the transaction.
ShippingState	Text	25	The shipping state for the product(s) purchased in the transaction.
ShippingZipCode	Text	10	The shipping zip code for the product(s) purchased in the transaction.
ShippingCountry	Text	50	The shipping country for the product(s) purchased in the transaction.
ClientIPAddress	Text	25	The IP address of the client device.
CustomInfo1	Text	255	For merchant use.
CustomInfo2	Text	255	For merchant use.
CustomInfo3	Text	255	For merchant use.
CustomInfo4	Text	255	For merchant use.
CustomInfo5	Text	255	For merchant use.
CustomInfo6	Text	255	For merchant use.
CustomInfo7	Text	255	For merchant use.
CustomInfo8	Text	255	For merchant use.
CustomInfo9	Text	255	For merchant use.
CustomInfo10	Text	255	For merchant use.
CustomInfo11	Text	255	For merchant use.
CustomInfo12	Text	255	For merchant use.
CustomInfo13	Text	255	For merchant use.
CustomInfo14	Text	255	For merchant use.
CustomInfo15	Text	255	For merchant use.
CustomInfo16	Text	255	For merchant use.
CustomInfo17	Text	255	For merchant use.
CustomInfo18	Text	255	For merchant use.
CustomInfo19	Text	255	For merchant use.
CustomInfo20	Text	255	For merchant use.

Note: Transaction data included in the batch file must be in comma-delimited format with quoted text

File Naming Convention - The batch file should be saved with an .ccb file extension using the following naming convention.

File Name	Description
YYMMDDNN.CCB	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 04111401.ccb Year=2004, Month=11, Day=14 & Batch Number=01

Note: The batch number is required. This is used to differentiate between batch files when a merchant sends more than one batch on the same day. If only one batch file is sent for a particular date, the batch number will always be entered as 01.

Response File Format

Response files are generated once a day, typically from 11:30 to 3 PM PST. Response file format is the same for both comma-delimited and NACHA batch file format.

Parameter	Type	Length	Description
RefID	Text	50	Merchant’s unique reference number
Amount	Numeric	8	Amount of sale
TransID	Numeric	10	Unique Key assigned by Paysafe
Authcode	Text	6	Authorization Code
Status	Text	25	Status is APPROVED or DECLINED
Reason	Text	100	Reject reason

File Naming Convention - The response file will have an .rsp file extension using the following naming convention.

File Name	Description
YYMMDDNN.RSP	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 10111401.rsp Year=2010, Month=11, Day=14 & Batch Number=01

ACH Integration Methods

This section describes integration requirements for invoking the HTTPS Post interface with an XML response. Transactions processed using this interface require the user to collect ACH information and sending the transaction data securely (via HTTPS) to our ACH gateway for processing. Through this interface, you can process ACH debits or credits. To use this interface please contact Paysafe for a MerchantID and MerchantKey.

ACHDebit

Description: Use these functions to create new ACH transactions. Below are the parameters for this method.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACHCredit

Description: Use these functions to create new ACH transactions. Below are the parameters for this method.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACHRefund

Description: Use the function to issue refunds to your customers. Below are the parameters for this method.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACHVoid

Description: Use this function to void open. Below are the parameters for this method. Method will return a TransID, which is the identified for the ACH transaction.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

AddCustomerACHDebit

Description: This method creates an ACH debit transaction from a customer record.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

AddCustomerACHCredit

Description: This method creates an ACH credit transaction from a customer record.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

GetAchTransaction

Description: This method retrieves an ACH transaction record from the database.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACHRecurringDebitInsert

Description: This method creates a recurring ACH debit transaction rule.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACHRecurringDebitUpdate

Description: This method updates a recurring ACH debit transaction rule.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request

ACH Batch File Upload Interface

To use this interface option, all transaction data must be correctly formatted and saved in a batch file. Batch files can be formatted as either comma-delimited or NACHA (fixed width). Our program polls the FTP directories every fifteen minutes to look for files that have been uploaded for processing.

FTP

Upon request, we will issue you a test account for development and testing. Once you’ve been certified, a production account will be created for you. The certification process includes the following steps:

1. Create a test batch file
2. Send the test file to Paysafe' FTP server
3. Notify Paysafe' Integration Department that the file has been uploaded
4. Our developer will validate the batch file by running it against a test database
5. If the file contains errors, the developer will notify you; otherwise, you will receive production account via email.

All files sent to us via SFTP shall be encrypted using PGP. Please contact us to obtain a free version of the PGP software and our public PGP key.

Batch File

The following guidelines shall be used for formatting transaction data sent in a comma-delimited batch file.

Parameter	Type	Length	Description
*Description	Text	10	Purpose of transaction. Description is required for ACH. This field shows up on customer’s bank statement.
*Trans Code	Text	2	27= Debit to checking account, 37= Debit to savings account
*ABA Expire	Text	9	Routing Number or ABA
*Account No	Text	17	Account Number or DDA
*Account Name	Text	22	Name on account
Ref ID	Text	50	User’s unique reference ID (Invoice #, Order # or Acct. No.)
*Amount	Numeric	8	Transaction Amount (with decimal point)
*SECC Code	Text	3	NACHA SECC Code indicating type of transaction. Example: PPD = Business to consumer transaction CCD = Business to business
*Company Name	Text	16	Source of the entry or merchant name

Note: Transaction data included in the batch file must be in comma-delimited format with quoted text, as follows. Please remove any spaces before and after the comma delimiter.

Sample business to consumer transaction
Checking Account Sample: "Fees","27","123456789","123456","John Doe","1475","140.25","PPD","Company 1"
Savings Account Sample: "Fees","37","123456789","123456","John Doe","1475","140.25"," PPD ","Company 1"

Sample business to business transaction
Checking Account Sample: "Fees","27","123456789","123456","John Doe","1475","140.25","CCD","Company 1"
Savings Account Sample: "Fees","37","123456789","123456","John Doe","1475","140.25","CCD","Company 1"

File Naming Convention - The batch file should be saved with an .ach file extension using the following naming convention.

File Name	Description
YYMMDDNN.ACH	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 04111401.ach Year=2004, Month=11, Day=14 & Batch Number=01

Note: The batch number is required. This is used to differentiate between batch files when a merchant sends more than one batch on the same day. If only one batch file is sent for a particular date, the batch number will always be entered as 01.

Batch File - NACHA Format

The following guidelines shall be used for formatting transaction data sent in a NACHA formatted batch file.

File Header Record
No.	Field Name	Field Size	Field Content
1	Record Type	1	‘1’
2	Priority Code	2	Leave blank
3	Immediate Destination	10	Leave blank
4	Immediate Origin	10	Merchant name
5	Transmit/File Create Date	6	Leave blank
6	Transmit/File Create Time	4	Leave blank
7	File Id Modifier	1	Leave blank
8	Record Size	3	‘094’
9	Blocking Factor	2	‘10’
10	Format Code	1	‘1’
11	Destination Name	23	Leave blank
12	Origin Name	23	Leave blank
13	Reference Code	8	Leave blank

Batch Header Record
No.	Field Name	Field Size	Field Content
1	Record Type	1	‘5’
2	Service Class Code	3	Leave blank
3	Company Name	16	Merchant name
4	Company Discretionary Data	20	Discretionary Data
5	Company ID	10	Merchant ID
6	Standard Entry Class Code	3	PPD or CCD
7	Company Entry Description	10	Purpose of the transaction
8	Company Descriptive Date	6	Description Date
9	Effective Entry Date	6	Leave blank
10	Settlement Date (Julian)	3	‘1’
11	Originator Status Code	1	Leave blank
12	Originating DFI Identification	8	Leave blank
13	Batch Number	7	Batch Number

Entry Detail Record
No.	Field Name	Field Size	Field Content
1	Record Type	1	‘6’
2	Transaction Code	2	27= Debit CK, 37= Debit SA
3	Receiving DFI Identification	8	ABA Digits 1 to 8
4	Check Digit	1	ABA Digit 9
5	Account Number	17	Account Number (Checking or Savings)
6	Amount	10	Transaction Amount (No decimal point)
7	Individual Identification Number	15	Leave blank
8	Individual Name	22	Name on account (Checking or Savings)
9	Discretionary Data	2	Leave blank
10	Addenda Record Identification	1	‘1’ if there is addenda record
11	Trace Number	15	Unique reference number

Batch Footer Record
No.	Field Name	Field Size	Field Content
1		1	‘8’
2	Service Class Code	3	‘200’
3	Entry Addenda Count	6	Count of detail and addenda records
4	Entry Hash	10	Leave blank
5	Total Debit Amount	12	Sum of debit amount
6	Total Credit Amount	12	Sum of credit amount
7	Company Identification	10	Merchant ID
8	Message Authentication Code	19	Leave blank
9	Reserved	6	Leave blank
10	Originating DFI Identification	8	Leave blank
11	Batch Number	7	Batch Number

File Footer Record
No.	Field Name	Field Size	Field Content
1	Record Type	1	‘9’
2	Batch Count	6	Number of batches
3	Block Count	6	Leave blank
4	Entry Addenda Count	8	Count of detail records
5	Entry Hash	10	Leave blank
6	Total Debit Amount in File	12	Sum of debit amount in file
7	Total Credit Amount in File	12	Sum of credit amount in file
8	Reserved	39	Leave blank

Sample NACHA File:

File Naming Convention - The batch file should be saved with a .nac file extension using the following naming convention.

File Name	Description
YYMMDDNN.NAC	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 04111401.nac Year=2004, Month=11, Day=14 & Batch Number=01

Note: The batch number is required. This is used to differentiate between batch files when a merchant sends more than one batch on the same day. If only one batch file is sent for a particular date, the batch number will always be entered as 01.

Response Format

Response files are generated once a day, typically from 11:30 to 3 PM PST. Response file format is the same for both comma-delimited and NACHA batch file format.

Parameter	Type	Length	Description
RefID	Text	50	Merchant’s unique reference number
Amount	Numeric	8	Amount of sale
TransID	Numeric	10	Unique Key assigned by Paysafe
Reason	Text	100	Reject reason
Addenda Information	Text	100	Explanatory Information related to a reject

File Naming Convention - The response file will have an .rsp file extension using the following naming convention.

File Name	Description
YYMMDDNN.RSP	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 04111401.rsp Year=2004, Month=11, Day=14 & Batch Number=01



Sample response file
"113000","140.25","12345678","Declined","Voided Transaction"

Return File Format

Parameter	Type	Length	Description
RefID	Text	50	Merchant’s unique reference number
TransID	Numeric	10	Unique Key assigned by Paysafe
Amount	Numeric	8	Amount of sale
Return Code	Text	3	R01, R02, C01, etc.
Return Reason	Text	100	NSF, Account Close etc.
Account Type	Text	2	CK - Checking Account and SA - Savings Account
Trans Type	Text	2	27, 22, 37, 32
Corrected Account#	Text	17	Corrected checking or savings account number (ifapplicable)
Corrected Trans Route#	Text	9	Corrected routing number (if applicable)

File Naming Convention - The return file will have an .rtn file extension using the following naming convention.

File Name	Description
YYMMDDNN.RTN	YY = Year, MM = Month, DD = Day & NN = Batch No Example: 04111401.rtn Year=2004, Month=11, Day=14 & Batch Number=01



Sample Return file
"113000","12345678","40.25","R01","NSF","CK","27","122000661","123654789"

Customer Vault

AddCustomer

Description: Use this function to add a new customer record. Below are the parameters for this method.

Resource Url: https://webservice.paymentxp.com/wh/WebHost.aspx

Method: POST

Request