Hosted Fields

Run a sale

View as MarkdownOpen in Claude

After a customer enters their payment details into Hosted Fields, we tokenize them and return a single-use token. To run a sale, use the single-use token with our API.

The API method that you need to use depends on the payment type that the single-use token represents, for example, card details or bank account details.

Before you begin

Single-use token

Make sure that your integration can handle submissionSuccess events to receive a single-use token when a customer submits their payment details.

Headers

To create the header of each POST request, you must include the following parameters:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.
1-H "Content-Type: application/json"
2-H "Authorization: <Bearer token>"
3-H "Idempotency-Key: <UUID v4>"

Errors

Make sure that your integration can handle errors. If a request is unsuccessful, we return an error that follows the RFC 7807 format. For more information about errors, go to Errors.

Integration steps

The method that you need to use to run the sale depends on the customer’s payment type:

Run a sale with card details

To run a sale with card details, send a 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].

For the paymentMethod object, send values for the following parameters:

  • type: Send a value of singleUseToken.
  • token: Send the single-use token that you received in the submissionSuccess event.

Request

channelenumRequired
Channel that the merchant used to receive the payment details.
Allowed values:
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.
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
1curl -X POST https://api.payroc.com/v1/payments \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "channel": "web",
7  "processingTerminalId": "1234001",
8  "order": {
9    "amount": 4999,
10    "currency": "USD",
11    "orderId": "1234567890W",
12    "description": "Card Transaction (APPLE)"
13  },
14  "paymentMethod": {
15    "type": "digitalWallet",
16    "encryptedData": "7b2262696c6c696e67436f6e74616374223a7b2266616d696c794e616d65223a22222c22676976656e4e616d65223a22222c2270686f6e6574696346616d696c794e616d65223a22222c2270686f6e65746963476976656e4e616d65223a22227d2c227368697070696e67436f6e74616374223a7b22656d61696c41646472657373223a227465737440646f6d61696e2e636f6d222c2266616d696c794e616d65223a22222c22676976656e4e616d65223a22222c2270686f6e6574696346616d696c794e616d65223a22222c2270686f6e65746963476976656e4e616d65223a22227d2c22746f6b656e223a7b227061796d656e7444617461223a7b2264617461223a2259314b37626731573479755568587473335941627a6150756c384d31795057304c724637734e2f70415950456d3871647969716c6257777356792b7732334c666c74344e6932525a684c2f6a52727563356f69496235537437763248543739682b74702f78517838496b6a5631485354594d747156644c6a413977686379774f654f70326575556d306e56386b50726569564273726a596c355931437a30576371495648595134424e737a4b5876675063686a497a6f4d4b456336425650744c7335777654667a434b51574a496a646b62516161306265685958524b422b7941773872537a6a4a476f3758523061467a414b4e70346c6f436e69484e564838373244504e4a77364b30336e544d69724b37725a615566485356754d477544473348366e4d78336c48436e6b517478764551474771754132676c416434424f427943414976483541566671655173534137776a4459702f494c6c66614e64307469467478344d6235566f6952513249387379384548547670307736667861316973613874636f484855614b32353857486474673d3d222c227369676e6174757265223a224d494147435371475349623344514548417143414d494143415145784454414c42676c67686b67425a514d45416745776741594a4b6f5a496876634e415163424141436767444343412b517767674f4c6f414d434151494343466e596f627971394f504e4d416f4743437147534d343942414d434d486f784c6a417342674e5642414d4d4a5546776347786c4945467763477870593246306157397549456c756447566e636d46306157397549454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a4165467730794d5441304d6a41784f544d334d444261467730794e6a41304d546b784f544d324e546c614d4749784b44416d42674e5642414d4d4832566a5979317a62584174596e4a76613256794c584e705a32356656554d304c564e42546b5243543167784644415342674e564241734d43326c505579425465584e305a57317a4d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a425a4d424d4742797147534d34394167454743437147534d34394177454841304941424949772f6176446e50646549437851325a74464575593334716b423357797a344c484e53314a6e6d506a505472336f4769576f7768354d4d39334f6a697157777661766f5a4d445263546f656b516d7a7055624570576a676749524d4949434454414d42674e5648524d4241663845416a41414d42384741315564497751594d42614146435079536352506b2b54764a2b62453969687350364b372f53354c4d45554743437347415155464277454242446b774e7a4131426767724267454642516377415959706148523063446f764c32396a633341755958427762475575593239744c32396a633341774e433168634842735a5746705932457a4d4449776767456442674e5648534145676745554d4949424544434341517747435371475349623359325146415443422f6a4342777759494b77594242515548416749776762594d67624e535a5778705957356a5a5342766269423061476c7a49474e6c636e52705a6d6c6a5958526c49474a35494746756553427759584a306553426863334e316257567a4947466a593256776447467559325567623259676447686c4948526f5a5734675958427762476c6a59574a735a53427a644746755a4746795a4342305a584a7463794268626d5167593239755a476c3061573975637942765a6942316332557349474e6c636e52705a6d6c6a5958526c4948427662476c6a65534268626d51675932567964476c6d61574e6864476c7662694277636d466a64476c6a5a53427a644746305a57316c626e527a4c6a4132426767724267454642516343415259716148523063446f764c33643364793568634842735a53356a623230765932567964476c6d61574e68644756686458526f62334a7064486b764d44514741315564487751744d4373774b61416e6f43574749326830644841364c79396a636d77755958427762475575593239744c3246776347786c59576c6a59544d7559334a734d4230474131556444675157424251434a44414c6d753774526a4758704b5a614b5a3543635949635254414f42674e56485138424166384542414d43423441774477594a4b6f5a496876646a5a415964424149464144414b42676771686b6a4f5051514441674e4841444245416942306f624d6b32304a4a517733544a307851644d53416a5a6f6653413436686358424e69566d4d6c2b386f7749676154615155367631433170532b6659415463574b725778517039594961446551344b63363042354b3259457767674c754d49494364614144416745434167684a62532b2f4f706a616c7a414b42676771686b6a4f50515144416a426e4d527377475159445651514444424a42634842735a5342536232393049454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a4165467730784e4441314d4459794d7a51324d7a4261467730794f5441314d4459794d7a51324d7a42614d486f784c6a417342674e5642414d4d4a5546776347786c4945467763477870593246306157397549456c756447566e636d46306157397549454e4249433067527a4d784a6a416b42674e564241734d485546776347786c49454e6c636e52705a6d6c6a59585270623234675158563061473979615852354d524d77455159445651514b44417042634842735a53424a626d4d754d517377435159445651514745774a56557a425a4d424d4742797147534d34394167454743437147534d34394177454841304941425041584559515a31325346315270654a594548647569416f752f656536354e34493338533550684d3162565a6c733172694c516c33594e496b353775676a396468664f694d743275325a7776736a6f4b59542f5645576a6766637767665177526759494b77594242515548415145454f6a41344d4459474343734741515546427a41426869706f644852774f69387662324e7a63433568634842735a53356a6232307662324e7a634441304c5746776347786c636d397664474e685a7a4d77485159445652304f4242594546435079536352506b2b54764a2b62453969687350364b372f53354c4d41384741315564457745422f7751464d414d4241663877487759445652306a42426777466f4155753744656f56677a694a716b69706e65767233727239724c4a4b73774e77594456523066424441774c6a41736f4371674b49596d6148523063446f764c324e7962433568634842735a53356a623230765958427762475679623239305932466e4d79356a636d777744675944565230504151482f42415144416745474d42414743697147534962335932514741673445416755414d416f4743437147534d343942414d43413263414d4751434d447250636f4e5246706d78687673317731624b59722f30462b335a4433564e6f6f362b385a7942586b4b33696669593935745a6e356a56515132506e656e432f6749774d693356524347776f7756336246337a4f4475515a2f305866437768625a5a50786e4a7067684a76565068366652755a7935734a6953466842706b50435a4964414141786767474a4d4949426851494241544342686a42364d5334774c4159445651514444435642634842735a5342426348427361574e6864476c766269424a626e526c5a334a6864476c7662694244515341744945637a4d5359774a4159445651514c44423142634842735a5342445a584a3061575a7059324630615739754945463164476876636d6c30655445544d424547413155454367774b51584277624755675357356a4c6a454c4d416b474131554542684d4356564d4343466e596f627971394f504e4d417347435743475341466c41775143416143426b7a415942676b71686b69473977304243514d784377594a4b6f5a496876634e415163424d42774743537147534962334451454a42544550467730794e4445794d5449784e6a51774d5452614d43674743537147534962334451454a4e4445624d426b774377594a59495a4941575544424149426f516f4743437147534d343942414d434d43384743537147534962334451454a4244456942434335615768366c647944637435626844536b62345835494a612b576f746d6d74344a624c74386949754a6b6a414b42676771686b6a4f50515144416752494d45594349514437637561364c6430697a6148716d5371713747303433476770363467484d6b514e523577757a32736137674968414e44643730585a6639432f412b58774e716a75672b76684c39534c4c4966465159746f6745377842534c774141414141414141222c22686561646572223a7b227075626c69634b657948617368223a225542347255754d6b7044627054564b7448636a6452525a496f643465766562754d4f696b7a4156556441593d222c22657068656d6572616c5075626c69634b6579223a224d466b77457759484b6f5a497a6a3043415159494b6f5a497a6a3044415163445167414557556a70324f663878427449432f354335535349544e443554736f75564c423831464547383847504b7243394e394d753365534e72586c32636564757533552f504f53652f616f75384477556a674e6670584d7831673d3d222c227472616e73616374696f6e4964223a2231363431326566383238303362633133356338333165396235663732376432366165623661616130363364633138353861313562323734386666346636333739227d2c2276657273696f6e223a2245435f7631227d2c227061796d656e744d6574686f64223a7b22646973706c61794e616d65223a224d6173746572436172642031343731222c226e6574776f726b223a224d617374657243617264222c2274797065223a226465626974227d2c227472616e73616374696f6e4964656e746966696572223a2231363431326566383238303362633133356338333165396235663732376432366165623661616130363364633138353861313562323734386666346636333739227d7d",
17    "serviceProvider": "apple"
18  },
19  "operator": "Jane"
20}'
Try it

