v1

latestSwagger 2.0Apache 2.02026-07-141430111.3 KB

payment-gateway

Authorize Transaction

Authorizes a credit card for capture at a later time. An authorized transaction will continue to be open until it expires or a capture message is received. Authorizations are automatically voided if they are not captured within 28 days, although most issuing banks will release the hold after 24 hours in retail environments or 7 days in card not present environments.

post/auth

Request body

amt_convenience_feenumber double

Format: Variable length, up to 8,2 N Description: Amount of convenience fee. A convenience fee is a fee charged to your customer for the "convenience" of being able to pay using an alternative payment channel outside your merchant's customary payment channel. Must be a flat/fixed fee amount per transaction. This field tracks the convenience fee amount for display purposes, but the amount of the fee must be included in amt_tran.

amt_fbonumber double

Format: Variable length, up to 12,2 N Description: Total amount of transaction to be transferred to the "for benefit of" (FBO) account.

amt_taxnumber double

Format: Variable length, up to 12,2 N Description: Amount of sales tax included in the total transaction amount. This field tracks the tax amount for display and interchange purposes, but the amount of the tax must be included in amt_tran. Conditional Requirement: Required for Level 2 and Level 3 interchange qualification.

amt_trannumber double

Format: Variable length, up to 12,2 N Description: Total amount of transaction including sales tax (amt_tax), convenience fee (amt_convenience_fee), and/or surcharge (amt_tran_fee) if applicable.

amt_tran_feenumber double

Format: Variable length, up to 8,2 N Description: Amount of transaction surcharge fee. A surcharge is a fee added to the cost of a purchase for the "privilege" of using a credit card instead of another form of payment, and can be a percentage of the transaction amount or fixed amount of up to 4% of amt_tran. This field tracks the surcharge amount of the transaction for display purposes, but the amount of the fee must be included in amt_tran.

auth_codestring

Format: Fixed length, 6 AN Description: This field should contain the 6-character authorization code that was received during a voice or Automated Response Unit(ARU) authorization for force request type. This is field is applicable to only force request type. Conditional Requirement: This field is required in force request type.

avs_addressstring

Format: Variable length, up to 20 AN Description: Street address of the cardholder. If present, it will be included in the authorization request sent to the issuing bank.

avs_zipstring

Format: Variable length, up to 9 AN Description: Zip code of the cardholder. If present, it will be included in the authorization request sent to the issuing bank. Conditional Requirement: This field is required if avs_address is present.

card_idstring

Format: Fixed length, 32 AN Description: Card ID received from a tokenization request. The card_id may be used in place of a card number or card swipe. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

card_numberstring

Format: Variable length, up to 19 N Description: Cardholder's card number. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

card_swipestring

Format: Variable length, up to 79 AN Description: Contains either track 1 or track 2 magnetic stripe data. If the magnetic stripe reader provides both track 1 and track 2 data in a single read, it is the responsibility of the implementer to send data for only one of the two tracks. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

cardholder_namestring

Format: Variable length, up to 64 AN Description: When provided in a tokenize request, the cardholder name will be stored in the Card Vault along with the cardholder card number and expiration date.

cavv_3dsstring

Format: Fixed length, 28 AN Description: Base 64 encoded CAVV returned from the merchant’s third-party 3-D Secure Merchant Plug-in (MPI). Use for Visa 3D Secure transactions.

client_ipstring

Format: Variable length AN Description: Client IP address.

customer_codestring

Format: Variable length, up to 17 AN Description: Reference code supplied by the cardholder to the merchant.

customer_emailstring

Format: Variable length Description: [Deprecated use email_address] Comma-separated list of e-mail addresses to which a receipt should be sent.

customer_idstring

Format: Variable length, up to 32 AN Description: Customer ID value established by the merchant. The customer_id may be used in place of a card number in requests requiring cardholder account data. When used with a card_id or card_number or card_swipe, the request will be tied to the customer_id in Qualpay reporting. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

cvv2string

Format: Variable length, up to 4 N Description: CVV2 or CID value from the signature panel on the back of the cardholder's card. If present during a request that requires authorization, the value will be sent to the issuer for validation.

dba_namestring

Format: Variable length, up to 21 AN Description: When the merchant has been authorized to send dynamic DBA information, this field will contain the DBA name used by Qulapay in the authorization and clearing messages. Note: the payment gateway will automatically add a prefix plus an asterisk () to the dba_name value. For example, if the prefix is ABC and the dba_name value is SHOE CO, the DBA name will show as "ABCSHOE CO" on the cardholder's credit card statement.

