Skip to content
payrocdevelopers

Submit payment instruction

Browse API reference

POST/devices/{serialNumber}/payment-instructionssendPaymentInstruction

Use this method to submit an instruction request to initiate a sale on a payment device.

In the request, include the order amount and currency.

When you send a successful request, our gateway returns information about the payment instruction and a paymentInstructionId, which you need for the following methods:

Parameters

NameInTypeDescription
serialNumberRequiredpathstring

Serial number of the merchant’s payment device.

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.

Request body

application/json · required
Field Edit request inputs →
  • autoCaptureboolean
    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.
  • credentialOnFileobject
    Object that contains information about saving the customer’s payment details.
    • externalVaultboolean
      Indicates if the merchant uses a third-party vault to store the customer’s payment details.
    • mitAgreementstring
      Indicates how the merchant can use the customer's card details to run future card transactions, as agreed with the customer. If you send a value for the mitAgreement parameter, you must also include the standingInstructions object in your request. unscheduled Transactions for a fixed or variable amount that the merchant runs at a certain predefined event. recurring Transactions for a fixed amount that the merchant runs 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 the merchant runs at regular intervals, for example, monthly. Installment transactions have a fixed duration. Note: If you send a value for mitAgreement, you must send the standingInstructions object in the paymentOrder object.unscheduledrecurringinstallment
    • secureTokenIdstring
      Unique identifier that the merchant creates for the secure token that represents the customer’s payment details. Note: If you do not send a value for the secureTokenId parameter, our gateway generates a unique identifier for the token.0–200 chars
    • tokenizeboolean
      Indicates if our gateway should tokenize the customer’s payment details as part of the transaction.
  • 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
  • customizationOptionsobject
    Object that contains available options to customize certain aspects of an instruction.
    • closedLoopOptionsobject
      Polymorphic object that indicates the type of closed-loop card that the merchant accepts.
      • option 1object
        +1 more fields at deeper levels — see the full spec
    • ebtDetailsobject
      Object that contains information about the Electronic Benefit Transfer (EBT) transaction.
      • benefitCategorystringrequired
        Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
      • withdrawalboolean
        Indicates whether the customer wants to withdraw cash. Note: Cash withdrawals are available only from EBT Cash accounts.
    • entryMethodstring
      Indicates how you want the device to capture the card details. deviceRead Device prompts the cardholder to tap, swipe, or insert their card. manualEntry Device prompts the merchant or cardholder to manually enter card details. deviceReadOrManualEntry Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details.deviceReadmanualEntrydeviceReadOrManualEntry
  • 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.
  • operatorstring
    Operator who initiated the request.0–50 chars
  • orderobjectrequired
    Object that contains information about the payment.
    • amountintegerint64required
      Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents.
    • currencystringrequired
      Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    • descriptionstring
      Description of the transaction.0–1024 chars
    • orderIdstringrequired
      Unique identifier that the merchant assigns to the transaction.1–24 chars
    • acceptPartialAmountboolean
      Indicates if the merchant accepts a partial authorization for this transaction. true — If the issuer cannot approve the full amount, the gateway accepts a partial authorization and returns the approved amount. The integrator is responsible for collecting the remaining balance via a follow-up payment. false — Standard authorization behavior. If the issuer cannot approve the full amount, the transaction is declined. Note: When this field is omitted, the default is false and standard authorization behavior applies.
    • breakdownobject
      Object that contains information about the breakdown of the transaction.
      • cashbackAmountintegerint64
        Amount of cashback for the transaction.
      • dualPricingobject
        Object that contains information about dual pricing.+2 more fields at deeper levels — see the full spec
      • healthcareExpensesobject[]
        Array of healthcareExpense objects that contain information about healthcare expenses.+2 more fields at deeper levels — see the full spec
      • subtotalintegerint64required
        Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. Required for Level 2, Level 3, and CEDP transactions.
      • surchargeobject
        Object that contains information about the surcharge.+1 more fields at deeper levels — see the full spec
      • tipobject
        Object that contains information about the tip.+3 more fields at deeper levels — see the full spec
      • taxesobject[]
        List of taxes.+3 more fields at deeper levels — see the full spec
  • processAsSaleboolean
    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.
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 chars

Responses

Successful request. We accepted the payment instruction.

202 Accepted · application/json
{
  "link": {
    "href": "https://api.payroc.com/v1/payment-instructions/a37439165d134678a9100ebba3b29597",
    "method": "GET",
    "rel": "self"
  },
  "paymentInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "inProgress"
}
Response schema · 7 fields
  • errorMessagestring
    Description of the error that caused the instruction to fail. Note: We return this field only if the status is failure.
  • 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.
  • statusstringrequired
    Indicates the current status of the instruction. canceled – The instruction was canceled before it was completed. completed – The instruction has completed. Use the link object to check the resource. failure – The instruction failed. Check the errorMessage field for more information. inProgress – The instruction is currently in progress.canceledcompletedfailureinProgress
  • paymentInstructionIdstringrequired
    Unique identifier that we assigned to the payment instruction.1–36 chars

Used in workflows

run-a-sale-on-a-device

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