Create secure token

Browse API reference

POST/processing-terminals/{processingTerminalId}/secure-tokenscreateSecureToken

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 – View the details of the secure token.
Delete Secure Token – Delete the secure token.
Update Secure Token – Update the details of the secure token.
Update Account Details – 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.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.

Request body

application/json · required

Field Edit request inputs →

customFieldsobject[]
Array of customField objects.
- namestringrequired
  Name of the custom field.1–56 chars
- valuestringrequired
  Value for the custom field.1–100 chars
customerobject
Object that contains the customer's contact details and address information. Contains parameters required for Level 2, Level 3, and CEDP transactions.
- billingAddressobject
  Object that contains information about the address.
  - address1stringrequired
    Address line 1.≤ 150 chars
  - address2string
    Address line 2.≤ 150 chars
  - address3string
    Address line 3.≤ 150 chars
  - citystringrequired
    City.≤ 50 chars
  - countrystringrequired
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
  - postalCodestringrequired
    Zip code or postal code.≤ 10 chars
  - statestringrequired
    Name of the state or state abbreviation.≤ 50 chars
- contactMethodsobject[]
  Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 more fields at deeper levels — see the full spec
- dateOfBirthstringdate
  Customer's date of birth. The format for this value is YYYY-MM-DD.
- firstNamestring
  Customer's first name.0–60 chars
- lastNamestring
  Customer's last name.0–60 chars
- notificationLanguagestringiso-639-1
  Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
- referenceNumberstring
  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.0–48 chars
- shippingAddressobject
  Object that contains information about the customer and their shipping address. Contains parameters required for Level 3 and CEDP transactions.
  - addressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - recipientNamestring
    Recipient's name. Required for Level 3 and CEDP transactions.0–50 chars
ipAddressobject
Object that contains the IP address of the device that sent the request.
- typestringrequired
  Internet protocol version of the IP address.ipv4ipv6
- valuestringrequired
  IP address of the device.
mitAgreementstring
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.unscheduledrecurringinstallment
operatorstring
Operator who saved the customer's payment details.1–50 chars
secureTokenIdstring
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.1–200 chars
sourceobjectrequired
Polymorphic object that contains the payment method to tokenize. The value of the type parameter determines which variant you should use: ach Automated Clearing House (ACH) details pad Pre-authorized debit (PAD) details card Payment card details singleUseToken Single-use token details
- achobject
  Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions.
  - accountNumberstringrequired
    Customer’s bank account number. Note: In responses, our gateway shows only the last four digits of the account number, for example, *****5929.4–17 chars^[0-9]*$
  - accountTypestring
    Indicates the customer’s account type. Note: For bank account details, send a value for accountType.checkingsavings
  - nameOnAccountstringrequired
    Customer's name.1–50 chars
  - routingNumberstringrequired
    Nine-digit number that identifies the customer's bank.9–9 chars^[0-9]*$
  - secCodestring
    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.webtelccdppd
  - typestringrequired
    Indicates the type of bank account details the customer is using: ACH Customer's bank account is in the United States. PAD Customer's bank account is in Canada.ach
- padobject
  Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions.
  - accountNumberstringrequired
    Customer's account number. Note: In responses, our gateway shows only the last four digits of the account number, for example, *****5929.7–12 chars^[0-9]*$
  - accountTypestring
    Indicates the customer’s account type. Note: For bank account details, send a value for accountType.checkingsavings
  - institutionNumberstringrequired
    Three-digit number that identifies the customer's bank.3–3 chars^[0-9]*$
  - nameOnAccountstringrequired
    Customer's name.1–29 chars
  - transitNumberstringrequired
    Five-digit number that identifies the customer's bank branch.5–5 chars^[0-9]*$
  - typestringrequired
    Indicates the type of bank account details the customer is using: ACH Customer's bank account is in the United States. PAD Customer's bank account is in Canada.pad
- cardobject
  Object that contains information about the customer’s payment card.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardDetailsobjectrequired
    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.+132 more fields at deeper levels — see the full spec
  - typestringrequired
    Method that the terminal used to take the payment.card
- singleUseTokenobject
  Object that contains information about the single-use token, which represents the customer’s payment details.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only if the single-use token represents bank account details.checkingsavings
  - ebtDetailsobject
    Object that contains information about the Electronic Benefit Transfer (EBT) transaction.+5 more fields at deeper levels — see the full spec
  - pinDetailsobject
    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.+7 more fields at deeper levels — see the full spec
  - secCodestring
    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.webtelccdppd
  - tokenstringrequired
    Unique token that the gateway assigned to the payment details.128–128 chars
  - typestringrequired
    Method that the terminal used to take the payment.singleUseToken
threeDSecureobject
Polymorphic object that contains authentication information from 3-D Secure. The value of the type parameter determines which variant you should use: gatewayThreeDSecure Use our gateway to run a 3-D Secure check. thirdPartyThreeDSecure Use a third party to run a 3-D Secure check.
- gatewayobject
  Object that contains the 3-D Secure information from our gateway.
  - mpiReferencestringrequired
    Reference that our gateway assigned to the 3-D Secure authentication response.20–20 chars
  - serviceProviderstringrequired
    Provider of your 3-D Secure protocol.gateway