dba_suffixstring

Format: Fixed length, 9 AN Description: For use by merchants using negative option marketing. This field must be used in the first transaction at the conclusion of the free or reduced trial. This suffix will be appended to the end of your DBA and the result will appear on the cardholder statement. (If your DBA and suffix contain more that 25 characters, your DBA will be truncated.) Possible values are: <ul><li>END DSCNT</li><li>END OFFER</li><li>END PROMO</li><li>END TRIAL</li></ul>

dda_numberstring

Format: Variable length, up to 17 N Description: Owner's account number at the bank. Applicable for ACH payments. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

developer_idstring

Format: Variable length, up to 32 AN Description: Use to indicate which company developed the integration to Qualpay or the name of the payment solution that is connected to Qualpay. Suggested usage is softwareABCv1.0 or companyXYZv2.0.

duplicate_secondsinteger

Format: Variable length, up to 5 N Description: Duplicate transaction window in seconds. Qualpay will reject any transactions after a successful transaction within the duplicate_seconds window with a duplicate Account Number and optionally Purchase ID or, and, Merchant Reference Number. This value overrides any value set for a merchant on Qualpay Manager.

echo_fieldsstring

Format: Variable length Description: This field contains a JSON array of field data that will be echoed back in the response message.

email_addressstring[]

AN Description: An array of email addresses to which the transaction receipt should be sent to.

email_receiptboolean

Default: false Description: When this field is provided and set to true, a customer_email must also be provided. When these two fields are provided, a transaction receipt will be sent via e-mail to the address(es) provided in the customer_email field.

emv_tran_idstring

Format: Variable length, up to 36 AN Description: Base64 encoded MasterCard UCAF Transaction ID returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for MasterCard 3-D Secure transactions.

exp_datestring

Format: Fixed length, 4 N, MMYY format Description: Expiration date of cardholder card number. When card_id or customer_id is present in the request this field may also be present; if it is not, then the expiration date from the Card Vault will be used. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

fbo_idinteger

Format: Variable length, up to 16 N Description: For Benefit Of (FBO) merchant account identifier on the Qualpay system. Contact Qualpay customer support to obtain your FBO information.

line_itemsstring

Format: Variable length Description: JSON array of JSON objects. Each object represents a single line item detail element related to the transaction. Each detail element has required subfields: quantity (7N) description (26AN) unit_of_measure (12AN) product_code (12AN) - cannot be all zeroes debit_credit_ind (1 AN) unit_cost (12,2N) Optional subfields: type_of_supply (2AN) - visa only commodity_code - visa only(12AN) Conditional Requirement: This field is required for Level 3 interchange qualification.

loc_idstring

Format: Variable length, up to 4 N Description: When a merchant has more than one location using the same currency, this value is used to specify the specific location for this request.

mc_ucaf_datastring

Format: Variable length, up to 32 AN Description: Base64 encoded MasterCard UCAF Field Data returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for MasterCard 3-D Secure transactions.

mc_ucaf_indstring

Format: Fixed length, 1 AN Description: MasterCard UCAF Collection Indicator returned from the merchant’s third-party 3-D Secure Merchant Plug-in (MPI). Use for MasterCard 3-D Secure transactions.

merch_ref_numstring

Format: Variable length, up to 128 AN Description: Merchant provided reference value that will be stored with the transaction data and included with transaction data in reports within Qualpay Manager. This value will also be attached to any lifecycle transactions (e.g. retrieval requests and chargebacks) that may occur.

merchant_idinteger required

Format: Variable length, up to 12 N Description: Unique identifier on the Qualpay system.

moto_ecomm_indstring

Format: Fixed length, 1 N Default: 7 Description: Indicates type of MOTO transaction: <ul><li>0 = Card Present (not MOTO/e-Commerce)</li><li> 1 = One Time MOTO transaction</li><li>2 = Recurring </li><li>3 = Installment </li><li>5 = Full 3D-Secure transaction</li><li>6 = Merchant 3D-Secure transaction</li><li>7 = e-Commerce Channel Encrypted (SSL)</li></ul>

partial_authboolean

Default: false Description: This field must be present and set to a value of 'true' in order for the request to allow for approval of a partial amount. This would be used to allow a merchant to accept a partial payment from pre-paid or debit cards. When only part of the requested amount is available, the response code will be 010 and the amt_tran field in the response will contain the amount that was approved. A second sale request on a different card is needed to capture the remaining amount. Applicable to auth and sale request types.

