> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.payroc.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.payroc.com/_mcp/server. # Run a sale with bank account details > Run a bank transfer payment by sending a POST request to the Bank Transfer Payments endpoint with ACH or PAD bank account details and amount. Our gateway supports the following bank transfer services: * **Automated Clearing House (ACH):** A service that U.S. banks use to transfer funds between accounts. * **Pre-Authorized Debit (PAD):** A service that Canadian banks use to transfer funds between accounts. ## Integration steps * Create a bank transfer payment. ## Before you begin [Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors). ## Create a bank transfer payment To create a bank transfer payment, send a POST request to our Bank Transfer Payments endpoint. | Environment | URL | | :---------- | :----------------------------------------------------------------------------------------------------------- | | Test | [https://api.uat.payroc.com/v1/bank-transfer-payments](https://api.uat.payroc.com/v1/bank-transfer-payments) | | Production | [https://api.payroc.com/v1/bank-transfer-payments](https://api.payroc.com/v1/bank-transfer-payments) | ### Request parameters To create the body of your request, use the following parameters: ### Schema (`request.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /bank-transfer-payments: post: operationId: subpackageBankTransferPaymentsPayments_create summary: Create payment description: "Use this method to run a sale with a customer's bank account details. \n\nIn the response, our gateway returns information about the bank transfer payment and a paymentId, which you need for the following methods: \n-\t[Retrieve payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve) - View the details of the bank transfer payment.\n-\t[Reverse payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/reverse-payment) - Cancel the bank transfer payment if it's an open batch.\n-\t[Refund payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) - Run a referenced refund to return funds to the customer's bank account.\n\n**Payment methods** \n\nOur gateway accepts the following payment methods: \n-\tAutomated clearing house (ACH) details\n-\tPre-authorized debit (PAD) details \n\nYou can also use [secure tokens](https://docs.payroc.com/api/schema/payments/secure-tokens/overview) and [single-use tokens](https://docs.payroc.com/api/schema/tokenization/single-use-tokens/create) that you created from ACH details or PAD details. \n" tags: - subpackage_bankTransferPayments/payments parameters: - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '201': description: Successful request. We processed the sale. content: application/json: schema: $ref: '#/components/schemas/bankTransferPayment' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/bankTransferPaymentRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency taxRate: type: object properties: rate: type: number format: double minimum: 0 maximum: 99.99999 description: > Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). name: type: string minLength: 1 maxLength: 64 description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - rate - name title: taxRate TipType: type: string enum: - percentage - fixedAmount description: > 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. title: TipType TipMode: type: string enum: - prompted - adjusted description: > 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. title: TipMode tip: type: object properties: type: $ref: '#/components/schemas/TipType' description: > 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. mode: $ref: '#/components/schemas/TipMode' description: > 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. amount: type: integer format: int64 exclusiveMinimum: 0 description: > If the value for type is `fixedAmount`, this value is the tip amount in the currency's lowest denomination, for example, cents. percentage: type: number format: double maximum: 100 exclusiveMinimum: 0 description: >- If the value for type is `percentage`, this value is the tip as a percentage. required: - type description: Object that contains information about the tip. title: tip bankTransferRequestBreakdown: type: object properties: taxes: type: array items: $ref: '#/components/schemas/taxRate' description: Array of tax objects. subtotal: type: integer format: int64 description: >- Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. required: - subtotal description: Object that contains information about the transaction. title: bankTransferRequestBreakdown bankTransferPaymentRequestOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. dateTime: type: string format: date-time description: >- The processing date and time of the transaction represented as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. description: type: string minLength: 1 maxLength: 256 description: A brief description of the transaction. amount: type: integer format: int64 description: >- The total amount in the currency's lowest denomination. For example, cents. currency: $ref: '#/components/schemas/currency' breakdown: $ref: '#/components/schemas/bankTransferRequestBreakdown' required: - orderId - amount - currency description: Object that contains information about the transaction. title: bankTransferPaymentRequestOrder BankTransferCustomerNotificationLanguage: type: string enum: - en - fr description: >- Customer's preferred notification language. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) standard. title: BankTransferCustomerNotificationLanguage contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod bankTransferCustomer: type: object properties: notificationLanguage: $ref: '#/components/schemas/BankTransferCustomerNotificationLanguage' description: >- Customer's preferred notification language. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) standard. contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" description: Object that contains information about the customer. title: bankTransferCustomer SchemasCredentialOnFileMitAgreement: type: string enum: - unscheduled - recurring - installment description: > 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](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.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. title: SchemasCredentialOnFileMitAgreement schemas-credentialOnFile: type: object properties: externalVault: type: boolean default: false description: >- Indicates if the merchant uses a third-party vault to store the customer’s payment details. tokenize: type: boolean description: >- Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. secureTokenId: type: string minLength: 0 maxLength: 200 description: > 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. mitAgreement: $ref: '#/components/schemas/SchemasCredentialOnFileMitAgreement' description: > 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](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.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. description: >- Object that contains information about saving the customer’s payment details. title: schemas-credentialOnFile BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details. title: >- BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: >- BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. - type: object properties: dataFormat: type: string enum: - raw description: 'Discriminator value: raw' pin: type: string minLength: 1 maxLength: 2147483647 description: Customer’s unencrypted PIN. required: - dataFormat - pin description: Object that contains information about the unencrypted PIN details. discriminator: propertyName: dataFormat description: > 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. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails EbtDetailsWithVoucherBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsWithVoucherBenefitCategory voucher: type: object properties: approvalCode: type: string minLength: 6 maxLength: 6 description: Authorization code that the processor issued for the transaction. serialNumber: type: string minLength: 7 maxLength: 15 description: Serial number of the voucher. required: - approvalCode - serialNumber description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. title: voucher ebtDetailsWithVoucher: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsWithVoucherBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. voucher: $ref: '#/components/schemas/voucher' required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetailsWithVoucher BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode BankTransferPaymentRequestPaymentMethod: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. secCode: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode description: > 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. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: > Customer’s bank account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Nine-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - routingNumber description: >- Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: > Customer's account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit number that identifies the customer's bank branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: >- Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. - type: object properties: type: type: string enum: - secureToken description: 'Discriminator value: secureToken' accountType: $ref: >- #/components/schemas/BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details. token: type: string minLength: 12 maxLength: 19 description: Unique token that the gateway assigned to the payment details. secCode: $ref: >- #/components/schemas/BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode description: > 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. required: - type - token description: >- Object that contains information about the secure token that represents the customer’s payment details. - type: object properties: type: type: string enum: - singleUseToken description: 'Discriminator value: singleUseToken' accountType: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. token: type: string minLength: 128 maxLength: 128 description: Unique token that the gateway assigned to the payment details. pinDetails: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails description: > 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. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' secCode: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode description: > 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. required: - type - token description: >- Object that contains information about the single-use token, which represents the customer’s payment details. discriminator: propertyName: type description: "Polymorphic object that contains payment detail information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`secureToken` - Secure token details\n-\t`singleUseToken` - Single-use token details\n" title: BankTransferPaymentRequestPaymentMethod customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField bankTransferPaymentRequest: type: object properties: processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/bankTransferPaymentRequestOrder' customer: $ref: '#/components/schemas/bankTransferCustomer' credentialOnFile: $ref: '#/components/schemas/schemas-credentialOnFile' paymentMethod: $ref: '#/components/schemas/BankTransferPaymentRequestPaymentMethod' description: "Polymorphic object that contains payment detail information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`secureToken` - Secure token details\n-\t`singleUseToken` - Single-use token details\n" customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - processingTerminalId - order - paymentMethod description: >- Object that contains information about the sale and the customer's bank details. title: bankTransferPaymentRequest retrievedTax: type: object properties: name: type: string minLength: 1 maxLength: 64 description: Name of the tax. rate: type: number format: double minimum: 0 maximum: 99.99999 description: Tax percentage for the transaction. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents. required: - name - rate title: retrievedTax bankTransferBreakdown: type: object properties: taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: Array of tax objects. subtotal: type: integer format: int64 description: >- Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. required: - subtotal description: Object that contains information about the transaction. title: bankTransferBreakdown bankTransferPaymentOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. dateTime: type: string format: date-time description: >- The processing date and time of the transaction represented as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. description: type: string minLength: 1 maxLength: 256 description: A brief description of the transaction. amount: type: integer format: int64 description: >- The total amount in the currency's lowest denomination. For example, cents. currency: $ref: '#/components/schemas/currency' breakdown: $ref: '#/components/schemas/bankTransferBreakdown' required: - orderId - amount - currency description: Object that contains information about the transaction. title: bankTransferPaymentOrder BankTransferRefundBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: | 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. title: BankTransferRefundBankAccountDiscriminatorMappingAchSecCode SecureTokenSummaryStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > 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. title: SecureTokenSummaryStatus link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link secureTokenSummary: type: object properties: secureTokenId: type: string minLength: 1 maxLength: 200 description: Unique identifier that the merchant assigned to the secure token. customerName: type: string minLength: 1 maxLength: 50 description: Customer's name. token: type: string minLength: 12 maxLength: 19 description: > 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. status: $ref: '#/components/schemas/SecureTokenSummaryStatus' description: > 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. link: $ref: '#/components/schemas/link' required: - secureTokenId - customerName - token - status description: Object that contains information about the secure token. title: secureTokenSummary BankTransferPaymentBankAccount: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' secCode: $ref: >- #/components/schemas/BankTransferRefundBankAccountDiscriminatorMappingAchSecCode description: > 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. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string minLength: 4 maxLength: 17 description: >- Customer's bank account number. We mask all digits except the last four digits. routingNumber: type: string minLength: 9 maxLength: 9 description: > 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. secureToken: $ref: '#/components/schemas/secureTokenSummary' required: - type - nameOnAccount - accountNumber - routingNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string minLength: 7 maxLength: 12 description: >- Customer's bank account number. We mask all digits except the last four digits. transitNumber: type: string minLength: 5 maxLength: 5 description: Five-digit code that represents the customer's banking branch. institutionNumber: type: string minLength: 3 maxLength: 3 description: Three-digit code that represents the customer's bank. secureToken: $ref: '#/components/schemas/secureTokenSummary' required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: Object that contains the customer's account details. discriminator: propertyName: type description: "Polymorphic object that contains bank account information.\n\nThe value of the type field determines which variant you should use:\n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" title: BankTransferPaymentBankAccount RefundSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the refund. title: RefundSummaryStatus RefundSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > 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. title: RefundSummaryResponseCode refundSummary: type: object properties: refundId: type: string minLength: 10 maxLength: 10 description: Unique identifier of the refund. dateTime: type: string format: date-time description: Date and time that the refund was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/RefundSummaryStatus' description: Current status of the refund. responseCode: $ref: '#/components/schemas/RefundSummaryResponseCode' description: > 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. responseMessage: type: string minLength: 1 maxLength: 48 description: Description of the response from the processor. link: $ref: '#/components/schemas/link' required: - refundId - dateTime - currency - amount - status - responseCode - responseMessage description: Object that contains information about a refund. title: refundSummary bankTransferReturnSummary: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that our gateway assigned to the payment. date: type: string format: date description: The date that the check was returned. returnCode: type: string description: The NACHA return code. returnReason: type: string description: The reason why the check was returned. represented: type: boolean description: Indicates whether the return has been re-presented. closed: type: boolean description: >- Indicates whether the merchant accepted an alternative payment method to complete the payment. link: $ref: '#/components/schemas/link' required: - paymentId - date - returnCode - returnReason - represented - closed description: Object that contains information about a return. title: bankTransferReturnSummary PaymentSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the payment. title: PaymentSummaryStatus PaymentSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > 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. title: PaymentSummaryResponseCode paymentSummary: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier of the payment. dateTime: type: string format: date-time description: Date and time that the payment was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the payment. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/PaymentSummaryStatus' description: Current status of the payment. responseCode: $ref: '#/components/schemas/PaymentSummaryResponseCode' description: > 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. responseMessage: type: string minLength: 1 maxLength: 48 description: Response description from the processor. link: $ref: '#/components/schemas/link' required: - paymentId - dateTime - currency - amount - status - responseCode description: Object that contains information about a payment. title: paymentSummary BankTransferResultType: type: string enum: - payment - refund - unreferencedRefund - accountVerification description: Type of transaction. title: BankTransferResultType BankTransferResultStatus: type: string enum: - ready - pending - declined - complete - admin - reversal - returned description: "Status of the transaction. The value is one of the following: \n- `ready` - Successful transaction. We added the payment to the open batch. \n- `pending` - Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. \n-\t`declined` - Unsuccessful transaction. The customer's bank declined the transfer. \n-\t`complete` - Successful transaction. The funds have moved to the merchant’s bank account. \n-\t`admin` - Transaction under review. We have flagged an issue with the transaction. \n-\t`reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. \n-\t`returned` - Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the **returns** object. \n" title: BankTransferResultStatus bankTransferResult: type: object properties: type: $ref: '#/components/schemas/BankTransferResultType' description: Type of transaction. status: $ref: '#/components/schemas/BankTransferResultStatus' description: "Status of the transaction. The value is one of the following: \n- `ready` - Successful transaction. We added the payment to the open batch. \n- `pending` - Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. \n-\t`declined` - Unsuccessful transaction. The customer's bank declined the transfer. \n-\t`complete` - Successful transaction. The funds have moved to the merchant’s bank account. \n-\t`admin` - Transaction under review. We have flagged an issue with the transaction. \n-\t`reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. \n-\t`returned` - Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the **returns** object. \n" authorizedAmount: type: integer format: int64 description: | Amount of the transaction. **Note:** The amount is negative for a refund. currency: $ref: '#/components/schemas/currency' responseCode: type: string description: | Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. responseMessage: type: string minLength: 1 maxLength: 48 description: Description of the response from the processor. processorResponseCode: type: string description: Original response code that the processor sent. required: - type - status - responseCode description: Object that contains information about the transaction. title: bankTransferResult bankTransferPayment: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that we assigned to the payment. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/bankTransferPaymentOrder' customer: $ref: '#/components/schemas/bankTransferCustomer' bankAccount: $ref: '#/components/schemas/BankTransferPaymentBankAccount' description: "Polymorphic object that contains bank account information.\n\nThe value of the type field determines which variant you should use:\n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" refunds: type: array items: $ref: '#/components/schemas/refundSummary' description: List of refunds issued against the payment. returns: type: array items: $ref: '#/components/schemas/bankTransferReturnSummary' description: List of returns issued against the payment. representment: $ref: '#/components/schemas/paymentSummary' description: >- Object that contains details about the re-presented payment linked to the return. transactionResult: $ref: '#/components/schemas/bankTransferResult' customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - paymentId - processingTerminalId - order - bankAccount - transactionResult description: >- Object that contains information about the sale and the customer's bank details. title: bankTransferPayment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ``` ### Example request ### Request POST [https://api.payroc.com/v1/bank-transfer-payments](https://api.payroc.com/v1/bank-transfer-payments) **`Store Token Bank Transfer Payment`** ```curl Store Token Bank Transfer Payment curl -X POST https://api.payroc.com/v1/bank-transfer-payments \ -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "processingTerminalId": "1234001", "order": { "amount": 4999, "currency": "USD", "orderId": "OrderRef6543", "breakdown": { "subtotal": 4347, "taxes": [ { "rate": 5, "name": "Sales Tax", "type": "rate" } ], "tip": { "type": "percentage", "percentage": 10 } }, "description": "Large Pepperoni Pizza" }, "paymentMethod": { "type": "ach", "accountNumber": "11101010", "nameOnAccount": "Sarah Hazel Hopper", "routingNumber": "053200983", "accountType": "checking", "secCode": "web" }, "customer": { "notificationLanguage": "en", "contactMethods": [ { "type": "email", "value": "joe@blogssoftware.com" } ] }, "credentialOnFile": { "tokenize": true }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] }' ``` **`Store Token Bank Transfer Payment`** ```python Store Token Bank Transfer Payment import requests url = "https://api.payroc.com/v1/bank-transfer-payments" payload = { "processingTerminalId": "1234001", "order": { "amount": 4999, "currency": "USD", "orderId": "OrderRef6543", "breakdown": { "subtotal": 4347, "taxes": [ { "rate": 5, "name": "Sales Tax", "type": "rate" } ], "tip": { "type": "percentage", "percentage": 10 } }, "description": "Large Pepperoni Pizza" }, "paymentMethod": { "type": "ach", "accountNumber": "11101010", "nameOnAccount": "Sarah Hazel Hopper", "routingNumber": "053200983", "accountType": "checking", "secCode": "web" }, "customer": { "notificationLanguage": "en", "contactMethods": [ { "type": "email", "value": "joe@blogssoftware.com" } ] }, "credentialOnFile": { "tokenize": True }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } headers = { "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` **`Store Token Bank Transfer Payment`** ```javascript Store Token Bank Transfer Payment const url = 'https://api.payroc.com/v1/bank-transfer-payments'; const options = { method: 'POST', headers: { 'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"processingTerminalId":"1234001","order":{"amount":4999,"currency":"USD","orderId":"OrderRef6543","breakdown":{"subtotal":4347,"taxes":[{"rate":5,"name":"Sales Tax","type":"rate"}],"tip":{"type":"percentage","percentage":10}},"description":"Large Pepperoni Pizza"},"paymentMethod":{"type":"ach","accountNumber":"11101010","nameOnAccount":"Sarah Hazel Hopper","routingNumber":"053200983","accountType":"checking","secCode":"web"},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"joe@blogssoftware.com"}]},"credentialOnFile":{"tokenize":true},"customFields":[{"name":"yourCustomField","value":"abc123"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **`Store Token Bank Transfer Payment`** ```go Store Token Bank Transfer Payment package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.payroc.com/v1/bank-transfer-payments" payload := strings.NewReader("{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"amount\": 4999,\n \"currency\": \"USD\",\n \"orderId\": \"OrderRef6543\",\n \"breakdown\": {\n \"subtotal\": 4347,\n \"taxes\": [\n {\n \"rate\": 5,\n \"name\": \"Sales Tax\",\n \"type\": \"rate\"\n }\n ],\n \"tip\": {\n \"type\": \"percentage\",\n \"percentage\": 10\n }\n },\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"ach\",\n \"accountNumber\": \"11101010\",\n \"nameOnAccount\": \"Sarah Hazel Hopper\",\n \"routingNumber\": \"053200983\",\n \"accountType\": \"checking\",\n \"secCode\": \"web\"\n },\n \"customer\": {\n \"notificationLanguage\": \"en\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@blogssoftware.com\"\n }\n ]\n },\n \"credentialOnFile\": {\n \"tokenize\": true\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` **`Store Token Bank Transfer Payment`** ```ruby Store Token Bank Transfer Payment require 'uri' require 'net/http' url = URI("https://api.payroc.com/v1/bank-transfer-payments") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"amount\": 4999,\n \"currency\": \"USD\",\n \"orderId\": \"OrderRef6543\",\n \"breakdown\": {\n \"subtotal\": 4347,\n \"taxes\": [\n {\n \"rate\": 5,\n \"name\": \"Sales Tax\",\n \"type\": \"rate\"\n }\n ],\n \"tip\": {\n \"type\": \"percentage\",\n \"percentage\": 10\n }\n },\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"ach\",\n \"accountNumber\": \"11101010\",\n \"nameOnAccount\": \"Sarah Hazel Hopper\",\n \"routingNumber\": \"053200983\",\n \"accountType\": \"checking\",\n \"secCode\": \"web\"\n },\n \"customer\": {\n \"notificationLanguage\": \"en\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@blogssoftware.com\"\n }\n ]\n },\n \"credentialOnFile\": {\n \"tokenize\": true\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` **`Store Token Bank Transfer Payment`** ```java Store Token Bank Transfer Payment import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.payroc.com/v1/bank-transfer-payments") .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"amount\": 4999,\n \"currency\": \"USD\",\n \"orderId\": \"OrderRef6543\",\n \"breakdown\": {\n \"subtotal\": 4347,\n \"taxes\": [\n {\n \"rate\": 5,\n \"name\": \"Sales Tax\",\n \"type\": \"rate\"\n }\n ],\n \"tip\": {\n \"type\": \"percentage\",\n \"percentage\": 10\n }\n },\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"ach\",\n \"accountNumber\": \"11101010\",\n \"nameOnAccount\": \"Sarah Hazel Hopper\",\n \"routingNumber\": \"053200983\",\n \"accountType\": \"checking\",\n \"secCode\": \"web\"\n },\n \"customer\": {\n \"notificationLanguage\": \"en\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@blogssoftware.com\"\n }\n ]\n },\n \"credentialOnFile\": {\n \"tokenize\": true\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}") .asString(); ``` **`Store Token Bank Transfer Payment`** ```php Store Token Bank Transfer Payment request('POST', 'https://api.payroc.com/v1/bank-transfer-payments', [ 'body' => '{ "processingTerminalId": "1234001", "order": { "amount": 4999, "currency": "USD", "orderId": "OrderRef6543", "breakdown": { "subtotal": 4347, "taxes": [ { "rate": 5, "name": "Sales Tax", "type": "rate" } ], "tip": { "type": "percentage", "percentage": 10 } }, "description": "Large Pepperoni Pizza" }, "paymentMethod": { "type": "ach", "accountNumber": "11101010", "nameOnAccount": "Sarah Hazel Hopper", "routingNumber": "053200983", "accountType": "checking", "secCode": "web" }, "customer": { "notificationLanguage": "en", "contactMethods": [ { "type": "email", "value": "joe@blogssoftware.com" } ] }, "credentialOnFile": { "tokenize": true }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324', ], ]); echo $response->getBody(); ``` **`Store Token Bank Transfer Payment`** ```csharp Store Token Bank Transfer Payment using RestSharp; var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"amount\": 4999,\n \"currency\": \"USD\",\n \"orderId\": \"OrderRef6543\",\n \"breakdown\": {\n \"subtotal\": 4347,\n \"taxes\": [\n {\n \"rate\": 5,\n \"name\": \"Sales Tax\",\n \"type\": \"rate\"\n }\n ],\n \"tip\": {\n \"type\": \"percentage\",\n \"percentage\": 10\n }\n },\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"ach\",\n \"accountNumber\": \"11101010\",\n \"nameOnAccount\": \"Sarah Hazel Hopper\",\n \"routingNumber\": \"053200983\",\n \"accountType\": \"checking\",\n \"secCode\": \"web\"\n },\n \"customer\": {\n \"notificationLanguage\": \"en\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@blogssoftware.com\"\n }\n ]\n },\n \"credentialOnFile\": {\n \"tokenize\": true\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` **`Store Token Bank Transfer Payment`** ```swift Store Token Bank Transfer Payment import Foundation let headers = [ "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "processingTerminalId": "1234001", "order": [ "amount": 4999, "currency": "USD", "orderId": "OrderRef6543", "breakdown": [ "subtotal": 4347, "taxes": [ [ "rate": 5, "name": "Sales Tax", "type": "rate" ] ], "tip": [ "type": "percentage", "percentage": 10 ] ], "description": "Large Pepperoni Pizza" ], "paymentMethod": [ "type": "ach", "accountNumber": "11101010", "nameOnAccount": "Sarah Hazel Hopper", "routingNumber": "053200983", "accountType": "checking", "secCode": "web" ], "customer": [ "notificationLanguage": "en", "contactMethods": [ [ "type": "email", "value": "joe@blogssoftware.com" ] ] ], "credentialOnFile": ["tokenize": true], "customFields": [ [ "name": "yourCustomField", "value": "abc123" ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/bank-transfer-payments")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Response fields If your request is successful, we create the payment and return the following response: ### Schema (`response.body`) ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /bank-transfer-payments: post: operationId: subpackageBankTransferPaymentsPayments_create summary: Create payment description: "Use this method to run a sale with a customer's bank account details. \n\nIn the response, our gateway returns information about the bank transfer payment and a paymentId, which you need for the following methods: \n-\t[Retrieve payment](https://docs.payroc.com/api/schema/bank-transfer-payments/payments/retrieve) - View the details of the bank transfer payment.\n-\t[Reverse payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/reverse-payment) - Cancel the bank transfer payment if it's an open batch.\n-\t[Refund payment](https://docs.payroc.com/api/schema/bank-transfer-payments/refunds/refund) - Run a referenced refund to return funds to the customer's bank account.\n\n**Payment methods** \n\nOur gateway accepts the following payment methods: \n-\tAutomated clearing house (ACH) details\n-\tPre-authorized debit (PAD) details \n\nYou can also use [secure tokens](https://docs.payroc.com/api/schema/payments/secure-tokens/overview) and [single-use tokens](https://docs.payroc.com/api/schema/tokenization/single-use-tokens/create) that you created from ACH details or PAD details. \n" tags: - subpackage_bankTransferPayments/payments parameters: - name: Idempotency-Key in: header description: >- Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency). required: true schema: type: string format: uuid responses: '201': description: Successful request. We processed the sale. content: application/json: schema: $ref: '#/components/schemas/bankTransferPayment' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/400' '401': description: Identity could not be verified content: application/json: schema: $ref: '#/components/schemas/401' '403': description: Do not have permissions to perform this action content: application/json: schema: $ref: '#/components/schemas/403' '406': description: Not acceptable content: application/json: schema: $ref: '#/components/schemas/406' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/409' '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/415' '500': description: An error has occured content: application/json: schema: $ref: '#/components/schemas/500' requestBody: content: application/json: schema: $ref: '#/components/schemas/bankTransferPaymentRequest' servers: - url: https://api.payroc.com/v1 description: Production - url: https://api.uat.payroc.com/v1 description: UAT components: schemas: '400': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '400' '401': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '401' '403': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path the action was attempted on resource: type: string description: Resource the action was attempted on required: - type - title - status - detail title: '403' '406': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '406' '409': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem instance: type: string description: Resource path to the existing resource errors: type: array items: $ref: '#/components/schemas/ErrorsItems' link: $ref: '#/components/schemas/link' required: - type - title - status - detail title: '409' '415': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem required: - type - title - status - detail title: '415' '500': type: object properties: type: type: string description: URI reference identifying the problem type title: type: string description: Short description of the issue. status: type: integer description: Http status code detail: type: string description: Explanation of the problem errors: type: array items: $ref: '#/components/schemas/ErrorsItems' required: - type - title - status - detail title: '500' currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL description: >- Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard. title: currency taxRate: type: object properties: rate: type: number format: double minimum: 0 maximum: 99.99999 description: > Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data). name: type: string minLength: 1 maxLength: 64 description: >- Name of the tax. A tax validation on the stored rate for the tax name is performed. required: - rate - name title: taxRate TipType: type: string enum: - percentage - fixedAmount description: > 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. title: TipType TipMode: type: string enum: - prompted - adjusted description: > 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. title: TipMode tip: type: object properties: type: $ref: '#/components/schemas/TipType' description: > 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. mode: $ref: '#/components/schemas/TipMode' description: > 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. amount: type: integer format: int64 exclusiveMinimum: 0 description: > If the value for type is `fixedAmount`, this value is the tip amount in the currency's lowest denomination, for example, cents. percentage: type: number format: double maximum: 100 exclusiveMinimum: 0 description: >- If the value for type is `percentage`, this value is the tip as a percentage. required: - type description: Object that contains information about the tip. title: tip bankTransferRequestBreakdown: type: object properties: taxes: type: array items: $ref: '#/components/schemas/taxRate' description: Array of tax objects. subtotal: type: integer format: int64 description: >- Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. required: - subtotal description: Object that contains information about the transaction. title: bankTransferRequestBreakdown bankTransferPaymentRequestOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. dateTime: type: string format: date-time description: >- The processing date and time of the transaction represented as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. description: type: string minLength: 1 maxLength: 256 description: A brief description of the transaction. amount: type: integer format: int64 description: >- The total amount in the currency's lowest denomination. For example, cents. currency: $ref: '#/components/schemas/currency' breakdown: $ref: '#/components/schemas/bankTransferRequestBreakdown' required: - orderId - amount - currency description: Object that contains information about the transaction. title: bankTransferPaymentRequestOrder BankTransferCustomerNotificationLanguage: type: string enum: - en - fr description: >- Customer's preferred notification language. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) standard. title: BankTransferCustomerNotificationLanguage contactMethod: oneOf: - type: object properties: type: type: string enum: - email description: 'Discriminator value: email' value: type: string maxLength: 50 description: Email address. required: - type - value description: email variant - type: object properties: type: type: string enum: - phone description: 'Discriminator value: phone' value: type: string maxLength: 15 description: Phone number. required: - type - value description: phone variant - type: object properties: type: type: string enum: - mobile description: 'Discriminator value: mobile' value: type: string maxLength: 15 description: Mobile number. required: - type - value description: mobile variant - type: object properties: type: type: string enum: - fax description: 'Discriminator value: fax' value: type: string maxLength: 15 description: Fax number. required: - type - value description: fax variant discriminator: propertyName: type title: contactMethod bankTransferCustomer: type: object properties: notificationLanguage: $ref: '#/components/schemas/BankTransferCustomerNotificationLanguage' description: >- Customer's preferred notification language. This code follows the [ISO 639-1](https://www.iso.org/iso-639-language-code) standard. contactMethods: type: array items: $ref: '#/components/schemas/contactMethod' description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n" description: Object that contains information about the customer. title: bankTransferCustomer SchemasCredentialOnFileMitAgreement: type: string enum: - unscheduled - recurring - installment description: > 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](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.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. title: SchemasCredentialOnFileMitAgreement schemas-credentialOnFile: type: object properties: externalVault: type: boolean default: false description: >- Indicates if the merchant uses a third-party vault to store the customer’s payment details. tokenize: type: boolean description: >- Indicates if our gateway should tokenize the customer’s payment details as part of the transaction. secureTokenId: type: string minLength: 0 maxLength: 200 description: > 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. mitAgreement: $ref: '#/components/schemas/SchemasCredentialOnFileMitAgreement' description: > 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](https://docs.payroc.com/api/schema/card-payments/payments/create#request.body.order.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. description: >- Object that contains information about saving the customer’s payment details. title: schemas-credentialOnFile BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType: type: string enum: - checking - savings description: | Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. title: >- BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details. title: >- BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: >- BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType: type: string enum: - checking - savings description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails: oneOf: - type: object properties: dataFormat: type: string enum: - dukpt description: 'Discriminator value: dukpt' pin: type: string format: hexadecimal minLength: 1 maxLength: 2147483647 description: | Encrypted PIN. **Note:** PIN is encrypted using the DUKPT scheme. pinKsn: type: string format: hexadecimal minLength: 20 maxLength: 20 description: Key serial number. required: - dataFormat - pin - pinKsn description: Object that contains information about encrypted PIN details. - type: object properties: dataFormat: type: string enum: - raw description: 'Discriminator value: raw' pin: type: string minLength: 1 maxLength: 2147483647 description: Customer’s unencrypted PIN. required: - dataFormat - pin description: Object that contains information about the unencrypted PIN details. discriminator: propertyName: dataFormat description: > 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. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails EbtDetailsWithVoucherBenefitCategory: type: string enum: - cash - foodStamp description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP title: EbtDetailsWithVoucherBenefitCategory voucher: type: object properties: approvalCode: type: string minLength: 6 maxLength: 6 description: Authorization code that the processor issued for the transaction. serialNumber: type: string minLength: 7 maxLength: 15 description: Serial number of the voucher. required: - approvalCode - serialNumber description: | Object that contains information about the EBT voucher. **Note:** Vouchers are available only for EBT SNAP payments. title: voucher ebtDetailsWithVoucher: type: object properties: benefitCategory: $ref: '#/components/schemas/EbtDetailsWithVoucherBenefitCategory' description: > Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. - `cash` – EBT Cash - `foodStamp` – EBT SNAP withdrawal: type: boolean description: > Indicates whether the customer wants to withdraw cash. **Note:** Cash withdrawals are available only from EBT Cash accounts. voucher: $ref: '#/components/schemas/voucher' required: - benefitCategory description: >- Object that contains information about the Electronic Benefit Transfer (EBT) transaction. title: ebtDetailsWithVoucher BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode: type: string enum: - web - tel - ccd - ppd description: > 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. title: >- BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode BankTransferPaymentRequestPaymentMethod: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. secCode: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingAchSecCode description: > 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. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 4 maxLength: 17 description: > Customer’s bank account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. routingNumber: type: string pattern: ^[0-9]*$ minLength: 9 maxLength: 9 description: Nine-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - routingNumber description: >- Object that contains information about the payment details for the customer’s automated clearing house (ACH) transactions. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' accountType: $ref: >- #/components/schemas/BankAccountVerificationRequestBankAccountDiscriminatorMappingPadAccountType description: > Indicates the customer’s account type. **Note:** For bank account details, send a value for accountType. nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string pattern: ^[0-9]*$ minLength: 7 maxLength: 12 description: > Customer's account number. **Note:** In responses, our gateway shows only the last four digits of the account number, for example, `*****5929`. transitNumber: type: string pattern: ^[0-9]*$ minLength: 5 maxLength: 5 description: Five-digit number that identifies the customer's bank branch. institutionNumber: type: string pattern: ^[0-9]*$ minLength: 3 maxLength: 3 description: Three-digit number that identifies the customer's bank. required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: >- Object that contains information about the payment details for the customer’s preauthorized electronic debit (PAD) transactions. - type: object properties: type: type: string enum: - secureToken description: 'Discriminator value: secureToken' accountType: $ref: >- #/components/schemas/BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details. token: type: string minLength: 12 maxLength: 19 description: Unique token that the gateway assigned to the payment details. secCode: $ref: >- #/components/schemas/BankTransferUnreferencedRefundRefundMethodDiscriminatorMappingSecureTokenSecCode description: > 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. required: - type - token description: >- Object that contains information about the secure token that represents the customer’s payment details. - type: object properties: type: type: string enum: - singleUseToken description: 'Discriminator value: singleUseToken' accountType: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenAccountType description: > Indicates the customer’s account type. **Note:** Send a value for accountType only if the single-use token represents bank account details. token: type: string minLength: 128 maxLength: 128 description: Unique token that the gateway assigned to the payment details. pinDetails: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenPinDetails description: > 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. ebtDetails: $ref: '#/components/schemas/ebtDetailsWithVoucher' secCode: $ref: >- #/components/schemas/BankTransferPaymentRequestPaymentMethodDiscriminatorMappingSingleUseTokenSecCode description: > 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. required: - type - token description: >- Object that contains information about the single-use token, which represents the customer’s payment details. discriminator: propertyName: type description: "Polymorphic object that contains payment detail information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`secureToken` - Secure token details\n-\t`singleUseToken` - Single-use token details\n" title: BankTransferPaymentRequestPaymentMethod customField: type: object properties: name: type: string minLength: 1 maxLength: 56 description: Name of the custom field. value: type: string minLength: 1 maxLength: 100 description: Value for the custom field. required: - name - value title: customField bankTransferPaymentRequest: type: object properties: processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/bankTransferPaymentRequestOrder' customer: $ref: '#/components/schemas/bankTransferCustomer' credentialOnFile: $ref: '#/components/schemas/schemas-credentialOnFile' paymentMethod: $ref: '#/components/schemas/BankTransferPaymentRequestPaymentMethod' description: "Polymorphic object that contains payment detail information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n-\t`secureToken` - Secure token details\n-\t`singleUseToken` - Single-use token details\n" customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - processingTerminalId - order - paymentMethod description: >- Object that contains information about the sale and the customer's bank details. title: bankTransferPaymentRequest retrievedTax: type: object properties: name: type: string minLength: 1 maxLength: 64 description: Name of the tax. rate: type: number format: double minimum: 0 maximum: 99.99999 description: Tax percentage for the transaction. amount: type: integer format: int64 exclusiveMinimum: 0 description: >- Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents. required: - name - rate title: retrievedTax bankTransferBreakdown: type: object properties: taxes: type: array items: $ref: '#/components/schemas/retrievedTax' description: Array of tax objects. subtotal: type: integer format: int64 description: >- Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents. tip: $ref: '#/components/schemas/tip' description: Object that contains tip information for the transaction. required: - subtotal description: Object that contains information about the transaction. title: bankTransferBreakdown bankTransferPaymentOrder: type: object properties: orderId: type: string minLength: 1 maxLength: 24 description: Unique identifier that the merchant assigns to the transaction. dateTime: type: string format: date-time description: >- The processing date and time of the transaction represented as per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. description: type: string minLength: 1 maxLength: 256 description: A brief description of the transaction. amount: type: integer format: int64 description: >- The total amount in the currency's lowest denomination. For example, cents. currency: $ref: '#/components/schemas/currency' breakdown: $ref: '#/components/schemas/bankTransferBreakdown' required: - orderId - amount - currency description: Object that contains information about the transaction. title: bankTransferPaymentOrder BankTransferRefundBankAccountDiscriminatorMappingAchSecCode: type: string enum: - web - tel - ccd - ppd description: | 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. title: BankTransferRefundBankAccountDiscriminatorMappingAchSecCode SecureTokenSummaryStatus: type: string enum: - notValidated - cvvValidated - validationFailed - issueNumberValidated - cardNumberValidated - bankAccountValidated description: > 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. title: SecureTokenSummaryStatus link: type: object properties: rel: type: string description: >- Indicates the relationship between the current resource and the target resource. method: type: string description: HTTP method that you need to use with the target resource. href: type: string description: URL of the target resource. required: - rel - method - href description: Object that contains HATEOAS links for the resource. title: link secureTokenSummary: type: object properties: secureTokenId: type: string minLength: 1 maxLength: 200 description: Unique identifier that the merchant assigned to the secure token. customerName: type: string minLength: 1 maxLength: 50 description: Customer's name. token: type: string minLength: 12 maxLength: 19 description: > 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. status: $ref: '#/components/schemas/SecureTokenSummaryStatus' description: > 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. link: $ref: '#/components/schemas/link' required: - secureTokenId - customerName - token - status description: Object that contains information about the secure token. title: secureTokenSummary BankTransferPaymentBankAccount: oneOf: - type: object properties: type: type: string enum: - ach description: 'Discriminator value: ach' secCode: $ref: >- #/components/schemas/BankTransferRefundBankAccountDiscriminatorMappingAchSecCode description: > 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. nameOnAccount: type: string minLength: 1 maxLength: 50 description: Customer's name. accountNumber: type: string minLength: 4 maxLength: 17 description: >- Customer's bank account number. We mask all digits except the last four digits. routingNumber: type: string minLength: 9 maxLength: 9 description: > 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. secureToken: $ref: '#/components/schemas/secureTokenSummary' required: - type - nameOnAccount - accountNumber - routingNumber description: Object that contains the customer's account details. - type: object properties: type: type: string enum: - pad description: 'Discriminator value: pad' nameOnAccount: type: string minLength: 1 maxLength: 29 description: Customer's name. accountNumber: type: string minLength: 7 maxLength: 12 description: >- Customer's bank account number. We mask all digits except the last four digits. transitNumber: type: string minLength: 5 maxLength: 5 description: Five-digit code that represents the customer's banking branch. institutionNumber: type: string minLength: 3 maxLength: 3 description: Three-digit code that represents the customer's bank. secureToken: $ref: '#/components/schemas/secureTokenSummary' required: - type - nameOnAccount - accountNumber - transitNumber - institutionNumber description: Object that contains the customer's account details. discriminator: propertyName: type description: "Polymorphic object that contains bank account information.\n\nThe value of the type field determines which variant you should use:\n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" title: BankTransferPaymentBankAccount RefundSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the refund. title: RefundSummaryStatus RefundSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > 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. title: RefundSummaryResponseCode refundSummary: type: object properties: refundId: type: string minLength: 10 maxLength: 10 description: Unique identifier of the refund. dateTime: type: string format: date-time description: Date and time that the refund was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the refund. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/RefundSummaryStatus' description: Current status of the refund. responseCode: $ref: '#/components/schemas/RefundSummaryResponseCode' description: > 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. responseMessage: type: string minLength: 1 maxLength: 48 description: Description of the response from the processor. link: $ref: '#/components/schemas/link' required: - refundId - dateTime - currency - amount - status - responseCode - responseMessage description: Object that contains information about a refund. title: refundSummary bankTransferReturnSummary: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that our gateway assigned to the payment. date: type: string format: date description: The date that the check was returned. returnCode: type: string description: The NACHA return code. returnReason: type: string description: The reason why the check was returned. represented: type: boolean description: Indicates whether the return has been re-presented. closed: type: boolean description: >- Indicates whether the merchant accepted an alternative payment method to complete the payment. link: $ref: '#/components/schemas/link' required: - paymentId - date - returnCode - returnReason - represented - closed description: Object that contains information about a return. title: bankTransferReturnSummary PaymentSummaryStatus: type: string enum: - ready - pending - declined - complete - referral - pickup - reversal - returned - admin - expired - accepted description: Current status of the payment. title: PaymentSummaryStatus PaymentSummaryResponseCode: type: string enum: - A - D - E - P - R - C description: > 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. title: PaymentSummaryResponseCode paymentSummary: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier of the payment. dateTime: type: string format: date-time description: Date and time that the payment was processed. currency: $ref: '#/components/schemas/currency' amount: type: integer format: int64 description: >- Amount of the payment. This value is in the currency’s lowest denomination, for example, cents. status: $ref: '#/components/schemas/PaymentSummaryStatus' description: Current status of the payment. responseCode: $ref: '#/components/schemas/PaymentSummaryResponseCode' description: > 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. responseMessage: type: string minLength: 1 maxLength: 48 description: Response description from the processor. link: $ref: '#/components/schemas/link' required: - paymentId - dateTime - currency - amount - status - responseCode description: Object that contains information about a payment. title: paymentSummary BankTransferResultType: type: string enum: - payment - refund - unreferencedRefund - accountVerification description: Type of transaction. title: BankTransferResultType BankTransferResultStatus: type: string enum: - ready - pending - declined - complete - admin - reversal - returned description: "Status of the transaction. The value is one of the following: \n- `ready` - Successful transaction. We added the payment to the open batch. \n- `pending` - Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. \n-\t`declined` - Unsuccessful transaction. The customer's bank declined the transfer. \n-\t`complete` - Successful transaction. The funds have moved to the merchant’s bank account. \n-\t`admin` - Transaction under review. We have flagged an issue with the transaction. \n-\t`reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. \n-\t`returned` - Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the **returns** object. \n" title: BankTransferResultStatus bankTransferResult: type: object properties: type: $ref: '#/components/schemas/BankTransferResultType' description: Type of transaction. status: $ref: '#/components/schemas/BankTransferResultStatus' description: "Status of the transaction. The value is one of the following: \n- `ready` - Successful transaction. We added the payment to the open batch. \n- `pending` - Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. \n-\t`declined` - Unsuccessful transaction. The customer's bank declined the transfer. \n-\t`complete` - Successful transaction. The funds have moved to the merchant’s bank account. \n-\t`admin` - Transaction under review. We have flagged an issue with the transaction. \n-\t`reversal` - Transaction cancelled. The transaction was cancelled, and we removed the transaction from the open batch. \n-\t`returned` - Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the **returns** object. \n" authorizedAmount: type: integer format: int64 description: | Amount of the transaction. **Note:** The amount is negative for a refund. currency: $ref: '#/components/schemas/currency' responseCode: type: string description: | Response from the processor. - `A` - The processor approved the transaction. - `D` - The processor declined the transaction. responseMessage: type: string minLength: 1 maxLength: 48 description: Description of the response from the processor. processorResponseCode: type: string description: Original response code that the processor sent. required: - type - status - responseCode description: Object that contains information about the transaction. title: bankTransferResult bankTransferPayment: type: object properties: paymentId: type: string minLength: 10 maxLength: 10 description: Unique identifier that we assigned to the payment. processingTerminalId: type: string minLength: 4 maxLength: 50 description: Unique identifier that we assigned to the terminal. order: $ref: '#/components/schemas/bankTransferPaymentOrder' customer: $ref: '#/components/schemas/bankTransferCustomer' bankAccount: $ref: '#/components/schemas/BankTransferPaymentBankAccount' description: "Polymorphic object that contains bank account information.\n\nThe value of the type field determines which variant you should use:\n-\t`ach` - Automated Clearing House (ACH) details\n-\t`pad` - Pre-authorized debit (PAD) details\n" refunds: type: array items: $ref: '#/components/schemas/refundSummary' description: List of refunds issued against the payment. returns: type: array items: $ref: '#/components/schemas/bankTransferReturnSummary' description: List of returns issued against the payment. representment: $ref: '#/components/schemas/paymentSummary' description: >- Object that contains details about the re-presented payment linked to the return. transactionResult: $ref: '#/components/schemas/bankTransferResult' customFields: type: array items: $ref: '#/components/schemas/customField' description: | Array of customField objects. required: - paymentId - processingTerminalId - order - bankAccount - transactionResult description: >- Object that contains information about the sale and the customer's bank details. title: bankTransferPayment ErrorsItems: type: object properties: message: type: string description: Error message title: ErrorsItems ``` ### Example response ### Response (201) ```json { "paymentId": "M2MJOG6O2Y", "processingTerminalId": "1234001", "order": { "amount": 4999, "currency": "USD", "orderId": "OrderRef6543", "breakdown": { "subtotal": 4347, "taxes": [ { "name": "Sales Tax", "rate": 5, "amount": 217 } ], "tip": { "type": "percentage", "amount": 435, "percentage": 10 } }, "dateTime": "2024-07-02T15:30:00Z", "description": "Large Pepperoni Pizza" }, "bankAccount": { "type": "ach", "accountNumber": "****3159", "nameOnAccount": "Sarah Hazel Hopper", "routingNumber": "053200983", "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": "sarah.hopper@example.com" } ] }, "customFields": [ { "name": "yourCustomField", "value": "abc123" } ] } ``` ## Test cases Before you run test cases, read the [Payments](/test/test-your-integration/payments) page in Test Your Integration. ### Run a sale with bank account details Send a POST request to the following endpoint: POST [https://api.uat.payroc.com/v1/bank-transfer-payments](https://api.uat.payroc.com/v1/bank-transfer-payments) **Example response** ```json { "channel": "POS", "processingTerminalId": "3204001", "operator": "Davi-CHP", "order": { "orderId": "CC-12", "description": "BT ACH - Sale with CC", "currency": "USD", "amount": 9700 }, "paymentMethod": { "type": "ach", "accountType": "checking", "secCode": "web", "nameOnAccount": "Davi", "accountNumber": "49100130", "routingNumber": "292735277" } } ```