Skip to content
developers

Create payment

Browse API reference

POST/bank-transfer-paymentsbankTransferPayment

Use this method to run a sale with a customer's bank account details.

In the response, our gateway returns information about the bank transfer payment and a paymentId, which you need for the following methods:

  • Retrieve payment - View the details of the bank transfer payment.
  • Reverse payment - Cancel the bank transfer payment if it's an open batch.
  • Refund payment - Run a referenced refund to return funds to the customer's bank account.

Payment methods

Our gateway accepts the following payment methods:

  • Automated clearing house (ACH) details
  • Pre-authorized debit (PAD) details

You can also use secure tokens and single-use tokens that you created from ACH details or PAD details.

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.

Request body

application/json · required
Field Edit request inputs →
  • 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.
  • customFieldsobject[]
    Array of customField objects.
    • namestringrequired
      Name of the custom field.1–56 chars
    • valuestringrequired
      Value for the custom field.1–100 chars
  • customerobject
    Object that contains information about the customer.
    • 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
        • typestringrequired
          Type of contact method.email
        • valuestringrequired
          Email address.≤ 50 chars
      • phoneobject
        • typestringrequired
          Type of contact method.phone
        • valuestringrequired
          Phone number.≤ 15 chars
      • mobileobject
        • typestringrequired
          Type of contact method.mobile
        • valuestringrequired
          Mobile number.≤ 15 chars
      • faxobject
        • typestringrequired
          Type of contact method.fax
        • valuestringrequired
          Fax number.≤ 15 chars
    • notificationLanguagestringiso-639-1
      Customer's preferred notification language. This code follows the ISO 639-1 standard.2–2 charsenfr
  • orderobjectrequired
    Object that contains information about the transaction.
    • breakdownobject
      Object that contains information about the transaction.
      • taxesobject[]
        Array of tax objects.
        • namestringrequired
          Name of the tax. A tax validation on the stored rate for the tax name is performed.1–64 chars
        • ratenumberdoublerequired
          Tax percentage for the transaction. Required for Level 3 and CEDP transactions.0–99.99999
        • typestringrequired
          Indicates that the tax is a rate.rate
      • subtotalintegerint64required
        Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents.
      • tipobject
        Object that contains information about the tip.
        • amountintegerint64
          If the value for type is fixedAmount, this value is the tip amount in the currency's lowest denomination, for example, cents.
        • percentagenumberdouble
          If the value for type is percentage, this value is the tip as a percentage.≤ 100
        • typestringrequired
          Indicates if the tip is a fixed amount or a percentage. Note: Our gateway applies the percentage tip to the total amount of the transaction after tax.percentagefixedAmount
    • 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
  • 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
    • 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
    • secureTokenobject
      Object that contains information about the secure token that represents the customer’s payment details.
      • accountTypestring
        Indicates the customer’s account type. Note: Send a value for accountType only if the secure token represents bank account details.checkingsavings
      • 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 when the secure token represents ACH bank account details.webtelccdppd
      • tokenstringrequired
        Unique token that the gateway assigned to the payment details.12–19 chars
      • typestringrequired
        Method that the terminal used to take the payment.secureToken
    • singleUseTokenobject
      Object that contains information about the single-use token, which represents the customer’s payment details.
      • accountTypestring
        Indicates the customer’s account type. Note: Send a value for accountType only if the single-use token represents bank account details.checkingsavings
      • 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.
        • voucherobject
          Object that contains information about the EBT voucher. Note: Vouchers are available only for EBT SNAP payments.
          • approvalCodestringrequired
            Authorization code that the processor issued for the transaction.6–6 chars
          • serialNumberstringrequired
            Serial number of the voucher.7–15 chars
      • pinDetailsobject
        Polymorphic object that contains information about a customer's PIN. The value of the dataFormat parameter determines which variant you should use: dukpt PIN information is encrypted. raw PIN information is unencrypted.
        • dukptobject
          Object that contains information about encrypted PIN details.
          • dataFormatstringrequired
            Indicates the format of the PIN data.dukpt
          • pinstringhexadecimalrequired
            Encrypted PIN. Note: PIN is encrypted using the DUKPT scheme.1–2147483647 chars
          • pinKsnstringhexadecimalrequired
            Key serial number.20–20 chars
        • rawobject
          Object that contains information about the unencrypted PIN details.
          • dataFormatstringrequired
            Indicates the format of the PIN data.raw
          • pinstringrequired
            Customer’s unencrypted PIN.1–2147483647 chars
      • 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 when the single-use token represents ACH bank account details.webtelccdppd
      • tokenstringrequired
        Unique token that the gateway assigned to the payment details.128–128 chars
      • typestringrequired
        Method that the terminal used to take the payment.singleUseToken
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 chars

