> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.payroc.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.payroc.com/_mcp/server. # Save a customer's payment details > Convert a Hosted Fields single-use token into a reusable secure token by sending a POST request to the Secure Tokens endpoint, enabling future card and bank account payments without recapturing payment details. An AI skill is available for this guide, get it on the [Skills Marketplace (GitHub)](https://github.com/payroc/skills). You can update your Hosted Fields integration to save a customer's payment details as a secure token without charging the customer. To tokenize the customer's payment details, you need to update the Hosted Fields JavaScript configuration, and then send a request to our Secure Tokens endpoint. You don't need to change your authentication process for your existing Hosted Fields integration. ## Before you begin Make sure that you've set up your Hosted Fields integration to handle the single-use token from the submissionSuccess event. For more information, go to [Run a sale](/essentials/hosted-fields/run-a-sale). [Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors). ## Integration steps 1. Update the JavaScript configuration. 2. Convert the single-use token into a secure token. ## Step 1. Update the JavaScript configuration * In the JavaScript configuration, change the value for the mode parameter from payment to `tokenization`. **`Card`** ```js title="Card" ``` **`ACH`** ```js title="ACH" ``` **`PAD`** ```js title="PAD" ``` ## Step 2. Convert the single-use token into a secure token To convert the single-use token into a secure token, send a POST request to our Secure Tokens endpoint. | Environment | URL | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Test | [https://api.uat.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens](https://api.uat.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens) | | Production | [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens](https://api.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens) | ### Request parameters In the body of your request, include the singleUseToken from the submissionSuccess event in the source object. We also recommend that you assign a secureTokenId. ### Schema (`request.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /processing-terminals/{processingTerminalId}/secure-tokens: post: operationId: subpackageTokenizationSecureTokens_create summary: Create secure token description: > Use this method to create a secure token that represents a customer's payment details. When you create a secure token, you need to generate and provide a secureTokenId that you use to run follow-on actions: - [Retrieve Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/retrieve) – View the details of the secure token. - [Delete Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/delete) – Delete the secure token. - [Update Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/partially-update) – Update the details of the secure token. - [Update Account Details](https://docs.payroc.com/api/schema/tokenization/secure-tokens/update-account) – Update the secure token with the details from a single-use token. **Note:** If you don't generate a secureTokenId to identify the token, our gateway generates a unique identifier and returns it in the response. If the request is successful, our gateway returns a token that the merchant can use in transactions instead of the customer's sensitive payment details, for example, when they [run a sale](https://docs.payroc.com/api/schema/card-payments/payments/create). tags: - subpackage_tokenization/secureTokens parameters: - name: processingTerminalId in: path description: Unique identifier that we assigned to the terminal. required: true schema: type: string minLength: 4 maxLength: 50 - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '201': description: >- Successful request. We created a secure token that represents your customer's payment details. content: application/json: schema: $ref: '#/components/schemas/secureToken' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/tokenizationRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' TokenizationRequestMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. title: TokenizationRequestMitAgreement address: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string maxLength: 10 description: Zip code or postal code. required: - address1 - city - state - country - postalCode description: Object that contains information about the address. title: address shipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: > Recipient's name. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). address: $ref: '#/components/schemas/address' description: > Object that contains information about the shipping address. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: > Object that contains information about the customer and their shipping address. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: shipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod CustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: CustomerNotificationLanguage customer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string minLength: 0 maxLength: 48 description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). billingAddress: $ref: '#/components/schemas/address' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/shipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/CustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: > Object that contains the customer's contact details and address information. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: customer IpAddressType: type: string enum: - ipv4 - ipv6 description: Internet protocol version of the IP address. title: IpAddressType ipAddress: type: object properties: type: $ref: '#/components/schemas/IpAddressType' description: Internet protocol version of the IP address. value: type: string description: IP address of the device. required: - type - value description: Object that contains the IP address of the device that sent the request. title: ipAddress BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory for ACH payments and unreferenced refunds. title: BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. title: FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo DeviceModel: type: string enum: - bbposChp - bbposChp2x - bbposChp3x - bbposRambler - bbposWp - bbposWp2 - bbposWp3 - genericCtlsMsr - genericMsr - idtechAugusta - idtechMinismart - idtechSredkey - idtechVp3300 - idtechVp5300 - idtechVp6300 - idtechVp6800 - ingenicoAxiumDx4000 - ingenicoAxiumDx8000 - ingenicoAxiumEx8000 - ingenicoIct220 - ingenicoIpp320 - ingenicoIpp350 - ingenicoIuc285 - ingenicoL3000 - ingenicoL7000 - ingenicoS2000 - ingenicoS3000 - ingenicoS4000 - ingenicoS5000 - ingenicoS7000 - paxA80 - paxA920 - paxA920Pro - paxA920Max - paxE500 - paxE700 - paxE800 - paxIm30 - uic680 - uicBezel8 description: Model of the device that the merchant used to process the transaction. title: DeviceModel DeviceCategory: type: string enum: - attended - unattended default: attended description: Indicates if the device is attended or unattended. title: DeviceCategory deviceConfig: type: object properties: quickChip: type: boolean default: false description: Indicates if Quick Chip mode is active on a merchant’s POS terminal. required: - quickChip description: >- Object that contains information about the configuration of the POS terminal. title: deviceConfig device: type: object properties: model: $ref: '#/components/schemas/DeviceModel' description: >- Model of the device that the merchant used to process the transaction. category: $ref: '#/components/schemas/DeviceCategory' default: attended description: Indicates if the device is attended or unattended. serialNumber: type: string minLength: 1 maxLength: 64 description: Serial number of the physical device. firmwareVersion: type: string description: Firmware version of the physical device. config: $ref: '#/components/schemas/deviceConfig' required: - model - serialNumber description: >- Object that contains information about the physical device the merchant used to capture the customer’s card details. title: device FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo EncryptionCapableDeviceModel: type: string enum: - bbposChp - bbposChp2x - bbposChp3x - bbposRambler - bbposWp - bbposWp2 - bbposWp3 - genericCtlsMsr - genericMsr - idtechAugusta - idtechMinismart - idtechSredkey - idtechVp3300 - idtechVp5300 - idtechVp6300 - idtechVp6800 - ingenicoAxiumDx4000 - ingenicoAxiumDx8000 - ingenicoAxiumEx8000 - ingenicoIct220 - ingenicoIpp320 - ingenicoIpp350 - ingenicoIuc285 - ingenicoL3000 - ingenicoL7000 - ingenicoS2000 - ingenicoS3000 - ingenicoS4000 - ingenicoS5000 - ingenicoS7000 - paxA80 - paxA920 - paxA920Pro - paxA920Max - paxE500 - paxE700 - paxE800 - paxIm30 - uic680 - uicBezel8 description: Model of the device that the merchant used to process the transaction. title: EncryptionCapableDeviceModel EncryptionCapableDeviceCategory: type: string enum: - attended - unattended default: attended description: Indicates if the device is attended or unattended. title: EncryptionCapableDeviceCategory encryptionCapableDevice: type: object properties: model: $ref: '#/components/schemas/EncryptionCapableDeviceModel' description: >- Model of the device that the merchant used to process the transaction. category: $ref: '#/components/schemas/EncryptionCapableDeviceCategory' default: attended description: Indicates if the device is attended or unattended. serialNumber: type: string minLength: 1 maxLength: 64 description: Serial number of the physical device. firmwareVersion: type: string description: Firmware version of the physical device. config: $ref: '#/components/schemas/deviceConfig' dataKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - model - serialNumber - dataKsn description: >- Object that contains information about the encryption details of the POS terminal. title: encryptionCapableDevice EbtDetailsWithVoucherBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsWithVoucherBenefitCategory voucher: type: object properties: approvalCode: type: string minLength: 6 maxLength: 6 description: Authorization code that the processor issued for the transaction. serialNumber: type: string minLength: 7 maxLength: 15 description: Serial number of the voucher. required: - approvalCode - serialNumber description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. title: voucher ebtDetailsWithVoucher: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsWithVoucherBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. voucher: $ref: '#/components/schemas/voucher' required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetailsWithVoucher FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData: oneOf: - type: object properties: dataFormat: type: string enum: - fullyEncrypted description: 'Discriminator value: fullyEncrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted card data. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the customer’s card number. required: - dataFormat - device - encryptedData description: >- Object that contains information about the encrypted card data for keyed transactions. - type: object properties: dataFormat: type: string enum: - partiallyEncrypted description: 'Discriminator value: partiallyEncrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedPan: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted card number. maskedPan: type: string minLength: 12 maxLength: 19 description: > Masked card number. The gateway shows only the first six digits and the last four digits of the account number. For example, `453985******7062`. expiryDate: type: string pattern: '[0-9]{4}' description: Expiry date of the customer’s card. cvv: type: string pattern: '[0-9]{3,4}' description: Security code of the customer’s card. cvvEncrypted: type: string format: hexadecimal description: Encrypted security code data. issueNumber: type: string pattern: '[0-9]{1,2}' description: Issue number of the customer’s card. required: - dataFormat - device - encryptedPan - maskedPan - expiryDate description: >- Object that contains information about the partially-encrypted card data for keyed transactions. - type: object properties: dataFormat: type: string enum: - plainText description: 'Discriminator value: plainText' device: $ref: '#/components/schemas/device' cardNumber: type: string minLength: 12 maxLength: 19 description: Customer’s card number. expiryDate: type: string pattern: '[0-9]{4}' description: > Expiry date of the customer’s card. **Note:** We require you to send an expiry date for most BIN lookups and electronic voucher transactions. cvv: type: string pattern: '[0-9]{3,4}' description: Security code of the customer’s card. issueNumber: type: string pattern: '[0-9]{1,2}' description: Issue number of the customer’s card. required: - dataFormat - cardNumber description: >- Object that contains information about the plain-text card data for keyed transactions. discriminator: propertyName: dataFormat description: "Polymorphic object that contains payment card details that the merchant manually entered into the device. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`fullyEncrypted` - All payment card details are encrypted.\n-\t`partiallyEncrypted` - Some payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. discriminator: propertyName: dataFormat description: Polymorphic object that contains information about the customer's PIN. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason: type: string enum: - technical - repeatFallback - emptyCandidateList description: Reason for the fallback. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason: type: string enum: - technical - repeatFallback - emptyCandidateList description: Reason for the fallback. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData: oneOf: - type: object properties: dataFormat: type: string enum: - encrypted description: 'Discriminator value: encrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted data received from the magnetic stripe reader. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the of the card number. fallback: type: boolean description: >- Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. fallbackReason: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason description: Reason for the fallback. required: - dataFormat - device - encryptedData description: >- Object that contains information about the encrypted swiped card data. - type: object properties: dataFormat: type: string enum: - plainText description: 'Discriminator value: plainText' device: $ref: '#/components/schemas/device' trackData: type: string minLength: 16 maxLength: 256 description: Customer’s card data from the swiped transaction. fallback: type: boolean description: >- Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. fallbackReason: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason description: Reason for the fallback. required: - dataFormat - device - trackData description: Object that contains information about plain-text swiped card data. discriminator: propertyName: dataFormat description: "Polymorphic object that contains payment card details that a device captured from the magnetic strip. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`encrypted` - Payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. discriminator: propertyName: dataFormat description: Polymorphic object that contains information about the customer's PIN. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails: oneOf: - type: object properties: entryMethod: type: string enum: - raw description: 'Discriminator value: raw' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction. device: $ref: '#/components/schemas/device' rawData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Unencrypted data from the POS terminal. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). required: - entryMethod - device - rawData description: Object that contains information about the unencrypted card details. - type: object properties: entryMethod: type: string enum: - icc description: 'Discriminator value: icc' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction. device: $ref: '#/components/schemas/encryptionCapableDevice' iccData: type: string format: hexadecimal description: >- Cardholder data from the ICC. The data consists of EMV tags in Tag-Length-Value (TLV) format. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the card number. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - device - iccData description: >- Object that contains information about the Integrated Circuit Card (ICC). - type: object properties: entryMethod: type: string enum: - keyed description: 'Discriminator value: keyed' keyedData: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData description: "Polymorphic object that contains payment card details that the merchant manually entered into the device. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`fullyEncrypted` - All payment card details are encrypted.\n-\t`partiallyEncrypted` - Some payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). pinDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails description: >- Polymorphic object that contains information about the customer's PIN. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - keyedData description: Object that contains information about the keyed card details. - type: object properties: entryMethod: type: string enum: - swiped description: 'Discriminator value: swiped' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction. swipedData: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData description: "Polymorphic object that contains payment card details that a device captured from the magnetic strip. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`encrypted` - Payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" cardholderName: type: string minLength: 0 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). pinDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails description: >- Polymorphic object that contains information about the customer's PIN. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - swipedData description: >- Object that contains information about the customer’s card details for swiped transactions. discriminator: propertyName: entryMethod description: > Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: - `raw` - Unencrypted payment data directly from the device. - `icc` - Payment data that the device captured from the chip. - `keyed` - Payment data that the merchant entered manually. - `swiped` - Payment data that the device captured from the magnetic strip. title: FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. - type: object properties: dataFormat: type: string enum: - raw description: 'Discriminator value: raw' pin: type: string minLength: 1 maxLength: 2147483647 description: Customer’s unencrypted PIN. required: - dataFormat - pin description: Object that contains information about the unencrypted PIN details. discriminator: propertyName: dataFormat description: > Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: - `dukpt` - PIN information is encrypted. - `raw` - PIN information is unencrypted. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory when the single-use token represents ACH bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode TokenizationRequestSource: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. secCode: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory for ACH payments and unreferenced refunds. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: > Customer’s bank account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Nine-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - routingNumber description: >- Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: > Customer's account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit number that identifies the customer's bank branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: >- Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. - type: object properties: type: type: string enum: - card description: 'Discriminator value: card' accountType: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. cardDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails description: > Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: - `raw` - Unencrypted payment data directly from the device. - `icc` - Payment data that the device captured from the chip. - `keyed` - Payment data that the merchant entered manually. - `swiped` - Payment data that the device captured from the magnetic strip. required: - type - cardDetails description: Object that contains information about the customer’s payment card. - type: object properties: type: type: string enum: - singleUseToken description: 'Discriminator value: singleUseToken' accountType: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. token: type: string minLength: 128 maxLength: 128 description: Unique token that the gateway assigned to the payment details. pinDetails: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails description: > Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: - `dukpt` - PIN information is encrypted. - `raw` - PIN information is unencrypted. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' secCode: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory when the single-use token represents ACH bank account details. required: - type - token description: >- Object that contains information about the single-use token, which represents the customer’s payment details. discriminator: propertyName: type description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" title: TokenizationRequestSource PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci: type: string enum: - fullyAuthenticated - authAttempted description: E-commerce indicator (ECI) result of a the 3-D Secure check. title: PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci TokenizationRequestThreeDSecure: oneOf: - type: object properties: type: type: string enum: - gatewayThreeDSecure description: 'Discriminator value: gatewayThreeDSecure' mpiReference: type: string minLength: 20 maxLength: 20 description: >- Reference that our gateway assigned to the 3-D Secure authentication response. required: - type - mpiReference description: Object that contains the 3-D Secure information from our gateway. - type: object properties: type: type: string enum: - thirdPartyThreeDSecure description: 'Discriminator value: thirdPartyThreeDSecure' eci: $ref: >- #/components/schemas/PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci description: E-commerce indicator (ECI) result of a the 3-D Secure check. xid: type: string minLength: 0 maxLength: 50 description: >- Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request. cavv: type: string minLength: 0 maxLength: 50 description: >- Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment. dsTransactionId: type: string minLength: 0 maxLength: 36 description: >- Directory Server Transaction ID that the processor assigned to the request. required: - type - eci description: Object that contains the 3-D Secure information from a third party. discriminator: propertyName: type description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the type parameter determines which variant you should use: \n-\t`gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check.\n-\t`thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.\n" title: TokenizationRequestThreeDSecure customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField tokenizationRequest: type: object properties: secureTokenId: type: string minLength: 1 maxLength: 200 description: > Unique identifier that you create for the secure token that represents the customer’s payment details. **Note:** If you don't send a value for the secureTokenId, our gateway generates a unique identifier for the token. operator: type: string minLength: 1 maxLength: 50 description: Operator who saved the customer's payment details. mitAgreement: $ref: '#/components/schemas/TokenizationRequestMitAgreement' description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. customer: $ref: '#/components/schemas/customer' ipAddress: $ref: '#/components/schemas/ipAddress' source: $ref: '#/components/schemas/TokenizationRequestSource' description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" threeDSecure: $ref: '#/components/schemas/TokenizationRequestThreeDSecure' description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the type parameter determines which variant you should use: \n-\t`gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check.\n-\t`thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.\n" customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - source title: tokenizationRequest SecureTokenMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. title: SecureTokenMitAgreement retrievedAddress: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string maxLength: 10 description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: Recipient's name. address: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the customer and their shipping address. title: retrievedShipping RetrievedCustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: RetrievedCustomerNotificationLanguage retrievedCustomer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string minLength: 0 maxLength: 48 description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. billingAddress: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/retrievedShipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/RetrievedCustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: >- Object that contains the customer's contact details and address information. title: retrievedCustomer currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency surcharging: type: object properties: allowed: type: boolean description: >- Indicates if the merchant can add a surcharge when the customer uses this card. amount: type: integer format: int64 exclusiveMinimum: 0 description: > Surcharge amount to add to the transaction. **Note:** Our gateway returns the surcharge amount only if you include a transaction amount in the request. percentage: type: number format: double maximum: 100 exclusiveMinimum: 0 description: Surcharge rate that the merchant configures on their account. disclosure: type: string description: Statement that informs the customer about the surcharge fee. required: - allowed description: >- Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. title: surcharging SecureTokenSource: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: Customer's account number. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Routing number of the customer's account. required: - type - nameOnAccount - accountNumber - routingNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: Customer's account number. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit code that represents the customer's banking branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit code that represents the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - card description: 'Discriminator value: card' cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder's name. cardNumber: type: string minLength: 12 maxLength: 19 description: Primary account number of the customer's card. expiryDate: type: string pattern: '[0-9]{4}' description: Expiry date of the customer's card. cardType: type: string description: Card brand of the card, for example, Visa. currency: $ref: '#/components/schemas/currency' debit: type: boolean description: Indicates if the card is a debit card. surcharging: $ref: '#/components/schemas/surcharging' required: - type - cardholderName - cardNumber description: Object that contains the customer's card details. discriminator: propertyName: type description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" title: SecureTokenSource SecureTokenStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. title: SecureTokenStatus secureToken: type: object properties: secureTokenId: type: string minLength: 0 maxLength: 200 description: >- Unique identifier that the merchant created for the secure token that represents the customer's payment details. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. mitAgreement: $ref: '#/components/schemas/SecureTokenMitAgreement' description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. customer: $ref: '#/components/schemas/retrievedCustomer' source: $ref: '#/components/schemas/SecureTokenSource' description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" token: type: string minLength: 12 maxLength: 19 description: > Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. status: $ref: '#/components/schemas/SecureTokenStatus' description: > Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - secureTokenId - processingTerminalId - source - token - status description: Object that contains information about the secure token. title: secureToken ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link ``` ### Example request ### Request POST [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens](https://api.payroc.com/v1/processing-terminals/\{processingTerminalId}/secure-tokens) **`Secure token created from a single-use token`** ```curl Secure token created from a single-use token curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens \ -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "source": { "type": "singleUseToken", "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "operator": "Jane", "mitAgreement": "unscheduled", "customer": { "firstName": "Sarah", "lastName": "Hopper", "dateOfBirth": "1990-07-15", "referenceNumber": "Customer-12", "billingAddress": { "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2" }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "ipAddress": { "type": "ipv4", "value": "104.18.24.203" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] }' ``` **`Secure token created from a single-use token`** ```python Secure token created from a single-use token import requests url = "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens" payload = { "source": { "type": "singleUseToken", "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "operator": "Jane", "mitAgreement": "unscheduled", "customer": { "firstName": "Sarah", "lastName": "Hopper", "dateOfBirth": "1990-07-15", "referenceNumber": "Customer-12", "billingAddress": { "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2" }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "ipAddress": { "type": "ipv4", "value": "104.18.24.203" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } headers = { "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` **`Secure token created from a single-use token`** ```javascript Secure token created from a single-use token const url = 'https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens'; const options = { method: 'POST', headers: { 'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"source":{"type":"singleUseToken","token":"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"},"operator":"Jane","mitAgreement":"unscheduled","customer":{"firstName":"Sarah","lastName":"Hopper","dateOfBirth":"1990-07-15","referenceNumber":"Customer-12","billingAddress":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056","address2":"Example Address Line 2"},"contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}],"notificationLanguage":"en"},"ipAddress":{"type":"ipv4","value":"104.18.24.203"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **`Secure token created from a single-use token`** ```go Secure token created from a single-use token package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens" payload := strings.NewReader("{\n \"source\": {\n \"type\": \"singleUseToken\",\n \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\"\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` **`Secure token created from a single-use token`** ```ruby Secure token created from a single-use token require 'uri' require 'net/http' url = URI("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"source\": {\n \"type\": \"singleUseToken\",\n \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\"\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` **`Secure token created from a single-use token`** ```java Secure token created from a single-use token import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens") .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"source\": {\n \"type\": \"singleUseToken\",\n \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\"\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}") .asString(); ``` **`Secure token created from a single-use token`** ```php Secure token created from a single-use token request('POST', 'https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens', [ 'body' => '{ "source": { "type": "singleUseToken", "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "operator": "Jane", "mitAgreement": "unscheduled", "customer": { "firstName": "Sarah", "lastName": "Hopper", "dateOfBirth": "1990-07-15", "referenceNumber": "Customer-12", "billingAddress": { "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2" }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "ipAddress": { "type": "ipv4", "value": "104.18.24.203" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324', ], ]); echo $response->getBody(); ``` **`Secure token created from a single-use token`** ```csharp Secure token created from a single-use token using RestSharp; var client = new RestClient("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"source\": {\n \"type\": \"singleUseToken\",\n \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\"\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` **`Secure token created from a single-use token`** ```swift Secure token created from a single-use token import Foundation let headers = [ "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "source": [ "type": "singleUseToken", "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" ], "operator": "Jane", "mitAgreement": "unscheduled", "customer": [ "firstName": "Sarah", "lastName": "Hopper", "dateOfBirth": "1990-07-15", "referenceNumber": "Customer-12", "billingAddress": [ "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2" ], "contactMethods": [ [ "type": "email", "value": "sarah.hopper@example.com" ] ], "notificationLanguage": "en" ], "ipAddress": [ "type": "ipv4", "value": "104.18.24.203" ], "customFields": [ [ "name": "yourCustomField", "value": "abc123" ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Response fields If your request is successful, our gateway converts the single-use token into a secure token. Our gateway returns the secure token in the token field. The response also contains the following fields: ### Schema (`response.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /processing-terminals/{processingTerminalId}/secure-tokens: post: operationId: subpackageTokenizationSecureTokens_create summary: Create secure token description: > Use this method to create a secure token that represents a customer's payment details. When you create a secure token, you need to generate and provide a secureTokenId that you use to run follow-on actions: - [Retrieve Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/retrieve) – View the details of the secure token. - [Delete Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/delete) – Delete the secure token. - [Update Secure Token](https://docs.payroc.com/api/schema/tokenization/secure-tokens/partially-update) – Update the details of the secure token. - [Update Account Details](https://docs.payroc.com/api/schema/tokenization/secure-tokens/update-account) – Update the secure token with the details from a single-use token. **Note:** If you don't generate a secureTokenId to identify the token, our gateway generates a unique identifier and returns it in the response. If the request is successful, our gateway returns a token that the merchant can use in transactions instead of the customer's sensitive payment details, for example, when they [run a sale](https://docs.payroc.com/api/schema/card-payments/payments/create). tags: - subpackage_tokenization/secureTokens parameters: - name: processingTerminalId in: path description: Unique identifier that we assigned to the terminal. required: true schema: type: string minLength: 4 maxLength: 50 - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '201': description: >- Successful request. We created a secure token that represents your customer's payment details. content: application/json: schema: $ref: '#/components/schemas/secureToken' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/tokenizationRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' TokenizationRequestMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. title: TokenizationRequestMitAgreement address: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string maxLength: 10 description: Zip code or postal code. required: - address1 - city - state - country - postalCode description: Object that contains information about the address. title: address shipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: > Recipient's name. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). address: $ref: '#/components/schemas/address' description: > Object that contains information about the shipping address. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). description: > Object that contains information about the customer and their shipping address. Contains parameters required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: shipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod CustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: CustomerNotificationLanguage customer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string minLength: 0 maxLength: 48 description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. Required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). billingAddress: $ref: '#/components/schemas/address' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/shipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/CustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: > Object that contains the customer's contact details and address information. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). title: customer IpAddressType: type: string enum: - ipv4 - ipv6 description: Internet protocol version of the IP address. title: IpAddressType ipAddress: type: object properties: type: $ref: '#/components/schemas/IpAddressType' description: Internet protocol version of the IP address. value: type: string description: IP address of the device. required: - type - value description: Object that contains the IP address of the device that sent the request. title: ipAddress BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory for ACH payments and unreferenced refunds. title: BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. title: FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo DeviceModel: type: string enum: - bbposChp - bbposChp2x - bbposChp3x - bbposRambler - bbposWp - bbposWp2 - bbposWp3 - genericCtlsMsr - genericMsr - idtechAugusta - idtechMinismart - idtechSredkey - idtechVp3300 - idtechVp5300 - idtechVp6300 - idtechVp6800 - ingenicoAxiumDx4000 - ingenicoAxiumDx8000 - ingenicoAxiumEx8000 - ingenicoIct220 - ingenicoIpp320 - ingenicoIpp350 - ingenicoIuc285 - ingenicoL3000 - ingenicoL7000 - ingenicoS2000 - ingenicoS3000 - ingenicoS4000 - ingenicoS5000 - ingenicoS7000 - paxA80 - paxA920 - paxA920Pro - paxA920Max - paxE500 - paxE700 - paxE800 - paxIm30 - uic680 - uicBezel8 description: Model of the device that the merchant used to process the transaction. title: DeviceModel DeviceCategory: type: string enum: - attended - unattended default: attended description: Indicates if the device is attended or unattended. title: DeviceCategory deviceConfig: type: object properties: quickChip: type: boolean default: false description: Indicates if Quick Chip mode is active on a merchant’s POS terminal. required: - quickChip description: >- Object that contains information about the configuration of the POS terminal. title: deviceConfig device: type: object properties: model: $ref: '#/components/schemas/DeviceModel' description: >- Model of the device that the merchant used to process the transaction. category: $ref: '#/components/schemas/DeviceCategory' default: attended description: Indicates if the device is attended or unattended. serialNumber: type: string minLength: 1 maxLength: 64 description: Serial number of the physical device. firmwareVersion: type: string description: Firmware version of the physical device. config: $ref: '#/components/schemas/deviceConfig' required: - model - serialNumber description: >- Object that contains information about the physical device the merchant used to capture the customer’s card details. title: device FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo EncryptionCapableDeviceModel: type: string enum: - bbposChp - bbposChp2x - bbposChp3x - bbposRambler - bbposWp - bbposWp2 - bbposWp3 - genericCtlsMsr - genericMsr - idtechAugusta - idtechMinismart - idtechSredkey - idtechVp3300 - idtechVp5300 - idtechVp6300 - idtechVp6800 - ingenicoAxiumDx4000 - ingenicoAxiumDx8000 - ingenicoAxiumEx8000 - ingenicoIct220 - ingenicoIpp320 - ingenicoIpp350 - ingenicoIuc285 - ingenicoL3000 - ingenicoL7000 - ingenicoS2000 - ingenicoS3000 - ingenicoS4000 - ingenicoS5000 - ingenicoS7000 - paxA80 - paxA920 - paxA920Pro - paxA920Max - paxE500 - paxE700 - paxE800 - paxIm30 - uic680 - uicBezel8 description: Model of the device that the merchant used to process the transaction. title: EncryptionCapableDeviceModel EncryptionCapableDeviceCategory: type: string enum: - attended - unattended default: attended description: Indicates if the device is attended or unattended. title: EncryptionCapableDeviceCategory encryptionCapableDevice: type: object properties: model: $ref: '#/components/schemas/EncryptionCapableDeviceModel' description: >- Model of the device that the merchant used to process the transaction. category: $ref: '#/components/schemas/EncryptionCapableDeviceCategory' default: attended description: Indicates if the device is attended or unattended. serialNumber: type: string minLength: 1 maxLength: 64 description: Serial number of the physical device. firmwareVersion: type: string description: Firmware version of the physical device. config: $ref: '#/components/schemas/deviceConfig' dataKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - model - serialNumber - dataKsn description: >- Object that contains information about the encryption details of the POS terminal. title: encryptionCapableDevice EbtDetailsWithVoucherBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsWithVoucherBenefitCategory voucher: type: object properties: approvalCode: type: string minLength: 6 maxLength: 6 description: Authorization code that the processor issued for the transaction. serialNumber: type: string minLength: 7 maxLength: 15 description: Serial number of the voucher. required: - approvalCode - serialNumber description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. title: voucher ebtDetailsWithVoucher: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsWithVoucherBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. voucher: $ref: '#/components/schemas/voucher' required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetailsWithVoucher FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData: oneOf: - type: object properties: dataFormat: type: string enum: - fullyEncrypted description: 'Discriminator value: fullyEncrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted card data. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the customer’s card number. required: - dataFormat - device - encryptedData description: >- Object that contains information about the encrypted card data for keyed transactions. - type: object properties: dataFormat: type: string enum: - partiallyEncrypted description: 'Discriminator value: partiallyEncrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedPan: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted card number. maskedPan: type: string minLength: 12 maxLength: 19 description: > Masked card number. The gateway shows only the first six digits and the last four digits of the account number. For example, `453985******7062`. expiryDate: type: string pattern: '[0-9]{4}' description: Expiry date of the customer’s card. cvv: type: string pattern: '[0-9]{3,4}' description: Security code of the customer’s card. cvvEncrypted: type: string format: hexadecimal description: Encrypted security code data. issueNumber: type: string pattern: '[0-9]{1,2}' description: Issue number of the customer’s card. required: - dataFormat - device - encryptedPan - maskedPan - expiryDate description: >- Object that contains information about the partially-encrypted card data for keyed transactions. - type: object properties: dataFormat: type: string enum: - plainText description: 'Discriminator value: plainText' device: $ref: '#/components/schemas/device' cardNumber: type: string minLength: 12 maxLength: 19 description: Customer’s card number. expiryDate: type: string pattern: '[0-9]{4}' description: > Expiry date of the customer’s card. **Note:** We require you to send an expiry date for most BIN lookups and electronic voucher transactions. cvv: type: string pattern: '[0-9]{3,4}' description: Security code of the customer’s card. issueNumber: type: string pattern: '[0-9]{1,2}' description: Issue number of the customer’s card. required: - dataFormat - cardNumber description: >- Object that contains information about the plain-text card data for keyed transactions. discriminator: propertyName: dataFormat description: "Polymorphic object that contains payment card details that the merchant manually entered into the device. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`fullyEncrypted` - All payment card details are encrypted.\n-\t`partiallyEncrypted` - Some payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. discriminator: propertyName: dataFormat description: Polymorphic object that contains information about the customer's PIN. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo: type: string enum: - keyed - swiped description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason: type: string enum: - technical - repeatFallback - emptyCandidateList description: Reason for the fallback. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason: type: string enum: - technical - repeatFallback - emptyCandidateList description: Reason for the fallback. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData: oneOf: - type: object properties: dataFormat: type: string enum: - encrypted description: 'Discriminator value: encrypted' device: $ref: '#/components/schemas/encryptionCapableDevice' encryptedData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Encrypted data received from the magnetic stripe reader. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the of the card number. fallback: type: boolean description: >- Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. fallbackReason: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingEncryptedFallbackReason description: Reason for the fallback. required: - dataFormat - device - encryptedData description: >- Object that contains information about the encrypted swiped card data. - type: object properties: dataFormat: type: string enum: - plainText description: 'Discriminator value: plainText' device: $ref: '#/components/schemas/device' trackData: type: string minLength: 16 maxLength: 256 description: Customer’s card data from the swiped transaction. fallback: type: boolean description: >- Indicates that this is a fallback transaction. For example, if there was a technical issue with the chip on the customer's card and the merchant then swiped the card. fallbackReason: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedDataDiscriminatorMappingPlainTextFallbackReason description: Reason for the fallback. required: - dataFormat - device - trackData description: Object that contains information about plain-text swiped card data. discriminator: propertyName: dataFormat description: "Polymorphic object that contains payment card details that a device captured from the magnetic strip. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`encrypted` - Payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. discriminator: propertyName: dataFormat description: Polymorphic object that contains information about the customer's PIN. title: >- FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails: oneOf: - type: object properties: entryMethod: type: string enum: - raw description: 'Discriminator value: raw' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingRawDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or to a keyed transaction. device: $ref: '#/components/schemas/device' rawData: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: Unencrypted data from the POS terminal. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). required: - entryMethod - device - rawData description: Object that contains information about the unencrypted card details. - type: object properties: entryMethod: type: string enum: - icc description: 'Discriminator value: icc' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingIccDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, an Integrated Circuit Card (ICC) transaction can be downgraded to a swiped transaction or a keyed transaction. device: $ref: '#/components/schemas/encryptionCapableDevice' iccData: type: string format: hexadecimal description: >- Cardholder data from the ICC. The data consists of EMV tags in Tag-Length-Value (TLV) format. firstDigitOfPan: type: string minLength: 1 maxLength: 1 description: First digit of the card number. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - device - iccData description: >- Object that contains information about the Integrated Circuit Card (ICC). - type: object properties: entryMethod: type: string enum: - keyed description: 'Discriminator value: keyed' keyedData: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedKeyedData description: "Polymorphic object that contains payment card details that the merchant manually entered into the device. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`fullyEncrypted` - All payment card details are encrypted.\n-\t`partiallyEncrypted` - Some payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). pinDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingKeyedPinDetails description: >- Polymorphic object that contains information about the customer's PIN. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - keyedData description: Object that contains information about the keyed card details. - type: object properties: entryMethod: type: string enum: - swiped description: 'Discriminator value: swiped' downgradeTo: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedDowngradeTo description: > If an offline transaction is not approved using the initial entry method, reprocess the transaction using a downgraded entry method. For example, a swiped transaction can be downgraded to a keyed transaction. swipedData: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedSwipedData description: "Polymorphic object that contains payment card details that a device captured from the magnetic strip. \n\nThe value of the dataFormat parameter determines which variant you should use: \n-\t`encrypted` - Payment card details are encrypted.\n-\t`plainText` - Payment card details are in plain text.\n" cardholderName: type: string minLength: 0 maxLength: 50 description: Cardholder’s name. cardholderSignature: type: string description: >- Cardholder's signature. For more information about how to format the signature, go to [How to send a signature to our gateway](https://docs.payroc.com/knowledge/basic-concepts/signature-capture). pinDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetailsDiscriminatorMappingSwipedPinDetails description: >- Polymorphic object that contains information about the customer's PIN. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' required: - entryMethod - swipedData description: >- Object that contains information about the customer’s card details for swiped transactions. discriminator: propertyName: entryMethod description: > Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: - `raw` - Unencrypted payment data directly from the device. - `icc` - Payment data that the device captured from the chip. - `keyed` - Payment data that the merchant entered manually. - `swiped` - Payment data that the device captured from the magnetic strip. title: FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. - type: object properties: dataFormat: type: string enum: - raw description: 'Discriminator value: raw' pin: type: string minLength: 1 maxLength: 2147483647 description: Customer’s unencrypted PIN. required: - dataFormat - pin description: Object that contains information about the unencrypted PIN details. discriminator: propertyName: dataFormat description: > Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: - `dukpt` - PIN information is encrypted. - `raw` - PIN information is unencrypted. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory when the single-use token represents ACH bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode TokenizationRequestSource: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. secCode: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory for ACH payments and unreferenced refunds. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: > Customer’s bank account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Nine-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - routingNumber description: >- Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: > Customer's account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit number that identifies the customer's bank branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: >- Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. - type: object properties: type: type: string enum: - card description: 'Discriminator value: card' accountType: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only for bank account details. cardDetails: $ref: >- #/components/schemas/FxRateInquiryPaymentMethodDiscriminatorMappingCardCardDetails description: > Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: - `raw` - Unencrypted payment data directly from the device. - `icc` - Payment data that the device captured from the chip. - `keyed` - Payment data that the merchant entered manually. - `swiped` - Payment data that the device captured from the magnetic strip. required: - type - cardDetails description: Object that contains information about the customer’s payment card. - type: object properties: type: type: string enum: - singleUseToken description: 'Discriminator value: singleUseToken' accountType: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. token: type: string minLength: 128 maxLength: 128 description: Unique token that the gateway assigned to the payment details. pinDetails: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails description: > Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: - `dukpt` - PIN information is encrypted. - `raw` - PIN information is unencrypted. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' secCode: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode description: > Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory when the single-use token represents ACH bank account details. required: - type - token description: >- Object that contains information about the single-use token, which represents the customer’s payment details. discriminator: propertyName: type description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" title: TokenizationRequestSource PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci: type: string enum: - fullyAuthenticated - authAttempted description: E-commerce indicator (ECI) result of a the 3-D Secure check. title: PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci TokenizationRequestThreeDSecure: oneOf: - type: object properties: type: type: string enum: - gatewayThreeDSecure description: 'Discriminator value: gatewayThreeDSecure' mpiReference: type: string minLength: 20 maxLength: 20 description: >- Reference that our gateway assigned to the 3-D Secure authentication response. required: - type - mpiReference description: Object that contains the 3-D Secure information from our gateway. - type: object properties: type: type: string enum: - thirdPartyThreeDSecure description: 'Discriminator value: thirdPartyThreeDSecure' eci: $ref: >- #/components/schemas/PaymentRequestThreeDSecureDiscriminatorMappingThirdPartyEci description: E-commerce indicator (ECI) result of a the 3-D Secure check. xid: type: string minLength: 0 maxLength: 50 description: >- Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request. cavv: type: string minLength: 0 maxLength: 50 description: >- Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment. dsTransactionId: type: string minLength: 0 maxLength: 36 description: >- Directory Server Transaction ID that the processor assigned to the request. required: - type - eci description: Object that contains the 3-D Secure information from a third party. discriminator: propertyName: type description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the type parameter determines which variant you should use: \n-\t`gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check.\n-\t`thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.\n" title: TokenizationRequestThreeDSecure customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField tokenizationRequest: type: object properties: secureTokenId: type: string minLength: 1 maxLength: 200 description: > Unique identifier that you create for the secure token that represents the customer’s payment details. **Note:** If you don't send a value for the secureTokenId, our gateway generates a unique identifier for the token. operator: type: string minLength: 1 maxLength: 50 description: Operator who saved the customer's payment details. mitAgreement: $ref: '#/components/schemas/TokenizationRequestMitAgreement' description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. customer: $ref: '#/components/schemas/customer' ipAddress: $ref: '#/components/schemas/ipAddress' source: $ref: '#/components/schemas/TokenizationRequestSource' description: "Polymorphic object that contains the payment method to tokenize. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n-\t`singleUseToken` - Single-use token details\n" threeDSecure: $ref: '#/components/schemas/TokenizationRequestThreeDSecure' description: "Polymorphic object that contains authentication information from 3-D Secure. \n\nThe value of the type parameter determines which variant you should use: \n-\t`gatewayThreeDSecure` - Use our gateway to run a 3-D Secure check.\n-\t`thirdPartyThreeDSecure` - Use a third party to run a 3-D Secure check.\n" customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - source title: tokenizationRequest SecureTokenMitAgreement: type: string enum: - unscheduled - recurring - installment description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. title: SecureTokenMitAgreement retrievedAddress: type: object properties: address1: type: string maxLength: 150 description: Address line 1. address2: type: string maxLength: 150 description: Address line 2. address3: type: string maxLength: 150 description: Address line 3. city: type: string maxLength: 50 description: City. state: type: string maxLength: 50 description: Name of the state or state abbreviation. country: type: string minLength: 2 maxLength: 2 description: >- Two-digit country code for the country that the business operates in. The format follows the [ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html) standard. postalCode: type: string maxLength: 10 description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string minLength: 0 maxLength: 50 description: Recipient's name. address: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the customer and their shipping address. title: retrievedShipping RetrievedCustomerNotificationLanguage: type: string enum: - en - fr description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. title: RetrievedCustomerNotificationLanguage retrievedCustomer: type: object properties: firstName: type: string minLength: 0 maxLength: 60 description: Customer's first name. lastName: type: string minLength: 0 maxLength: 60 description: Customer's last name. dateOfBirth: type: string format: date description: >- Customer's date of birth. The format for this value is **YYYY-MM-DD**. referenceNumber: type: string minLength: 0 maxLength: 48 description: > Identifier of the transaction, also known as a customer code. For requests, you must send a value for **referenceNumber** if the customer provides one. billingAddress: $ref: '#/components/schemas/retrievedAddress' description: >- Object that contains information about the address that the card is registered to. shippingAddress: $ref: '#/components/schemas/retrievedShipping' contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" notificationLanguage: $ref: '#/components/schemas/RetrievedCustomerNotificationLanguage' description: > Language that the customer uses for notifications. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) alpha-2 standard. description: >- Object that contains the customer's contact details and address information. title: retrievedCustomer currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency surcharging: type: object properties: allowed: type: boolean description: >- Indicates if the merchant can add a surcharge when the customer uses this card. amount: type: integer format: int64 exclusiveMinimum: 0 description: > Surcharge amount to add to the transaction. **Note:** Our gateway returns the surcharge amount only if you include a transaction amount in the request. percentage: type: number format: double maximum: 100 exclusiveMinimum: 0 description: Surcharge rate that the merchant configures on their account. disclosure: type: string description: Statement that informs the customer about the surcharge fee. required: - allowed description: >- Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions. title: surcharging SecureTokenSource: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: Customer's account number. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Routing number of the customer's account. required: - type - nameOnAccount - accountNumber - routingNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: Customer's account number. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit code that represents the customer's banking branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit code that represents the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - card description: 'Discriminator value: card' cardholderName: type: string minLength: 1 maxLength: 50 description: Cardholder's name. cardNumber: type: string minLength: 12 maxLength: 19 description: Primary account number of the customer's card. expiryDate: type: string pattern: '[0-9]{4}' description: Expiry date of the customer's card. cardType: type: string description: Card brand of the card, for example, Visa. currency: $ref: '#/components/schemas/currency' debit: type: boolean description: Indicates if the card is a debit card. surcharging: $ref: '#/components/schemas/surcharging' required: - type - cardholderName - cardNumber description: Object that contains the customer's card details. discriminator: propertyName: type description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" title: SecureTokenSource SecureTokenStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. title: SecureTokenStatus secureToken: type: object properties: secureTokenId: type: string minLength: 0 maxLength: 200 description: >- Unique identifier that the merchant created for the secure token that represents the customer's payment details. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. mitAgreement: $ref: '#/components/schemas/SecureTokenMitAgreement' description: > Indicates how the merchant can use the customer's card details, as agreed by the customer: - `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event. - `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement. - `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration. customer: $ref: '#/components/schemas/retrievedCustomer' source: $ref: '#/components/schemas/SecureTokenSource' description: "Polymorphic object that contains the payment method that we tokenized. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`card` - Payment card details\n" token: type: string minLength: 12 maxLength: 19 description: > Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm. status: $ref: '#/components/schemas/SecureTokenStatus' description: > Outcome of a security check on the status of the customer's payment card or bank account. **Note:** Depending on the merchant's account settings, this feature may be unavailable. customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - secureTokenId - processingTerminalId - source - token - status description: Object that contains information about the secure token. title: secureToken ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link ``` ### Response example ### Response (201) ```json { "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa", "processingTerminalId": "1234001", "source": { "type": "card", "cardNumber": "453985******7062", "cardholderName": "Sarah Hazel Hopper", "expiryDate": "1230" }, "token": "296753123456", "status": "notValidated", "mitAgreement": "unscheduled", "customer": { "firstName": "Sarah", "lastName": "Hopper", "dateOfBirth": "1990-07-15", "referenceNumber": "Customer-12", "billingAddress": { "address1": "1 Example Ave.", "address2": "Example Address Line 2", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056" }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } ``` ## Using the secure token After you receive the secure token that represents the customer's payment details, you can use it in follow-up requests to our API, including: * [Create a card payment](/guides/take-payments/payments/run-a-card-sale) * [Create a bank transfer payment](/guides/take-payments/payments/run-a-sale-with-bank-account-details) * [Update a customer's payment details with Hosted Fields](/essentials/hosted-fields/extend-your-integration/update-a-customers-payment-details) **Note:** You can also use the secure token to set up repeat payments with our gateway, which requires more integration effort and cost. For more information, contact our Integrations Team at [integrationsupport@payroc.com](mailto:integrationsupport@payroc.com).