payload_apple_paystring

Format: Variable length Description: Apple Pay payload

payload_google_paystring

Format: Variable length Description: Google Pay payload

pg_idstring

Format: Fixed length, 32 AN Description: PG ID of previously authorized transaction. This field is required when sending a capture, refund, or void request.

profile_idstring

Format: Fixed length, 20 N Description: Explicitly identifies which Payment Gateway profile should be used for the request.

purchase_idstring

Format: Variable length, up to 25 AN Description: Purchase Identifier (also referred to as the invoice number generated by the merchant). Conditional Requirement: This field is required for Level 2 and Level 3 interchange qualification.

report_datastring

Format: Variable length Description: This field contains a JSON array of field data that will be included with the transaction data reported in Qualpay Manager.

retry_attemptinteger

Format: Variable length, up to 4 N Description: This field contains a number greater than zero (0). When the value is one (1), the payment gateway treats the message as a new message. If the value is greater than one (1), then the payment gateway will return the result of the original message. If the original message did not complete, the payment gateway treats the message as a new message. Conditional Requirement: This field is required when the retry_id is present in the request message.

retry_idinteger

Format: Variable length, up to 15 N Description: This field contains a merchant generated number used to identify the request. This value must be unique within the last 24 hours. When present, the payment gateway will use the retry_attempt to determine whether the message is new or a retry of a previous message.

session_idstring

INTERNAL USE ONLY.

subscription_idinteger

Format: Variable length, up to 10 N Description: Identifies the recurring subscription that applies to this transaction.

tokenizeboolean

Default: false Description: In an authorization, credit, force, sale, or verify request the merchant can set tokenize to "true" and the payment gateway will store the cardholder data in the Card Vault and provide a card_id in the response. If the card_number or card_id in the request is already in the Card Vault, this flag instructs the payment gateway to update the associated data (e.g. avs_address, avs_zip, exp_date) if present. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

tr_numberstring

Format: Fixed length, 9 N Description: Bank transit/routing number. Applicable for ACH payments. Conditional Requirement: Refer to <a href="/developer/api/reference#card-source-conditional-requirements"target="_blank">Card or Bank Account Data Sources and Conditional Requirements</a>

tran_currencyinteger

Format: Fixed length, 3 N Default: 840 Description: ISO numeric currency code for the transaction. Refer to <a href="/developer/api/reference#country-codes"target="_blank">Country Codes</a> for a list of currency codes.

type_idstring

Format: Fixed length, 1 AN Default: C Description: Bank Account Type. Applicable for ACH payments. Possible values are: <ul><li>C = Personal checking account</li><li>S = Personal savings account</li><li>K = Business checking account</li><li>V = Business savings account</li></ul>

user_idinteger

INTERNAL USE ONLY.

vendor_idinteger

Format: Variable length, up to 12 N Description: Identifies the vendor to which this capture request applies.

xid_3dsstring

Format: Fixed length, 28 AN Description: Base64 encoded transaction ID (XID) returned from the merchant’s third-party 3D Secure Merchant Plug-in (MPI). Use for Visa 3-D Secure transactions.

Example request

