openapi: 3.2.0
info:
title: purchases-api Issue Card API
version: '1.0'
servers:
- url: https://sandboxpurchasesapi.connexpay.com
security:
- sec0: []
tags:
- name: IssueCard
paths:
/api/v1/IssueCard:
post:
summary: Issue Card
description: Use this endpoint to issue virtual cards associated with a credit or ACH sale. Do not use this endpoint if you fund your virtual cards from cash and therefore don't have an associated sale. If you aren't sure which Issuance API to use, please contact your client support representative.
operationId: issuecard
parameters:
- name: Content-Type
in: header
description: '"application/json"'
schema:
type: string
- name: Authorization
in: header
description: 'Token. Eg: "Bearer eHSN5rTBzqDozgAAlN1UlTMVuIT1zSiAZWCo6E..."'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- MerchantGuid
- FirstName
- AmountLimit
- PurchaseType
- LastName
properties:
MerchantGuid:
type: string
description: Merchant's Guid. Application-level value that indicates a virtual card is being requested for client's account. Value provided by ConnexPay.
FirstName:
type: string
description: Cardholder's first name. This is the first name placed on the virtual card provided to the supplier. The value is also searchable in the ConnexPay portal. The maximum length is 50 characters.
LastName:
type: string
description: Cardholder's last name. This is the last name placed on the virtual card provided to the supplier. The value is also searchable in the ConnexPay portal. The maximum length is 50 characters.
Phone:
type: string
description: Cardholder's phone number. Phone number up to 20 character string, numbers and plus sign (+) allowed only. Telephone number of the user (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.
Address1:
type: string
description: Cardholder's address line 1. The street number is used by the supplier when submitting the transaction to perform an AVS check. Alphanumerics and [,.-'] are allowed.
Address2:
type: string
description: Cardholder's address line 2. Alphanumerics and [,.-'] are allowed.
City:
type: string
description: Cardholder's city.
State:
type: string
description: Cardholder's short name state. The ISO 3166-2 CA and US state or province code of a user. Length = 2. If a non U.S. or Canadian value is submitted the virtual card request will not be processed and an error response returned.
ZipCode:
type: string
description: Cardholder's zipcode. The zip code is used by the supplier when submitting the transaction to perform an AVS check. The Zipcode must be between 1 and 10 characters long, only numbers and letters are allowed.
Country:
type: string
description: Cardholder's country. Only alpha-2 digit country code allowed and numbers are not allowed. See ISO-3166 country list of Alpha-2 country codes (https://www.iso.org/obp/ui/) .
CurrencyCode:
type: string
description: Do not use without consulting with your CXP resources for applicable use. Default is your Accounting Currency if left blank/unprovided. Currency of the stored balance of the issued virtual card.
Region:
type: string
description: Do not use without consulting with your CXP resources for applicable use. Default is your Accounting Region if left blank/unprovided. Where (region/bank) the virtual card is issued from.
UsageLimit:
type: integer
description: 'Security Control: Maximum number of times the card may be authorized. The maximum allowed field value is 99, and if you do not provide a value the card will be considered unlimited. The exception to this are UATP cards, which have a maximum allowed value of 9999 and will default to that max if no value is provided.
Authorization attempts exceeding the provided value will be declined. Even though a virtual card is often considered a “one-time-use” card, some suppliers may need to authorize a card multiple times (pre-authorizations, a purchase comprised of multiple tickets, etc.) and you may consider a value that is not overly restrictive to avoid unwanted declines.'
format: int64
AmountLimit:
type: number
description: 'Security Control: Maximum dollar amount the card can be authorized and settled, which must be less than or equal to $4,999,999.99 ($1,200,000.00 CAD for Canadian Issuing clients). The value must incorporate any anticipated overages such as currency conversion or taxes that a supplier may associate with the transaction. If a supplier attempts to authorize a card for more than the amount limit it will be declined.'
format: float
ExpirationDate:
type: string
description: The ExpirationDate (YYYY-MM-DD) is the date to be provided to the supplier as the actual expiration date for the virtual card. The recommendation is to set the ExpirationDate one or two years in the future and set the TerminateDate just a day or two after the VCC is expected to be processed to avoid acceptance issues. The expiration date cannot be more than 48 months in the future. If an expiration date is not provided, the expiration will default to issue date plus three years. For cards issued outside of the US/Canada, the expiration date will default to issue date plus three years and can not be overwritten - even if this parameter is included in the request. Note, Returns can still be processed on expired or terminated VCCs.
format: date
TerminateDate:
type: string
description: The TerminateDate (YYYY-MM-DD format) is the date the Virtual Credit Card will be terminated by ConnexPay. TerminateDate is different than ExpirationDate in that TerminateDate indicates the actual date the card will no longer be active. The recommendation is to set the ExpirationDate one or two years in the future and set the TerminateDate just a day or two after the VCC is expected to be processed. If a terminate date is not indicated, the card will be inactivated as of the expiration date. Note, Returns can still be processed on terminated VCCs and UATP termination dates cannot exceed 12 months.
format: date
PurchaseType:
type: string
description: 'Security Control: The industry(s) where a virtual card can be used. For example, if value is set to 01 Airline and the card is attempted to be used at a hotel, it will decline. Allowed purchase types are decided during underwriting. Ask a ConnexPay team member for Purchase Types enabled on your account. Best Practice is to always assign a Purchase Type that is restrictive as possible.'
SequenceNumber:
type: string
description: 'Transaction sequence number within client environment. Note: value is not searchable or reportable in ConnexPay portal. The maximum length is 100 alpha-numeric characters.'
OrderNumber:
type: string
description: 'A value that is commonly used for reporting on and reconciling your PayIns and PayOuts. The Order Number is searchable in the ConnexPay Bridge and referenced in Analytics and reporting, and can be any identifier within your environment to associate with the sale or payment, such as a Record Locator, PNR, or transaction ID. The maximum length is 50 alpha-numeric characters and allows the following special characters: [._ /- ].'
default: ''
IncomingTransactionCode:
type: string
description: ITC for short Application level setting to associate the virtual card request with an original sale or sale group. The value is provided in the sale response of the original sale transaction, or in the Group Sale response of the group sale. All virtual card requests must be associated with an original sale or group transaction.
PayeeId:
type: string
description: The PayeeId is used to assist with Intelligent Routing functionality. This field was previously labeled as the Supplier ID and serves the same purpose for Intelligent Routing; however, it also supports additional functionality if a Payee has been created. Creating a Payee allows you complete control over the type of virtual card used to pay your payee and minimizes the data that must be passed in each card request. The field accepts up to 100 alpha-numeric characters, special characters, and spaces. Reference our MerchantPayees APIs for additional details.
PayorId:
type: string
description: An optional field used to tie the PayOut to a created Payor. This may assist with reconciling when using multiple bank accounts for funding your cash balance.
NonDomesticSupplier:
type: boolean
description: We can issue the “Global VCC” if the Supplier accepting that VCC has an overseas merchant account. This is an optional field. Indicating true will result in issuing this Global VCC. Indicating false (or not including this property in your request) will result in receiving a VCC created for domestic use.
Transmission:
type: object
description: URL Links (email) or a text document (fax) to virtual cards can be emailed/faxed by including the VCC Transmission object in the IssueCard API call. Including the transmission object for email also allows you to pull back a URL you can use within your application to direct a user to a visual representation of the virtual card.
properties:
TransmissionMethods:
type: array
description: 'Methods of Transmission. Supported methods: Email, Link, Fax. Populate this parameter as ''Email'' if you want to email the virtual card to a customer or supplier. Use the ''Link'' option to have a URL included in the response. Use the "Fax" option to fax the virtual card to a customer or supplier.'
items:
type: string
EmailRecipient:
type: string
description: Mandatory for email transmission. The email address of the intended recipient. 255 char max.
MerchantPhoneNumber:
type: string
description: This is the phone number that should display on the virtual card and is the number that should be used if the link has expired. Up to 15 characters. Numbers and plus sign (+) allowed only.
EmailFrom:
type: string
description: Mandatory for email transmission. This will be the email address that populates the ‘reply to’ section of the email message. 255 char max.
RecipientName:
type: string
description: Mandatory for email or fax transmission. A descriptive name of the email or fax recipient. 255 char max
Subject:
type: string
description: Mandatory for email (unless using an existing template and the EmailTemplateName is provided) or fax transmission. High-level subject line description of the transmission contents. 255 char max.
Message:
type: string
description: Mandatory for email (unless using an existing template and the EmailTemplateName is provided) or fax transmission. The message body of the email or fax. 2048 char max.
DaysToExpire:
type: string
description: 'Mandatory for email transmission. The number of days after card issuance until link to VC expires. Range: 1-999 days.'
EmailTemplateName:
type: string
description: Use a previously created custom email template by referring to the defined template name. 500 character max.
FaxFrom:
type: string
description: Mandatory for fax transmission. This can be the client name or fax number the fax is coming from that populates the ‘FaxFrom’ section of the fax. 255 char max.
FaxRecipient:
type: string
description: Mandatory for fax transmissions. The fax number of the intended recipient.
BookingDetail:
type: object
properties:
ArrivalDate:
type: string
description: Guest arrival date in YYYY-MM-DD format.
format: date
PaymentInstruction:
type: string
description: Instructions for payment processing. System automatically appends "This is a virtual credit card". Maximum length of 4000 characters.
ReferenceNumber:
type: string
description: Booking reference number for tracking. This should match the booking confirmation number in the hotel’s property management system. Maximum length of 100 characters.
Traveler:
type: object
properties:
FirstName:
type: string
description: Traveler's first name. Maximum length of 100 characters.
LastName:
type: string
description: Traveler's last name. Maximum length of 100 characters.
description: Traveler information.
Company:
type: object
description: Company information for the company paying for the charges.
properties:
Name:
type: string
description: Company Name. Maximum length of 200 characters.
Address1:
type: string
description: Primary company address line. Maximum length of 100 characters.
Address2:
type: string
description: Secondary company address line. Maximum length of 100 characters.
City:
type: string
description: Company city. Maximum length of 100 characters.
State:
type: string
description: Company state/province. Maximum length of 50 characters.
Zipcode:
type: string
description: Company postal/ZIP code. Maximum length of 20 characters.
Country:
type: string
description: Company country. Maximum length of 100 characters.
Contact:
type: object
properties:
PhoneNumber:
type: string
description: The phone number of the company that will be paying for the charges. Maximum of 20 characters.
EmailAddress:
type: string
description: Primary contact email address of the company that will be paying for the charges. Maximum of 255 characters.
InvoiceEmailAddress:
type: string
description: Invoice/billing email address. Maximum of 255 characters.
required:
- EmailAddress
description: Contact information for the company that will be paying for the charges.
Property:
type: object
properties:
GDSCode:
type: string
description: Hotel property GDS (Global Distribution System) code. Maximum of 50 characters
Address1:
type: string
description: Primary property address line. Maximum of 100 characters.
Address2:
type: string
description: Secondary property address line. Maximum of 100 characters.
City:
type: string
description: Property city. Maximum of 100 characters.
State:
type: string
description: Property state/province. Maximum of 50 characters.
Zipcode:
type: string
description: Property postal/ZIP code. Maximum of 20 characters.
Country:
type: string
description: Property country. Maximum of 100 characters.
description: Hotel property information.
required:
- GDSCode
description: Optional component that enables automated hotel booking authorization through the Sertifi platform when a virtual card is issued. When provided, the system will attempt to create a booking authorization with the hotel property using the card details. Contact your ConnexPay representative before use as fees will be applied and configuration is required.
required:
- ArrivalDate
- PaymentInstruction
- ReferenceNumber
ReturnCardData:
type: boolean
description: Optional field that may be set to true or false. When set to a value of true or if the field is not provided at all, card data is returned in the response. When set to a value of false, the Card Account Number and Security Code (CVV) will be excluded from the response.
CustomerID:
type: string
description: 'Transaction ID within client environment associated with the customer. This value acts as a secondary identifier in conjunction with OrderNumber. The value is searchable and reportable in the ConnexPay portal. This value may be sent in multiple times within the integration for multiple purposes. The maximum length is 100 alphanumeric characters and the following special characters: [@._/-].'
AssociationId:
type: string
description: 'Utilize the Association ID field to tie a virtual card to a sale or sales. For example, if you have several sales and one virtual card payment to a supplier, you can add association ID to the sales and the virtual card for downstream reporting. The maximum length is 100 alpha-numeric characters and the following special characters: [@._/-].'
LabelIDs:
type: array
description: Utilize Label IDs to associate a virtual card to a specific label(s) within ConnexPay Bridge UI for your organization. If a virtual card is tied to an incorrect Label, it will not filter or display correctly in Bridge's Search Grid. Please contact your Customer Care Consultant for a list of valid Label IDs before use.
items:
type: string
UserDefinedParameters:
type: array
description: You can add User Defined Parameters to your PayOut in the event that you need to associate or display additional information.
items:
properties:
Name:
type: string
description: Name of the User Defined Parameter.
Value:
type: string
description: 'Value for the named User Defined Parameter, in a format consistent with the defined DataType. If the User Defined Parameter is of Data Type String, the value is constrained by the defined Maximum Length and alphanumerics and special characters are allowed. If the User Defined Parameter is of Data Type DateTime, the formats accepted are ISO 8601 Formats (example: YYYY-MM-DD:HH:mm:ss), MM/DD/YYYY, and DD/MM/YYYY.'
type: object
EnableExactMatch:
type: boolean
default: 'false'
description: 'Restrict the issued single use virtual card to only allow authorization approvals when the request amount is an exact match to the created amount limit. This functionality is only applicable when the currency is USD and the Region is US. A default value may be configured for your client account that will be used automatically when not provided in the request, however the explicit value provided in a request call will override this. Please reach out to your ConnexPay representative to enable before usage. Note: When the card brand is UATP, Exact Match will be enforced as false by the CXP system.'
WhitelistCountries:
type: array
items:
type: integer
description: Specify the countries where the card may be successfully authorized. The Country Code ID or IDs must be used, which can be found at https://docs.connexpay.com/docs/country-code-ids. A country that is restricted by ConnexPay cannot be whitelisted, and that list can be found at https://docs.connexpay.com/docs/blacklisted-countries-of-vcc-acceptance. You may only specify a whitelist or blacklist, not both.
BlacklistCountries:
type: array
items:
type: integer
description: Specify the countries where the card may not be successfully authorized. The Country Code ID or IDs must be used, which can be found at https://docs.connexpay.com/docs/country-code-ids. You may only specify a whitelist or blacklist, not both.
avsCheck:
type: boolean
description: 'Optional field that will default to your client-level setting if not provided. If enabled, Address Line 1 and Zip Code must be provided. '
examples:
Issue Card Request Example - Booking Detail:
value:
MerchantGuid: 2b586234-7f14-432e-b0f4-a2935f783f38
FirstName: M
LastName: Smith
Phone: '5551234567'
Address1: 123 Main Street
Address2: Suite 100
City: New York
State: NY
Zipcode: '10001'
Country: US
UsageLimit: 10
AmountLimit: 180
ExpirationDate: '2026-12-30'
TerminateDate: '2026-12-30'
PurchaseType: '01'
SequenceNumber: Sample-seq-1
IncomingTransactionCode: 035U9MGQ5KF3XQAZQ00050000
NonDomesticSupplier: false
OrderNumber: OrderNumber-1
CustomerID: CustomerID-1
PayeeId: AA
Transmission:
TransmissionMethods:
- Email
- Fax
EmailRecipient: m.smith@example.com
MerchantPhoneNumber: '5551234567'
EmailFrom: noreply@example.com
RecipientName: Smith
Subject: Card Information
Message: here is your card information...
DaysToExpire: 1
FaxRecipient: '+15551234567'
FaxFrom: Example Corporation
BookingDetail:
ArrivalDate: '2025-12-01'
PaymentInstruction: Payment for hotel accommodation - This is a virtual credit card
ReferenceNumber: REF123456789
Traveler:
FirstName: M
LastName: Smith
Company:
Name: Example Corporation
Address1: 123 Main Street
Address2: Suite 100
City: New York
State: NY
Zipcode: '10001'
Country: US
Contact:
PhoneNumber: +1-555-123-4567
EmailAddress: m.smith@example.com
InvoiceEmailAddress: billing@example.com
Property:
GDSCode: HTL001
Address1: 456 Hotel Boulevard
Address2: Floor 1
City: Las Vegas
State: NV
Zipcode: '89101'
Country: US
summary: Issue Card Request Example - Booking Detail
Issue Card Request Example:
summary: Issue Card Request Example
value:
MerchantGuid: 2b586234-7f14-432e-b0f4-a2935f783f38
FirstName: M
LastName: Smith
Phone: '5551234567'
Address1: 123 Main Street
Address2: Suite 100
City: New York
State: NY
Zipcode: '10001'
Country: US
UsageLimit: 10
AmountLimit: 180
ExpirationDate: '2027-12-30'
TerminateDate: '2026-12-30'
PurchaseType: '01'
SequenceNumber: Sample-seq-1
IncomingTransactionCode: 035U9MGQ5KF3XQAZQ00050000
NonDomesticSupplier: false
OrderNumber: OrderNumber-1
CustomerID: CustomerID-1
PayeeId: AA
Transmission:
TransmissionMethods:
- Email
- Fax
EmailRecipient: m.smith@example.com
MerchantPhoneNumber: '5551234567'
EmailFrom: noreply@example.com
RecipientName: Smith
Subject: Card Information
Message: here is your card information...
DaysToExpire: 1
FaxRecipient: '+15551234567'
FaxFrom: Example Corporation
responses:
'200':
description: '200'
content:
application/json: {}
'201':
content:
application/json:
schema:
type: object
properties: {}
examples:
Issue Card Response:
summary: Issue Card Response
value:
cardHolder:
cardHolderGuid: a2b25172-c863-4325-b3b9-7e33cff2f8d1
firstName: Adam
lastName: Smith
phone: '7411237489'
address1: 345 Main Road
address2: ''
city: Miami Beach
state: MI
zipcode: '33109'
country: MX
createNewCard: false
reissuePhysicalCard: false
card:
cardGuid: ae17f687-8ba7-4502-b627-24fdf5e6f218
accountNumber: '1111118971563394'
securityCode: '617'
amountLimit: 1
usageLimit: 12
limitWindow: LIFETIME
expirationDate: '2026-12-30T18:59:59'
expiration: '1219'
terminateDate: '2026-12-30T23:59:59'
currencyCode: USD
firstSix: '111111'
lastFour: '3394'
nameLine1: Adam
nameLine2: Smith
status: Card - Active
customerServicePhoneNumber: 1-612-601-0914
sequenceNumber: Sample-seq-1
midWhitelist: []
midBlacklist: []
associationId: 'null'
gatewayMerchantGuid: 3b47973a-b0c1-4bcd-ba34-1514526d99cd
availableBalance: 1
isPhysical: false
isLodged: false
fingerprint: 941A49226BB191C7B623268B22C94300
customerId: null
supplierId: AA
issuerId: 3
country: ''
cardBin: '44325235'
cardClass: CommercialPrepaid
toleranceAmount: null
isGLobal: false
hasBooking: false
cardHolder: null
outgoingTransactionCode: null
createdBy: null
isMaestro: false
whitelistCountries: null
blacklistCountries: null
enableExactMatch: false
avsCheck: false
cardImageKey: null
labelIds:
- 889
- 992
cardBrand: MasterCard
cardClass: Commercial
saleGuid: d49e4881-34e5-461f-9d43-0efb0d94039d
incomingTransactionCode: '6560027639095375972800239'
Issue Card Response (ReturnCardData = false):
summary: Issue Card Response (ReturnCardData = false)
value: "{\n \"cardHolder\": {\n \"cardHolderGuid\": \"a2b25172-c863-4325-b3b9-7e33cff2f8d1\",\n \"firstName\": \"Adam\",\n \"lastName\": \"Smith\",\n \"phone\": \"7411237489\",\n \"address1\": \"345 Main Road\",\n \"address2\": \"\",\n \"city\": \"Miami Beach\",\n \"state\": \"MI\",\n \"zipcode\": \"33109\",\n \"dateOfBirth\": null,\n \"country\": \"U\",\n \"createNewCard\": false,\n \"reissuePhysicalCard\": false\n },\n \"card\": {\n \"cardGuid\": \"ae17f687-8ba7-4502-b627-24fdf5e6f218\",\n \"amountLimit\": 180,\n \"usageLimit\": 10,\n \"limitWindow\": \"LIFETIME\",\n \"expirationDate\": \"2026-12-30T18:59:59\",\n \"expiration\": \"1224\",\n \"terminateDate\": \"2026-12-30T23:59:59\",\n \"currencyCode\": \"USD\",\n \"firstSix\": \"111111\",\n \"lastFour\": \"3394\",\n \"nameLine1\": \"Adam\",\n \"nameLine2\": \"Smith\",\n \"status\": \"Card - Active\",\n \"customerServicePhoneNumber\": \"1-612-601-0914\",\n \"sequenceNumber\": \"Sample-seq-1\",\n \"midWhitelist\": [],\n \"midBlacklist\": [],\n \"gatewayMerchantGuid\": \"2b586234-7f14-432e-b0f4-a2935f783f38\",\n \"availableBalance\": 180,\n \"isPhysical\": false,\n \"isLodged\": false,\n \"fingerprint\": \"23C69076A2C917DDA5ED1B83A1629626\",\n \"customerId\": null,\n \"payeeId\": null,\n \"issuerId\": 3,\n
# --- truncated at 32 KB (232 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/connexpay/refs/heads/main/openapi/connexpay-issuecard-api-openapi.yml