openapi: 3.2.0
info:
title: purchases-api IssueCard (COPY) IssueCard (COPY) API
version: '1.0'
servers:
- url: https://sandboxpurchasesapi.connexpay.com
security:
- sec0: []
tags:
- name: IssueCard (COPY)
paths:
/api/v1/IssueCard (COPY):
post:
summary: Issue Card (COPY)
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 therefor don't have an associated sale. If you aren't sure which Issuance API to use, please contact your client support representative.
operationId: issue-card-copy
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
- LastName
- AmountLimit
- PurchaseType
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.
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.
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/) .
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. 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 $5,000,000.00. 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 36 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.
format: date
currencyCode:
type: string
description: Currency of the stored balance of the issued virtual card. If left blank or unprovided, the default is your Accounting Currency. See https://docs.connexpay.com/reference/currency-and-region-codes for valid codes.
region:
type: string
description: Where (region/bank) the virtual card is issued from. If left blank or unprovided, the default is your Accounting Region. See https://docs.connexpay.com/reference/currency-and-region-codes for valid codes.
PurchaseType:
type: string
description: 'Security Control: The industry where the virtual card will be utilized. For example, if value set to airline and the card is used at hotel, it will be declined. Available purchase type values are: ''01'' (Airline), ''02'' (Hotels and Resorts), ''03'' (Car Rental), ''04'' (Cable, Satellite, Television, and Radio Services), ''05'' (Cruise Lines), ''6'' (Travel), ''11'' (Medical Services and Health Practitioners), ''21'' (Advertising Services), ''22'' (Misc Advertising and Business Services), ''23'' (Ticketing), ''31'' (Insurance Sales, Underwriting, and Premiums), ''32'' (Insurance and Real Estate Codes), ''91'' (Restaurants and Food Services), and ''93'' (Tax Payments)..'
SequenceNumber:
type: string
description: 'Transaction sequence number within client environment. Note: value is not searchable or reportable in ConnexPay portal. Alphanumeric.'
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: '{{OrderNumber}}'
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. Reference our MerchantPayees APIs for additional details.
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.
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 characters and is alpha-numeric.
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.
CustomParameters:
type: array
description: You can add custom parameters to your issue card request in the event that you need to associate additional information with the virtual card. For example, if you want to add an invoice number you would include the custom parameters object with the name parameter = "invoice" and the value parameter as the invoice number. This requires customized reporting so you'll need to work with your implementations specialist to determine what's required.
items:
properties:
Name:
type: string
description: The custom parameter name can be anything you want to label the field. You can include as many custom parameters as needed to provide additional data to be included for the virtual card.
Value:
type: string
description: The value associated with this parameter. For example, if you are including an invoice number with your virtual card request, you would populate the custom parameter 'Name' as 'Invoice' and the custom parameter 'Value' as the invoice number.
type: object
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
examples:
Issue Card Request Example:
value:
MerchantGuid: 2b586234-7f14-432e-b0f4-a2935f783f38
Payee: Delta
FirstName: Adam
LastName: Smith
Phone: '7411237489'
Address1: 345 Main Road
Address2: ''
City: Miami Beach
State: MI
Zipcode: '33109'
Country: MX
UsageLimit: 10
AmountLimit: 180.55
ExpirationDate: '2024-12-30'
TerminateDate: '2024-12-30'
CurrencyCode: USD
Region: US
PurchaseType: '01'
SequenceNumber: Sample-seq-1
IncomingTransactionCode: 035U9MGQ5KF3XQAZQ00050000
SupplierID: AA
NonDomesticSupplier: true
Transmission:
TransmissionMethods:
- Email
- Fax
EmailRecipient: emailTo@gmail.com
MerchantPhoneNumber: '7411237489'
EmailFrom: emailFrom@gmail.com
RecipientName: Smith
Subject: Card Information
Message: here is your card information...
DaysToExpire: 1
FaxRecipient: '+55555555555'
FaxFrom: Merchant Alias
responses:
'200':
description: '200'
content:
application/json:
examples:
Issue Card Response Example:
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 \"country\":\"MX\"\n },\n \"card\":{\n \"cardGuid\":\"ae17f687-8ba7-4502-b627-24fdf5e6f218\",\n \"accountNumber\":\"1111118971563394\",\n \"securityCode\":\"617\",\n \"amountLimit\":180.55,\n \"usageLimit\":10,\n \"expirationDate\":\"2024-12-30T18:59:59\",\n \"expiration\":\"1219\",\n \"terminateDate\": \"2024-12-30T23:59:59\",\n \"currencyCode\":\"USD\",\n \"firstSix\":\"111111\",\n \"lastFour\":\"3394\",\n \"nameLine1\":\"Adam\",\n \"nameLine2\":\"Smith\",\n \"status\":\"Card - Active\",\n \"sequenceNumber\": \"Sample-seq-1\",\n \"labelIds\": [\n 889,\n 992\n ], \n },\n \"cardBrand\":\"MasterCard\",\n \"cardClass\":\"Commercial\",\n \"saleGuid\": \"d49e4881-34e5-461f-9d43-0efb0d94039d\"\n}"
Issued Card (ReturnCardData = False) Response Example:
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 \"country\":\"MX\"\n },\n \"card\":{\n \"cardGuid\":\"ae17f687-8ba7-4502-b627-24fdf5e6f218\",\n \"amountLimit\":180.55,\n \"usageLimit\":10,\n \"expirationDate\":\"2024-12-30T18:59:59\",\n \"expiration\":\"1219\",\n \"terminateDate\": \"2024-12-30T23:59:59\",\n \"currencyCode\":\"USD\",\n \"firstSix\":\"111111\",\n \"lastFour\":\"3394\",\n \"nameLine1\":\"Adam\",\n \"nameLine2\":\"Smith\",\n \"status\":\"Card - Active\",\n \"sequenceNumber\": \"Sample-seq-1\",\n \"labelIds\": [\n 889,\n 992\n ], \n },\n \"cardBrand\":\"MasterCard\",\n \"cardClass\":\"Commercial\",\n \"saleGuid\": \"d49e4881-34e5-461f-9d43-0efb0d94039d\"\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- IssueCard (COPY)
components:
securitySchemes:
sec0:
type: http
scheme: basic
x-readme:
headers:
- key: Authorization
value: Basic <JWT>
explorer-enabled: false
proxy-enabled: true
x-readme-fauxas: true