{
  "amt_convenience_fee": 2,
  "amt_fbo": 1.5,
  "amt_tax": 93.5,
  "amt_tran": 1193.5,
  "amt_tran_fee": 2.35,
  "auth_code": "620376",
  "avs_address": "123 Main St",
  "avs_zip": "94402",
  "card_id": "86e1b00d9b0811e68df3069d8f743581",
  "card_number": "4111111111111111",
  "card_swipe": ";4111111111111111=08051010912345678901?8",
  "cardholder_name": "JOHN CUSTOMER",
  "cavv_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k=",
  "client_ip": "10.1.1.4",
  "customer": {
    "billing_addr1": "123 Main Street",
    "billing_addr2": "Suite #1234",
    "billing_city": "San Mateo",
    "billing_country": "USA",
    "billing_country_code": "840",
    "billing_state": "CA",
    "billing_zip": "94402",
    "billing_zip4": "1234",
    "customer_email": "jsmith@somewhere.com",
    "customer_firm_name": "Qualpay",
    "customer_first_name": "Joe",
    "customer_last_name": "Smith",
    "customer_phone": "6503885200",
    "shipping_addresses": [
      {
        "primary": true,
        "shipping_addr1": "1234 Main Street",
        "shipping_addr2": "Ste 123",
        "shipping_city": "San Mateo",
        "shipping_country": "USA",
        "shipping_country_code": "840",
        "shipping_firm_name": "Qualpay",
        "shipping_first_name": "Joe",
        "shipping_last_name": "Smith",
        "shipping_state": "CA",
        "shipping_zip": "94402",
        "shipping_zip4": "1234"
      }
    ]
  },
  "customer_code": "PO # abc123",
  "customer_email": "testme@qualpay.com",
  "customer_id": "JOECUSTOMER_12",
  "cvv2": "152",
  "dba_name": "SHOE CO",
  "dba_suffix": "END PROMO",
  "dda_number": "3456776866",
  "developer_id": "QualpayV1.2",
  "duplicate_seconds": 300,
  "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
  "email_address": [
    "jdoe@qualpay.com",
    "john.doe@qualpay.com"
  ],
  "email_receipt": true,
  "emv_tran_id": "ASNFZ4nwEjR1We3I85BI70V9nifASNFZ4jwHyL0U=",
  "exp_date": "0921",
  "fbo_id": 999000000001,
  "line_items": "[{\"quantity\": \"1\",\"description\": \"Traffic Cones\", \"unit_of_measure\": \"each\", \"product_code\": \"SKU-123\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"14.99\"},{\"quantity\": \"3\", \"description\": \"Spray Paint\", \"unit_of_measure\": \"EA\", \"product_code\": \"SKU-456\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"5.00\"}]",
  "loc_id": "0001",
  "mc_ucaf_data": "ASNFZ4nwEjRWeI8BI0VnifASNFZ4jwHyL0U=",
  "mc_ucaf_ind": "2",
  "merch_ref_num": "ITEM 16126 Purchased 12-15-2016",
  "moto_ecomm_ind": "1",
  "partial_auth": true,
  "payload_apple_pay": "xxxxxxx",
  "payload_google_pay": "xxxxxxx",
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
  "profile_id": "21200001000300000978",
  "purchase_id": "55-1212",
  "report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]",
  "retry_attempt": 1,
  "retry_id": 1234,
  "subscription_id": 1234,
  "tokenize": true,
  "tr_number": "011111111",
  "tran_currency": 840,
  "type_id": "S",
  "vendor_id": 212100026512,
  "xid_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k="
}

Response

Success

amt_trannumber double

Format: Variable length, up to 12,2 N Description: Transaction amount, returned only on partial approvals.

auth_avs_resultstring

Format: Fixed length, 1 AN Description: AVS result from card issuer (if avs_zip and optionally avs_address were provided in the request). Refer to <a href="/developer/api/reference#avs-result-codes"target="_blank">Payment Result Codes for AVS</a> for possible values.

auth_codestring

Format: Fixed length, 6 AN Description: Card issuer authorization code returned on successful authorization request.

auth_cvv2_resultstring

Format: Fixed length, 1 AN Description: CVV2 result from card issuer (if CVV2 data was sent in the request). Refer to <a href="/developer/api/reference#cvv2-result-codes"target="_blank">Payment Result Codes for CVV2</a> for possible values.

card_idstring

Format: Fixed length, 32 AN Description: 32-byte value returned after successful tokenize request or when an authorization or sale transaction requests tokenization of the cardholder data.

echo_fieldsstring

Format: Variable length Description: Data that was provided in echo_fields in the request.

merchant_advice_codestring

Format: Fixed length, 4 AN Description: Recurring transaction advice for MasterCard authorizations.<ul><li>M001 = New account information available</li><li>M002 = Try again later</li><li>M003 = Do not try again for recurring payments transaction</li><li>M004 = Token requirements not fulfilled for this token type</li><li>M021 = Recurring payment cancellation</li></ul>

pg_idstring

Format: Fixed length, 32 AN Description: 32-byte unique identifier generated by the payment gateway, returned in all valid responses.

rcodestring

Format: Fixed length, 3 AN Description: Response code from the payment gateway. "000" indicates success. Refer to <a href="/developer/api/reference#api-response-codes"target="_blank">Platform API Response Codes</a> for entire list of Payment Gateway Response Codes.

rmsgstring

Format: Variable length Description: Response text from the payment gateway.

Example response

{
  "amt_tran": 62.87,
  "auth_avs_result": "X",
  "auth_code": "T37500",
  "auth_cvv2_result": "M",
  "card_id": "86e1b00d9b0811e68df3069d8f743581",
  "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
  "merchant_advice_code": "M001",
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
  "rcode": "000",
  "rmsg": "Approved T37500"
}