> 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 full documentation content, see https://docs.payroc.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.payroc.com/_mcp/server. # Create secure token POST https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens Content-Type: application/json 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). Reference: https://docs.payroc.com/api/schema/tokenization/secure-tokens/create ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: Payroc API version: 1.0.0 paths: /processing-terminals/{processingTerminalId}/secure-tokens: post: operationId: 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.subpackage_tokenization/secureTokens parameters: - name: processingTerminalId in: path description: Unique identifier that we assigned to the terminal. required: true schema: type: string - name: Authorization in: header description: Bearer authentication required: true schema: type: string - 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 description: Address line 1. address2: type: string description: Address line 2. address3: type: string description: Address line 3. city: type: string description: City. state: type: string description: Name of the state or state abbreviation. country: type: string 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 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 description: Recipient's name. address: $ref: '#/components/schemas/address' description: >- Object that contains information about the customer and their shipping address. title: shipping contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string 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 description: Customer's first name. lastName: type: string 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 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/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. 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 card or debit card transaction. - `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 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 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 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 description: Authorization code that the processor issued for the transaction. serialNumber: type: string 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 description: Encrypted card data. firstDigitOfPan: type: string 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 description: Encrypted card number. maskedPan: type: string 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 description: Expiry date of the customer’s card. cvv: type: string description: Security code of the customer’s card. cvvEncrypted: type: string format: hexadecimal description: Encrypted security code data. issueNumber: type: string 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 description: Customer’s card number. expiryDate: type: string 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 description: Security code of the customer’s card. issueNumber: type: string 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 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal 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 description: Encrypted data received from the magnetic stripe reader. firstDigitOfPan: type: string 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 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 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal 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 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 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 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 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 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal 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 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 card or debit card transaction. - `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 card or debit card transaction. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory for ACH payments and unreferenced refunds. nameOnAccount: type: string description: Customer's name. accountNumber: type: string 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 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 description: Customer's name. accountNumber: type: string 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 description: Five-digit number that identifies the customer's bank branch. institutionNumber: type: string 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 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 card or debit card transaction. - `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 - attemptedAuthentication 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 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 description: >- Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request. cavv: type: string description: >- Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment. dsTransactionId: type: string 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 description: Name of the custom field. value: type: string description: Value for the custom field. required: - name - value title: customField tokenizationRequest: type: object properties: secureTokenId: type: string description: > Unique identifier that the merchant created for the secure token that represents the customer's payment details. If the merchant doesn't create a secureTokenId, the gateway generates one and returns it in the response. operator: type: string 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 description: Address line 1. address2: type: string description: Address line 2. address3: type: string description: Address line 3. city: type: string description: City. state: type: string description: Name of the state or state abbreviation. country: type: string 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 description: Zip code or postal code. description: Object that contains information about the address. title: retrievedAddress retrievedShipping: type: object properties: recipientName: type: string 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 description: Customer's first name. lastName: type: string 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 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 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 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 description: Customer's name. accountNumber: type: string description: Customer's account number. routingNumber: type: string 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 description: Customer's name. accountNumber: type: string description: Customer's account number. transitNumber: type: string description: Five-digit code that represents the customer's banking branch. institutionNumber: type: string 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 description: Cardholder's name. cardNumber: type: string description: Primary account number of the customer's card. expiryDate: type: string 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 description: >- Unique identifier that the merchant created for the secure token that represents the customer's payment details. processingTerminalId: type: string 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 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 securitySchemes: Bearer: type: http scheme: bearer ``` ## Examples **Request** ```json { "source": { "type": "card", "cardDetails": { "entryMethod": "keyed", "keyedData": { "dataFormat": "plainText", "cardNumber": "4539858876047062", "cvv": "234", "expiryDate": "1230" }, "cardholderName": "Sarah Hazel Hopper" } }, "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", "address3": "Example Address Line 3" }, "shippingAddress": { "recipientName": "Sarah Hopper", "address": { "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2", "address3": "Example Address Line 3" } }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "ipAddress": { "type": "ipv4", "value": "104.18.24.203" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } ``` **Response** ```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", "address3": "Example Address Line 3", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056" }, "shippingAddress": { "recipientName": "Sarah Hopper", "address": { "address1": "1 Example Ave.", "address2": "Example Address Line 2", "address3": "Example Address Line 3", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056" } }, "contactMethods": [ { "type": "email", "value": "sarah.hopper@example.com" } ], "notificationLanguage": "en" }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } ``` **SDK Code** ```typescript Secure Token import { PayrocClient } from "payroc"; async function main() { const client = new PayrocClient(); await client.tokenization.secureTokens.create("1234001", { idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324", source: { type: "card", cardDetails: { entryMethod: "keyed", keyedData: { dataFormat: "plainText", cardNumber: "4539858876047062", cvv: "234", expiryDate: "1230", }, cardholderName: "Sarah Hazel Hopper", }, }, 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", address3: "Example Address Line 3", }, shippingAddress: { recipientName: "Sarah Hopper", address: { address1: "1 Example Ave.", city: "Chicago", state: "Illinois", country: "US", postalCode: "60056", address2: "Example Address Line 2", address3: "Example Address Line 3", }, }, contactMethods: [ { type: "email", value: "sarah.hopper@example.com", }, ], notificationLanguage: "en", }, ipAddress: { type: "ipv4", value: "104.18.24.203", }, customFields: [ { name: "yourCustomField", value: "abc123", }, ], }); } main(); ``` ```python Secure Token from payroc import Payroc, CardPayloadCardDetails_Keyed, KeyedCardDetailsKeyedData_PlainText, Customer, Address, Shipping, ContactMethod_Email, IpAddress, CustomField from payroc.tokenization.secure_tokens import TokenizationRequestSource_Card import datetime client = Payroc() client.tokenization.secure_tokens.create( processing_terminal_id="1234001", idempotency_key="8e03978e-40d5-43e8-bc93-6894a57f9324", source=TokenizationRequestSource_Card( card_details=CardPayloadCardDetails_Keyed( keyed_data=KeyedCardDetailsKeyedData_PlainText( card_number="4539858876047062", cvv="234", expiry_date="1230", ), cardholder_name="Sarah Hazel Hopper", ), ), operator="Jane", mit_agreement="unscheduled", customer=Customer( first_name="Sarah", last_name="Hopper", date_of_birth=datetime.date.fromisoformat("1990-07-15"), reference_number="Customer-12", billing_address=Address( address_1="1 Example Ave.", city="Chicago", state="Illinois", country="US", postal_code="60056", address_2="Example Address Line 2", address_3="Example Address Line 3", ), shipping_address=Shipping( recipient_name="Sarah Hopper", address=Address( address_1="1 Example Ave.", city="Chicago", state="Illinois", country="US", postal_code="60056", address_2="Example Address Line 2", address_3="Example Address Line 3", ), ), contact_methods=[ ContactMethod_Email( value="sarah.hopper@example.com", ) ], notification_language="en", ), ip_address=IpAddress( type="ipv4", value="104.18.24.203", ), custom_fields=[ CustomField( name="yourCustomField", value="abc123", ) ], ) ``` ```java Secure Token package com.example.usage; import com.payroc.api.PayrocApiClient; import com.payroc.api.resources.tokenization.securetokens.requests.TokenizationRequest; import com.payroc.api.resources.tokenization.securetokens.types.TokenizationRequestMitAgreement; import com.payroc.api.resources.tokenization.securetokens.types.TokenizationRequestSource; import com.payroc.api.types.Address; import com.payroc.api.types.CardPayload; import com.payroc.api.types.CardPayloadCardDetails; import com.payroc.api.types.ContactMethod; import com.payroc.api.types.ContactMethodEmail; import com.payroc.api.types.CustomField; import com.payroc.api.types.Customer; import com.payroc.api.types.CustomerNotificationLanguage; import com.payroc.api.types.IpAddress; import com.payroc.api.types.IpAddressType; import com.payroc.api.types.KeyedCardDetails; import com.payroc.api.types.KeyedCardDetailsKeyedData; import com.payroc.api.types.PlainTextKeyedDataFormat; import com.payroc.api.types.Shipping; import java.time.LocalDate; import java.util.Arrays; import java.util.Optional; public class Example { public static void main(String[] args) { PayrocApiClient client = PayrocApiClient .builder() .build(); client.tokenization().secureTokens().create( "1234001", TokenizationRequest .builder() .idempotencyKey("8e03978e-40d5-43e8-bc93-6894a57f9324") .source( TokenizationRequestSource.card( CardPayload .builder() .cardDetails( CardPayloadCardDetails.keyed( KeyedCardDetails .builder() .keyedData( KeyedCardDetailsKeyedData.plainText( PlainTextKeyedDataFormat .builder() .cardNumber("4539858876047062") .expiryDate("1230") .cvv("234") .build() ) ) .cardholderName("Sarah Hazel Hopper") .build() ) ) .build() ) ) .operator("Jane") .mitAgreement(TokenizationRequestMitAgreement.UNSCHEDULED) .customer( Customer .builder() .firstName("Sarah") .lastName("Hopper") .dateOfBirth(LocalDate.parse("1990-07-15")) .referenceNumber("Customer-12") .billingAddress( Address .builder() .address1("1 Example Ave.") .city("Chicago") .state("Illinois") .country("US") .postalCode("60056") .address2("Example Address Line 2") .address3("Example Address Line 3") .build() ) .shippingAddress( Shipping .builder() .recipientName("Sarah Hopper") .address( Address .builder() .address1("1 Example Ave.") .city("Chicago") .state("Illinois") .country("US") .postalCode("60056") .address2("Example Address Line 2") .address3("Example Address Line 3") .build() ) .build() ) .contactMethods( Optional.of( Arrays.asList( ContactMethod.email( ContactMethodEmail .builder() .value("sarah.hopper@example.com") .build() ) ) ) ) .notificationLanguage(CustomerNotificationLanguage.EN) .build() ) .ipAddress( IpAddress .builder() .type(IpAddressType.IPV_4) .value("104.18.24.203") .build() ) .customFields( Optional.of( Arrays.asList( CustomField .builder() .name("yourCustomField") .value("abc123") .build() ) ) ) .build() ); } } ``` ```ruby Secure Token require "payroc" client = Payroc::Client.new client.tokenization.secure_tokens.create( processing_terminal_id: "1234001", idempotency_key: "8e03978e-40d5-43e8-bc93-6894a57f9324", operator: "Jane", mit_agreement: "unscheduled", customer: { first_name: "Sarah", last_name: "Hopper", date_of_birth: "1990-07-15", reference_number: "Customer-12", billing_address: { address_1: "1 Example Ave.", city: "Chicago", state: "Illinois", country: "US", postal_code: "60056", address_2: "Example Address Line 2", address_3: "Example Address Line 3" }, shipping_address: { recipient_name: "Sarah Hopper", address: { address_1: "1 Example Ave.", city: "Chicago", state: "Illinois", country: "US", postal_code: "60056", address_2: "Example Address Line 2", address_3: "Example Address Line 3" } }, contact_methods: [], notification_language: "en" }, ip_address: { type: "ipv4", value: "104.18.24.203" }, custom_fields: [{ name: "yourCustomField", value: "abc123" }] ) ``` ```csharp Secure Token using Payroc; using System.Threading.Tasks; using Payroc.Tokenization.SecureTokens; using System; using System.Collections.Generic; namespace Usage; public class Example { public async Task Do() { var client = new PayrocClient(); await client.Tokenization.SecureTokens.CreateAsync( new TokenizationRequest { ProcessingTerminalId = "1234001", IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324", Source = new TokenizationRequestSource( new CardPayload { CardDetails = new CardPayloadCardDetails( new KeyedCardDetails { KeyedData = new KeyedCardDetailsKeyedData( new PlainTextKeyedDataFormat { CardNumber = "4539858876047062", Cvv = "234", ExpiryDate = "1230" } ), CardholderName = "Sarah Hazel Hopper" } ) } ), Operator = "Jane", MitAgreement = TokenizationRequestMitAgreement.Unscheduled, Customer = new Customer { FirstName = "Sarah", LastName = "Hopper", DateOfBirth = DateOnly.Parse("1990-07-15"), ReferenceNumber = "Customer-12", BillingAddress = new Address { Address1 = "1 Example Ave.", City = "Chicago", State = "Illinois", Country = "US", PostalCode = "60056", Address2 = "Example Address Line 2", Address3 = "Example Address Line 3" }, ShippingAddress = new Shipping { RecipientName = "Sarah Hopper", Address = new Address { Address1 = "1 Example Ave.", City = "Chicago", State = "Illinois", Country = "US", PostalCode = "60056", Address2 = "Example Address Line 2", Address3 = "Example Address Line 3" } }, ContactMethods = new List(){ new ContactMethod( new ContactMethodEmail { Value = "sarah.hopper@example.com" } ), } , NotificationLanguage = CustomerNotificationLanguage.En }, IpAddress = new IpAddress { Type = IpAddressType.Ipv4, Value = "104.18.24.203" }, CustomFields = new List(){ new CustomField { Name = "yourCustomField", Value = "abc123" }, } } ); } } ``` ```go Secure 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\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"cvv\": \"234\",\n \"expiryDate\": \"1230\"\n },\n \"cardholderName\": \"Sarah Hazel Hopper\"\n }\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 \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\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)) } ``` ```php Secure Token request('POST', 'https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens', [ 'body' => '{ "source": { "type": "card", "cardDetails": { "entryMethod": "keyed", "keyedData": { "dataFormat": "plainText", "cardNumber": "4539858876047062", "cvv": "234", "expiryDate": "1230" }, "cardholderName": "Sarah Hazel Hopper" } }, "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", "address3": "Example Address Line 3" }, "shippingAddress": { "recipientName": "Sarah Hopper", "address": { "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2", "address3": "Example Address Line 3" } }, "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(); ``` ```swift Secure Token import Foundation let headers = [ "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "source": [ "type": "card", "cardDetails": [ "entryMethod": "keyed", "keyedData": [ "dataFormat": "plainText", "cardNumber": "4539858876047062", "cvv": "234", "expiryDate": "1230" ], "cardholderName": "Sarah Hazel Hopper" ] ], "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", "address3": "Example Address Line 3" ], "shippingAddress": [ "recipientName": "Sarah Hopper", "address": [ "address1": "1 Example Ave.", "city": "Chicago", "state": "Illinois", "country": "US", "postalCode": "60056", "address2": "Example Address Line 2", "address3": "Example Address Line 3" ] ], "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() ```