openapi: 3.1.0 info: title: purchases-api 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 explorer-enabled: false proxy-enabled: true x-readme-fauxas: true