Hosted Fields

Run a sale

View as Markdown

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

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.

Authenticate your requests before making API calls. If your request fails, see 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

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    "orderId": "1234567890W",
10    "amount": 4999,
11    "currency": "USD",
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

Example response

Response
1{
2  "paymentId": "J9VULKIKFP",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "1234567890W",
6    "amount": 4999,
7    "currency": "USD",
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
Object that contains details about the re-presented payment 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}