Response fields

If your request is successful, our gateway uses the card details to run a sale. The response 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. - `capture` - Capture the payment. - `refund` - Refund the payment. - `fullyReverse` - Fully reverse the transaction. - `partiallyReverse` - Partially reverse the payment. - `incrementAuthorization` - Increase the amount of the authorization. - `adjustTip` - Adjust the tip post-payment. - `addSignature` - Add a signature to the payment. - `setAsReady` - Set the transaction’s status to `ready`. - `setAsPending` - Set the transaction’s status to `pending`.
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
1{
2  "paymentId": "J9VULKIKFP",
3  "processingTerminalId": "1234001",
4  "order": {
5    "amount": 4999,
6    "currency": "USD",
7    "orderId": "1234567890W",
8    "dateTime": "2024-07-02T15:30:00Z",
9    "description": "Card Transaction (APPLE)"
10  },
11  "card": {
12    "type": "MasterCard",
13    "entryMethod": "keyed",
14    "cardNumber": "500165******0000",
15    "expiryDate": "0328",
16    "securityChecks": {
17      "avsResult": "U"
18    }
19  },
20  "transactionResult": {
21    "status": "ready",
22    "responseCode": "A",
23    "type": "sale",
24    "approvalCode": "OK3",
25    "authorizedAmount": 4999,
26    "currency": "USD",
27    "responseMessage": "APPROVAL",
28    "processorResponseCode": "00"
29  },
30  "operator": "Jane",
31  "supportedOperations": [
32    "capture",
33    "fullyReverse",
34    "partiallyReverse",
35    "incrementAuthorization",
36    "adjustTip",
37    "setAsPending"
38  ]
39}

Run a sale with bank account details

To run a sale with bank account details, send a 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].

For the paymentMethod object, send values for the following parameters:

  • type: Send a value of singleUseToken.
  • token: Send the single-use token that you received in the submissionSuccess event.
  • accountType: Indicate if the bank account is a savings account or a checking account.
  • secCode: If the single-use token represents ACH details, indicate how the customer authorized the payment.

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
1curl -X POST https://api.payroc.com/v1/bank-transfer-payments \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "processingTerminalId": "1234001",
7  "order": {
8    "amount": 4999,
9    "currency": "USD",
10    "orderId": "OrderRef6543",
11    "breakdown": {
12      "subtotal": 4347,
13      "taxes": [
14        {
15          "rate": 5,
16          "name": "Sales Tax",
17          "type": "rate"
18        }
19      ],
20      "tip": {
21        "type": "percentage",
22        "percentage": 10
23      }
24    },
25    "description": "Large Pepperoni Pizza"
26  },
27  "paymentMethod": {
28    "type": "ach",
29    "accountNumber": "11101010",
30    "nameOnAccount": "Sarah Hazel Hopper",
31    "routingNumber": "053200983",
32    "accountType": "checking",
33    "secCode": "web"
34  },
35  "customer": {
36    "notificationLanguage": "en",
37    "contactMethods": [
38      {
39        "type": "email",
40        "value": "[email protected]"
41      }
42    ]
43  },
44  "credentialOnFile": {
45    "tokenize": true
46  },
47  "customFields": [
48    {
49      "name": "yourCustomField",
50      "value": "abc123"
51    }
52  ]
53}'
Try it

Response fields

If your request is successful, our gateway uses the bank account details to run a sale. The response 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
List of re-presented payments linked to the return.
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "amount": 4999,
6    "currency": "USD",
7    "orderId": "OrderRef6543",
8    "breakdown": {
9      "subtotal": 4347,
10      "taxes": [
11        {
12          "name": "Sales Tax",
13          "rate": 5,
14          "amount": 217
15        }
16      ],
17      "tip": {
18        "type": "percentage",
19        "amount": 435,
20        "percentage": 10
21      }
22    },
23    "dateTime": "2024-07-02T15:30:00Z",
24    "description": "Large Pepperoni Pizza"
25  },
26  "bankAccount": {
27    "type": "ach",
28    "accountNumber": "****3159",
29    "nameOnAccount": "Sarah Hazel Hopper",
30    "routingNumber": "053200983",
31    "secCode": "web",
32    "secureToken": {
33      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
34      "customerName": "Sarah Hazel Hopper",
35      "token": "296753123456",
36      "status": "notValidated",
37      "link": {
38        "rel": "self",
39        "method": "GET",
40        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
41      }
42    }
43  },
44  "transactionResult": {
45    "type": "payment",
46    "status": "ready",
47    "responseCode": "A",
48    "authorizedAmount": 4999,
49    "currency": "USD",
50    "responseMessage": "NoError",
51    "processorResponseCode": "0"
52  },
53  "customer": {
54    "notificationLanguage": "en",
55    "contactMethods": [
56      {
57        "type": "email",
58        "value": "[email protected]"
59      }
60    ]
61  },
62  "customFields": [
63    {
64      "name": "yourCustomField",
65      "value": "abc123"
66    }
67  ]
68}