Responses

Successful request. We processed the sale.

201 Created · application/json
{
  "bankAccount": {
    "accountNumber": "****3159",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "053200983",
    "secCode": "web",
    "secureToken": {
      "customerName": "Sarah Hazel Hopper",
      "link": {
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
        "method": "GET",
        "rel": "self"
      },
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "status": "notValidated",
      "token": "296753123456"
    },
    "type": "ach"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ],
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "order": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "amount": 217,
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "tip": {
        "amount": 435,
        "percentage": 10,
        "type": "percentage"
      }
    },
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "orderId": "OrderRef6543"
  },
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "transactionResult": {
    "authorizedAmount": 4999,
    "currency": "USD",
    "processorResponseCode": "0",
    "responseCode": "A",
    "responseMessage": "NoError",
    "status": "ready",
    "type": "payment"
  }
}
Response schema · 111 fields
  • 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
    • achobject
      Object that contains the customer's account details.
      • accountNumberstringrequired
        Customer's bank account number. We mask all digits except the last four digits.4–17 chars
      • nameOnAccountstringrequired
        Customer's name.1–50 chars
      • routingNumberstringrequired
        Routing number of the customer’s account. Note: In responses, our gateway shows only the last four digits of the account's routing number, for example, *****4162.9–9 chars
      • secCodestring
        Indicates the type of authorization for the transaction. Note: The field is mandatory for ACH secure token. web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction.webtelccdppd
      • secureTokenobject
        Object that contains information about the secure token.
        • customerNamestringrequired
          Customer's name.1–50 chars
        • 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.
        • secureTokenIdstringrequired
          Unique identifier that the merchant assigned to the secure token.1–200 chars
        • statusstringrequired
          Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
        • tokenstringrequired
          Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
      • typestringrequired
        ach
    • padobject
      Object that contains the customer's account details.
      • accountNumberstringrequired
        Customer's bank account number. We mask all digits except the last four digits.7–12 chars
      • institutionNumberstringrequired
        Three-digit code that represents the customer's bank.3–3 chars
      • nameOnAccountstringrequired
        Customer's name.1–29 chars
      • secureTokenobject
        Object that contains information about the secure token.
        • customerNamestringrequired
          Customer's name.1–50 chars
        • 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.
        • secureTokenIdstringrequired
          Unique identifier that the merchant assigned to the secure token.1–200 chars
        • statusstringrequired
          Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
        • tokenstringrequired
          Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
      • transitNumberstringrequired
        Five-digit code that represents the customer's banking branch.5–5 chars
      • typestringrequired
        pad
  • customFieldsobject[]
    Array of customField objects.
    • namestringrequired
      Name of the custom field.1–56 chars
    • valuestringrequired
      Value for the custom field.1–100 chars
  • customerobject
    Object that contains information about the customer.
    • 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
        • typestringrequired
          Type of contact method.email
        • valuestringrequired
          Email address.≤ 50 chars
      • phoneobject
        • typestringrequired
          Type of contact method.phone
        • valuestringrequired
          Phone number.≤ 15 chars
      • mobileobject
        • typestringrequired
          Type of contact method.mobile
        • valuestringrequired
          Mobile number.≤ 15 chars
      • faxobject
        • typestringrequired
          Type of contact method.fax
        • valuestringrequired
          Fax number.≤ 15 chars
    • notificationLanguagestringiso-639-1
      Customer's preferred notification language. This code follows the ISO 639-1 standard.2–2 charsenfr
  • orderobjectrequired
    Object that contains information about the transaction.
    • breakdownobject
      Object that contains information about the transaction.
      • taxesobject[]
        Array of tax objects.
        • amountintegerint64
          Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
        • namestringrequired
          Name of the tax.1–64 chars
        • ratenumberdoublerequired
          Tax percentage for the transaction.0–99.99999
      • subtotalintegerint64required
        Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents.
      • tipobject
        Object that contains information about the tip.
        • amountintegerint64
          If the value for type is fixedAmount, this value is the tip amount in the currency's lowest denomination, for example, cents.
        • modestring
          Indicates how the tip was added to the transaction. prompted – The customer was prompted to add a tip during payment. adjusted – The customer added a tip on the receipt for the merchant to adjust post-transaction.promptedadjusted
        • percentagenumberdouble
          If the value for type is percentage, this value is the tip as a percentage.≤ 100
        • typestringrequired
          Indicates if the tip is a fixed amount or a percentage. Note: Our gateway applies the percentage tip to the total amount of the transaction after tax.percentagefixedAmount
    • 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
    • dateTimestringdate-time
      Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format.
    • descriptionstring
      Description of the transaction.0–1024 chars
    • orderIdstringrequired
      Unique identifier that the merchant assigns to the transaction.1–24 chars
  • paymentIdstringrequired
    Unique identifier that we assigned to the payment.10–10 chars
  • processingTerminalIdstringrequired
    Unique identifier that we assigned to the terminal.4–50 chars
  • refundsobject[]
    List of refunds issued against the payment.
    • amountintegerint64required
      Amount of the refund. This 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
    • dateTimestringdate-timerequired
      Date and time that the refund was processed.
    • 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.
    • refundIdstringrequired
      Unique identifier of the refund.10–10 chars
    • responseCodestringrequired
      Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
    • responseMessagestringrequired
      Description of the response from the processor.1–48 chars
    • statusstringrequired
      Current status of the refund.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
  • representmentobject
    Object that contains information about a payment.
    • amountintegerint64required
      Amount of the payment. This 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
    • dateTimestringdate-timerequired
      Date and time that the payment was processed.
    • 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.
    • paymentIdstringrequired
      Unique identifier of the payment.10–10 chars
    • responseCodestringrequired
      Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
    • responseMessagestring
      Response description from the processor.1–48 chars
    • statusstringrequired
      Current status of the payment.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
  • returnsobject[]
    List of returns issued against the payment.
    • closedbooleanrequired
      Indicates whether the merchant accepted an alternative payment method to complete the payment.
    • datestringdaterequired
      The date that the check was returned.
    • 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.
    • paymentIdstringrequired
      Unique identifier that our gateway assigned to the payment.10–10 chars
    • representedbooleanrequired
      Indicates whether the return has been re-presented.
    • returnCodestringrequired
      The NACHA return code.
    • returnReasonstringrequired
      The reason why the check was returned.
  • transactionResultobjectrequired
    Object that contains information about the transaction.
    • authorizedAmountintegerint64
      Amount of the transaction. Note: The amount is negative for a refund.
    • currencystring
      Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    • processorResponseCodestring
      Original response code that the processor sent.
    • responseCodestringrequired
      Response from the processor. A The processor approved the transaction. D The processor declined the transaction.
    • responseMessagestring
      Description of the response from the processor.1–48 chars
    • statusstringrequired
      Status of the transaction. The value is one of the following: ready Successful transaction. We added the payment to the open batch. pending Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. declined Unsuccessful transaction. The customer's bank declined the transfer. complete Successful transaction. The funds have moved to the merchant’s bank account. admin Transaction under review. We have flagged an issue with the transaction. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. returned Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the returns object.readypendingdeclinedcompleteadminreversalreturned
    • typestringrequired
      Type of transaction.paymentrefundunreferencedRefundaccountVerification

Used in workflows

run-a-bank-transfer-sale

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