- thirdPartyobject
  Object that contains the 3-D Secure information from a third party.
  - cavvstring
    Cardholder Authentication Verification Value (CAVV) that the card issuer provided to prove that they authorized the online payment.0–50 chars
  - dsTransactionIdstring
    Directory Server Transaction ID that the processor assigned to the request.0–36 chars
  - ecistringrequired
    E-commerce indicator (ECI) result of a the 3-D Secure check.fullyAuthenticatedauthAttempted
  - serviceProviderstringrequired
    Provider of your 3-D Secure protocol.thirdParty
  - xidstring
    Unique transaction identifier that the merchant assigned to the transaction and sent in the authentication request.0–50 chars

Responses

Successful request. We created a secure token that represents your customer's payment details.

201 Created · application/json

{
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ],
  "customer": {
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "country": "US",
      "postalCode": "60056",
      "state": "Illinois"
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "dateOfBirth": "1990-07-15",
    "firstName": "Sarah",
    "lastName": "Hopper",
    "notificationLanguage": "en",
    "referenceNumber": "Customer-12",
    "shippingAddress": {
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "country": "US",
        "postalCode": "60056",
        "state": "Illinois"
      },
      "recipientName": "Sarah Hopper"
    }
  },
  "mitAgreement": "unscheduled",
  "processingTerminalId": "1234001",
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "source": {
    "cardNumber": "453985******7062",
    "cardholderName": "Sarah Hazel Hopper",
    "expiryDate": "1230",
    "type": "card"
  },
  "status": "notValidated",
  "token": "296753123456"
}

Response schema · 51 of 70 fields

customFieldsobject[]
Array of customField objects.
- namestringrequired
  Name of the custom field.1–56 chars
- valuestringrequired
  Value for the custom field.1–100 chars
customerobject
Object that contains the customer's contact details and address information.
- billingAddressobject
  Object that contains information about the address.
  - address1string
    Address line 1.≤ 150 chars
  - address2string
    Address line 2.≤ 150 chars
  - address3string
    Address line 3.≤ 150 chars
  - citystring
    City.≤ 50 chars
  - countrystring
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
  - postalCodestring
    Zip code or postal code.≤ 10 chars
  - statestring
    Name of the state or state abbreviation.≤ 50 chars
- contactMethodsobject[]
  Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 more fields at deeper levels — see the full spec
- dateOfBirthstringdate
  Customer's date of birth. The format for this value is YYYY-MM-DD.
- firstNamestring
  Customer's first name.0–60 chars
- lastNamestring
  Customer's last name.0–60 chars
- notificationLanguagestringiso-639-1
  Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
- referenceNumberstring
  Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one.0–48 chars
- shippingAddressobject
  Object that contains information about the customer and their shipping address.
  - addressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - recipientNamestring
    Recipient's name.0–50 chars
mitAgreementstring
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.unscheduledrecurringinstallment
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
secureTokenIdstringrequired
Unique identifier that the merchant created for the secure token that represents the customer's payment details.0–200 chars
sourceobjectrequired
Polymorphic object that contains the payment method that we tokenized. The value of the type parameter determines which variant you should use: ach Automated Clearing House (ACH) details pad Pre-authorized debit (PAD) details card Payment card details
- achobject
  Object that contains the customer's account details.
  - accountNumberstringrequired
    Customer's account number.4–17 chars^[0-9]*$
  - nameOnAccountstringrequired
    Customer's name.1–50 chars
  - routingNumberstringrequired
    Routing number of the customer's account.9–9 chars^[0-9]*$
  - typestringrequired
    ach
- padobject
  Object that contains the customer's account details.
  - accountNumberstringrequired
    Customer's account number.7–12 chars^[0-9]*$
  - institutionNumberstringrequired
    Three-digit code that represents the customer's bank.3–3 chars^[0-9]*$
  - nameOnAccountstringrequired
    Customer's name.1–29 chars
  - transitNumberstringrequired
    Five-digit code that represents the customer's banking branch.5–5 chars^[0-9]*$
  - typestringrequired
    pad
- Cardobject
  Object that contains the customer's card details.
  - cardNumberstringrequired
    Primary account number of the customer's card.12–19 chars
  - cardTypestring
    Card brand of the card, for example, Visa.
  - cardholderNamestringrequired
    Cardholder's name.1–50 chars
  - currencystring
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  - debitboolean
    Indicates if the card is a debit card.
  - expiryDatestring
    Expiry date of the customer's card.[0-9]{4}
  - surchargingobject
    Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions.+4 more fields at deeper levels — see the full spec
  - typestringrequired
    Type of payment.card
statusstringrequired
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.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
tokenstringrequired
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.12–19 chars

Validation error

400 Bad Request · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

save-a-card-with-hosted-fields save-a-payment-method

Create secure token

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer