Take paymentsHosted FieldsExtend your integrationSave payment details

Save payment details when running a sale

View as Markdown

Save payment details when running a sale

You can use the single-use token from your existing Hosted Fields integration to save a customer’s payment details at the same time that you run a sale.

If you save a customer’s payment details during a sale, our gateway uses the single-use token from Hosted Fields to charge the customer, and then saves the customer’s payment details as a secure token. You can use the secure token multiple times, and it doesn’t expire.

To tokenize payment details during a sale, you need to send some additional parameters in your request to our API. You don’t need to change the JavaScript configuration or authentication for your existing Hosted Fields integration.

Before you begin

Make sure that you’ve set up your Hosted Fields integration to run a sale with the single-use token from the submissionSuccess event. For more information, go to Run a sale.

Authenticate your requests before making API calls. If your request fails, see Errors.

Integration steps

The steps that you need to follow depend on whether your single-use token represents card details or bank account details:

Save card details when you run a sale

To run a sale and tokenize the card details, you need to update your POST request to our Payments endpoint.

Request parameters

Important: The request includes parameters for functions and features that we don’t cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at [email protected].

To save a customer’s card details when you run a sale, update your request to our Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Note: If you want to use the stored payment details to run repeat payments with your own software, include the standingInstructions object in your request. For more information about repeat payments with Hosted Fields, go to Repeat payments with Hosted Fields.

Request

channelenumRequired
Channel that the merchant used to receive the payment details.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the payment.
paymentMethodobjectRequired
Polymorphic object that contains payment details. The value of the type parameter determines which variant you should use: - `card` - Payment card details - `secureToken` - Secure token details - `digitalWallet` - Digital wallet details - `singleUseToken` - Single-use token details
operatorstringOptional0-50 characters
Operator who ran the transaction.
customerobjectOptional
Object that contains the customer's contact details and address information. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data).
ipAddressobjectOptional
Object that contains the IP address of the device that sent the request.
threeDSecureobjectOptional
Polymorphic object that contains authentication information from 3-D Secure. The value of the serviceProvider parameter determines which variant you should use: - `gateway` - Use our gateway to run a 3-D Secure check. - `thirdParty` - Use a third party to run a 3-D Secure check.
credentialOnFileobjectOptional
Object that contains information about saving the customer’s payment details.
offlineProcessingobjectOptional
Object that contains information about the transaction if the merchant ran it when the terminal was offline.
autoCapturebooleanOptionalDefaults to true
Indicates if we should automatically capture the payment amount. - `true` - Run a sale and automatically capture the transaction. - `false`- Run a pre-authorization and capture the transaction later. **Note:** If you send `false` and the terminal doesn't support pre-authorization, we set the transaction's status to pending. The merchant must capture the transaction to take payment from the customer.
processAsSalebooleanOptionalDefaults to false
Indicates if we should immediately settle the sale transaction. The merchant cannot adjust the transaction if we immediately settle it. **Note:** If the value for **processAsSale** is `true`, the gateway ignores the value in **autoCapture**.
customFieldslist of objectsOptional
Array of customField objects.

Example request

POST
/v1/payments
curl -X POST https://api.payroc.com/v1/payments \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "channel": "web",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      }
    }
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}'
Try it

Response fields

If your request is successful, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also contains the following fields:

Response

paymentIdstringRequired=10 characters
Unique identifier that our gateway assigned to the transaction.
processingTerminalIdstringRequired4-50 characters
Unique identifier of the terminal that initiated the transaction.
orderobjectRequired
Object that contains information about the payment.
cardobjectRequired
Object that contains the details of the payment card.
transactionResultobjectRequired
Object that contains information about the transaction response details.
operatorstringOptional0-50 characters
Operator who initiated the request.
customerobjectOptional
Object that contains the customer's contact details and address information.
refundslist of objectsOptional
Array of refundSummary objects. Each object contains information about refunds linked to the transaction.
supportedOperationslist of enumsOptional
Array of operations that you can perform on the transaction. Our gateway can return any of the following values: - `capture` - [Capture the payment](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `refund` - [Refund the payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund). - `fullyReverse` - [Fully reverse the transaction](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `partiallyReverse` - [Partially reverse the payment](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `incrementAuthorization` - [Increase the amount of the authorization](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `adjustTip` - [Adjust the tip post-payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `addSignature` - [Add a signature to the payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsReady` - [Set the transaction’s status to `ready`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsPending` - [Set the transaction’s status to `pending`](https://docs.payroc.com/api/schema/card-payments/payments/adjust).
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1230",
    "cardholderName": "Sarah Hopper",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    },
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "status": "ready",
    "responseCode": "A",
    "type": "sale",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "OK3",
    "cardSchemeReferenceId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      }
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Save bank account details when you run a sale

To run a sale and tokenize the bank account details, you need to update your POST request to our Bank Transfer Payments endpoint.

Request parameters

Important: The request includes parameters for functions and features that we don’t cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at [email protected].

To save a customer’s bank account details when you run a sale, update your request to our Bank Transfer Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Request

processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
paymentMethodobjectRequired
Polymorphic object that contains payment detail information. The value of the type parameter determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details - `secureToken` - Secure token details - `singleUseToken` - Single-use token details
customerobjectOptional
Object that contains information about the customer.
credentialOnFileobjectOptional
Object that contains information about saving the customer’s payment details.
customFieldslist of objectsOptional
Array of customField objects.

Example request

POST
/v1/bank-transfer-payments
curl -X POST https://api.payroc.com/v1/bank-transfer-payments \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "accountType": "checking",
    "secCode": "web"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ]
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}'
Try it

Response fields

If your request is successful, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also contains the following fields:

Response

paymentIdstringRequired=10 characters
Unique identifier that we assigned to the payment.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
bankAccountobjectRequired
Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details
transactionResultobjectRequiredRead-only
Object that contains information about the transaction.
customerobjectOptional
Object that contains information about the customer.
refundslist of objectsOptional
List of refunds issued against the payment.
returnslist of objectsOptional
List of returns issued against the payment.
representmentobjectOptional
Object that contains details about the re-presented payment linked to the return.
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
{
  "paymentId": "E29U8OU8Q4",
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "bankAccount": {
    "type": "ach",
    "accountNumber": "****1591",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "063100277",
    "secCode": "web",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "responseCode": "A",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "[email protected]"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Using the secure token

After you receive the secure token that represents the customer’s payment details, you can use it in follow-up requests to our API, including:

Note: You can also use the secure token to set up repeat payments with our gateway, which requires more integration effort and cost. For more information, contact our Integrations Team at [email protected].