API Reference
Login to SandboxCreate Account
Start typing to search…

Authorize Transaction

post
https://api-test.qualpay.com/pg/auth

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.

Note: Vendor accounts need special permissions to use this operation; contact Qualpay Support to enable it.

Body Params

Payment Gateway Authorization Request

int64
required

Format: Variable length, up to 12 N
Description: Unique identifier in our system.

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.

string

Format: Fixed length, 32 AN
Description: Card ID received from a tokenization request. This may be used in place of a card number or card swipe.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

string

Format: Variable length, up to 19 N
Description: Cardholder's card number.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

string

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 Card or Bank Account Data Sources and Conditional Requirements

string

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 our reporting.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

string

Format: Fixed length, 4 N, MMYY format
Description: Expiration date of cardholder's card number. When card_id or customer_id is present in the request, this field may also be present. If this field is not present, the tokenized expiration date is used.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

string

Format: Fixed length, 9 N
Description: Bank transit/routing number. Applicable for ACH payments.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

string

Format: Variable length, up to 17 N
Description: Owner's account number at the bank. Applicable for ACH payments.
Conditional Requirement: Refer to Card or Bank Account Data Sources and Conditional Requirements

boolean

Default: false
Description: In an authorization, credit, force, sale, or verify request, the merchant can set tokenize to true. The payment gateway then stores the cardholder data and provides a card_id in the response. If the card_number or card_id in the request is already tokenized, 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 Card or Bank Account Data Sources and Conditional Requirements

double

Format: Variable length, up to 8,2 N
Description: Amount of convenience fee. A convenience fee is a flat/fixed fee charged to your customer for the privilege of paying for a product or service using a non-standard method of payment. This field tracks the convenience fee amount for display purposes, but the amount of the fee must be included in amt_tran.

double

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

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.

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. It can be a percentage of the transaction amount or a 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.

string

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

string

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.

string

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.

string

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

string

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.

string

Format: Variable length AN
Description: The cardholder's IP address.

customer
object

Description: In an authorization, credit, force, sale, or verify, the payment gateway stores customer data when the merchant sends the following:

  • tokenize (set to true),
  • either card_number or card_swipe,
  • the desired customer_id, and
  • the customer field.

Cannot be used to update an existing customer_id.

string

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

string

Format: Variable length
Description: [This is a deprecated field. Use email_address.] Comma-separated list of e-mail addresses to which a receipt should be sent.

string

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.

string

Format: Variable length, up to 21 AN
Description: When the merchant has been authorized to send dynamic ‘Doing Business As’ information, this field will contain the DBA name used in authorization and clearing messages.
Note: The payment gateway automatically adds a prefix plus an asterisk to the dba_name value on the cardholder's credit card statement.

string

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:

  • END DSCNT
  • END OFFER
  • END PROMO
  • END TRIAL

string

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

int64

Format: Variable length, up to 5 N
Description: Duplicate transaction window in seconds. If one transaction succeeds, and an additional transaction with the same account number occurs within the duplicate_seconds window of the first transaction, we reject the additional transaction. Optionally, we can also reject such a transaction that has a duplicate purchase_id and/or merchant_id. This value overrides any value set for a merchant in the Merchant Manager portal.

string

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

email_address
array of strings

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

email_address
boolean

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 email to the address(es) provided in the customer_email field.

string

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.

int64

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

string

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 the following required subfields:

  • quantity (7 N)
  • description (26 AN)
  • unit_of_measure (12 AN)
  • product_code (12 AN, cannot be all 0s)
  • debit_credit_ind (1 AN)
  • unit_cost (12,2 N)

Each has these optional subfields:

  • type_of_supply (2 AN) - Visa only
  • commodity_code (12 AN) - Visa only

Conditional Requirement: This field is required for Level 3 interchange qualification.

string

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 location for this request.

string

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.

string

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.

string

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

string

Format: Fixed length, 1 N
Default: 7
Description: Indicates the type of MOTO transaction. Possible values:

  • 0 - Card present (not MOTO/e-commerce)
  • 1 - One-time MOTO transaction
  • 2 - Recurring
  • 3 - Installment
  • 7 - E-commerce channel encrypted (SSL)

Conditional Requirement: Recurring transactions require moto_ecomm_ind set to 2.

boolean

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 prepaid 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.

string

Format: Variable length
Description: Apple Pay payload.

string

Format: Variable length
Description: Google Pay payload.

string

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

string

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

string

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.

string

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

string

INTERNAL USE ONLY.

int64

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

int32

Format: Fixed length, 3 N
Default: 840
Description: The ISO numeric currency code for the transaction. This must be a currency code associated with one of your payment profiles; contact Qualpay to add currencies. Refer to Currency Codes for a list of currency codes.

string

Format: Fixed length, 1 AN
Default: C
Description: Bank account type. Applicable for ACH payments. Possible values:

  • C = Personal checking account
  • S = Personal savings account
  • K = Business checking account
  • V = Business savings account

int64

INTERNAL USE ONLY.

int64

Format: Fixed length, 10 N
Description: Identifies the vendor to which this request applies.
Conditional Requirement: This field is required for Qualpay partner accounts.

string

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.

boolean

INTERNAL USE ONLY.

Responses

Updated 6 months ago

Language
Credentials
Basic
base64
:
URL
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 6 months ago