Skip to content
payrocdevelopers

Create single use token

Browse API reference

POST/processing-terminals/{processingTerminalId}/single-use-tokenscreateSingleUseToken

Use this method to create a single-use token that represents a customer’s payment details.

A single-use token expires after 30 minutes and merchants can use them only once.

Note: To create a reusable permanent token, go to Create Secure Token.

In the request, send the customer’s payment details. If the request is successful, our gateway returns a token that you can use in a follow-on action, for example, run a sale.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

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.

processingTerminalIdRequiredpathstring

Unique identifier that our gateway assigned to the terminal.

Request body

application/json · required
Field Edit request inputs →
  • channelstringrequired
    Channel that the merchant used to receive the payment details.poswebmoto
  • operatorstring
    Operator who initiated the request.1–50 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
    • 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

Responses

Successful request. We created the single-use token.

201 Created · application/json
{
  "expiresAt": "2024-08-05T19:50:05.723+02:00",
  "processingTerminalId": "1234001",
  "source": {
    "cardNumber": "453985******7062",
    "cardType": "Visa Credit",
    "cardholderName": "Sarah Hazel Hopper",
    "currency": "USD",
    "debit": false,
    "expiryDate": "1230",
    "type": "card"
  },
  "token": "fa2e9e51bc5265a33a5ca41449524d53d1def596ffd8c0904f222183a71a65cdb58835120a65196a48a6375abc4deafe2b7e948689ab9d6aba919e860f32e247"
}
Response schema · 30 of 166 fields
  • expiresAtstringdate-timerequired
    Date and time that the token expires. We return this value in the ISO 8601 format.
  • operatorstring
    Operator who initiated the request.0–50 chars
  • paymentMethodobject
    Polymorphic object that contains payment card details.
    • 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
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 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
  • tokenstringrequired
    Unique identifier that our gateway assigned to the payment details. Note: Merchants can use the token with other terminals linked to their account.128–128 chars

Used in workflows

pay-with-single-use-token

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer