Submit eCheck Payments using the API

You can submit eCheck payments through the Payrix Pro API using POST /txns. You can enter new account information or process payments with an existing customer's tokenized account as the payment method.

Submit eCheck Payments with a New Payment Method

The following steps demonstrate how to submit an eCheck payment using a new payment method that hasn't been stored with Payrix Pro. This approach is useful when you don't plan to store payment information, such as for one-time eCheck payments, with Payrix Pro:

Create a POST https://test-api.payrix.com/txns request and include a payload with the following fields:

BASH

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

JSON

{
  "merchant": "t1_mer_123abc4d567890efg1h2i34",
  "type": "7",
  "origin": "2",
  "payment": {
      "method": "8",
      "number": "123456789",
      "routing": "123456789"
  },
  "total": "10000",
  "first": "Joe",
  "last": "Smith"
}

Parameter		Description	Notes and Required Values
`merchant`		ID of the Merchant to pay.	N/A
`type`		The type of Transaction.	Required Value: `7`: eCheck Sale
`origin`		The origin of this Transaction. How the merchant received the payment information.	Default Value: `2`: Processed through an e-commerce system.
`payment`		The object containing the payment method information.	Canadian Merchants who are submitting electronic funds transfer (EFT) transactions should provide a nine-digit routing number in the format `0`+`{institution_number}`+`{transit_number}`.
	`method`	The payment method associated with this Transaction, including the account details.	Valid Values: `8`: Personal checking account `9`: Personal savings account `10`: Corporate checking account `11`: Corporate savings account
	`number`	The bank account number.	Sandbox Testing Value: `123456789`
	`routing`	The bank account routing number.	Sandbox Testing Value: `123456789`
`total`		Total amount to charge, in cents.	Note: `total` is specified as an integer in cents and does not accept decimal and punctuation values. Example: `10000` = $100.00
`first`		Payer's first name.	Note: Either `first` or `last` is required.
`last`		Payer's last name.	Note: Either `first` or `last` is required.

Submit the request. A successful 200 OK response contains details about the payment transaction:

JSON

{
    "response": {
        "data": [
            {
                "payment": {
                    "id": "g123a456bc78901.",
                    "method": 8,
                    "number": "6789",
                    "routing": "6789",
                    "bin": null,
                    "payment": null,
                    "lastChecked": null,
                    "last4": null,
                    "mask": null,
                    "plaidConsumerAccount": null
                },
                "id": "t1_txn_66f...",
                "created": "2024-09-23 16:09:37.6355",
                "modified": "2024-09-23 16:09:39.4647",
                "creator": "t1_log_654...",
                ...
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

(Optional) Store the id value, which is the ID of the transaction. You can use it to check the transaction’s status at a later time using GET /txns/{id}.

Result: The eCheck payment is successfully submitted to the Payrix Pro platform using a customer’s new checking account as the payment method.

Tip

Because the status updates within a few hours, consider setting up a job that checks for regular updates.

Submit eCheck Payments with a Payment Token

You can also submit an eCheck payment using an existing tokenized payment method. The payment token must be an eCheck account, otherwise, the request to submit the eCheck payment will fail.

The following steps demonstrate how to use an existing customer’s payment token to submit an eCheck payment.

Verify the Token Payment Method

eCheck payment tokens are created using POST /tokens with payment.method set to a valid eCheck value, such as 8 for a personal checking account.

To verify a payment token as suitable for eCheck:

Create a GET /tokens?expand[payment][] request.

Include the SEARCH header value of token[equals]={tokenId} to return the specific token.

BASH

GET /tokens?expand[payment][] HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
SEARCH: token[equals]={token}

Submit the request. A successful 200 OK response looks similar to the following example.
Note: If the response.data.payment.method field is 8, 9, 10, or 11, then the token can be used for eCheck payments:

JSON

{
    "response": {
        "data": [
            {
                "payment": {
                    "id": "g123a456bc78901",
                    "method": 8,
                    "number": "1111",
                    "routing": "1111",
                    "payment": null,
                    "lastChecked": null,
                    "last4": null,
                    "mask": null,
                    "plaidConsumerAccount": null
                }
            }
        ]
    }
}

Create a POST /txns request and include a payload with the following fields:

BASH

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

JSON


{
  "merchant": "t1_mer_123abc4d567890efg1h2i34",
  "type": "7",
  "origin": "2",
  "token":"a12bc3d4e56f789g0h1ij23kl456789",
  "total": "10000"
}

Submit the request. A successful 200 OK response contains details about the payment transaction:

JSON

{
    "response": {
        "data": [
            {
                "id": "t1_txn_123abc4d567890efg1h2i34",
                "created": "2024-09-23 17:49:45.6275",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": "a12bc3d4e56f789g0h1ij23kl456789",
                "payment": "g123a456bc78901",
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Parameter	Description	Notes and Valid Values
`merchant`	ID of the Merchant to pay.
`type`	The type of Transaction.	Required Value: `7`: eCheck Sale
`origin`	The origin of this Transaction. How the merchant received the payment information.	Default Value: `2`: Processed through an e-commerce system.
`token`	The ID from the existing customer’s payment token.	N/A
`total`	Total amount to charge, in cents.	Note: `total` is specified as an integer in cents and does not accept decimal and punctuation values. Example: `10000` = $100.00

Result: The eCheck payment is successfully submitted to the Payrix Pro platform using a customer’s existing payment token as the payment method.

Submit and Tokenize eCheck Payments with a New Payment Method

You can also submit a first-time customer’s eCheck payment and tokenize their account information to streamline future payments. The following steps outline how to submit an eCheck payment using a new payment method that hasn't been stored with Payrix Pro, and you’d like to store the payment information for future use:

Create a POST https://test-api.payrix.com/txns request and include a payload with the following fields:

BASH

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

JSON

{
  "merchant": "t1_mer_123abc4d567890efg1h2i34",
  "type": "7",
  "origin": "2",
  "token": {
      "payment":{
          "method": "8",
          "number": "123456789",
          "routing": "123456789"
      },
      "customer":{
          "first": "Joe",
          "last": "Smith"
      }
  },
  "total": "10000"
}

Parameter			Description	Notes and Required Values
`merchant`			ID of the Merchant to pay.	N/A
`type`			The type of Transaction.	Required Value: `7`: eCheck Sale
`origin`			The origin of this Transaction. How the merchant received the payment information.	Default Value: `2`: Processed through an e-commerce system.
`token`			The object where the token data is configured.	N/A
	`payment`		The object containing the payment method information.	Canadian Merchants who are submitting electronic funds transfer (EFT) transactions should provide a nine-digit routing number in the format `0`+`{institution_number}`+`{transit_number}`.
		`method`	The payment method associated with this Transaction, including the account details.	Valid Values: `8`: Personal checking account `9`: Personal savings account `10`: Corporate checking account `11`: Corporate savings account
		`number`	The bank account number.	Sandbox Testing Value: `123456789`
		`routing`	The bank account routing number.	Sandbox Testing Value: `123456789`
	`customer`		The object containing the customer name associated with the payment account.	N/A
		`first`	Payer's first name.	N/A
		`last`	Payer's last name.	N/A
`total`			Total amount to charge, in cents.	Note: `total` is specified as an integer in cents and does not accept decimal and punctuation values. Example: `10000` = $100.00

JSON

{
    "response": {
        "data": [
            {
                "token": {
                    "customer": {
                        "id": "t1_cus_123abc4d567890efg1h2i34",
                        "created": "2024-09-23 17:35:18.0347",
                        ...
                    },
                    "payment": {
                        "id": "g123a456bc78901",
                        "method": 8,
                        "number": "6789",
                        "routing": "6789",
                        ...
                    },
                    "id": "t1_tok_123abc4d567890efg1h2i34",   //  New Token ID
                    "created": "2024-09-23 17:35:18.0428",
                    "creator": "t1_log_123abc4d567890efg1h2i34",
                    "modifier": "t1_log_123abc4d567890efg1h2i34",
                    "token": "a12bc3d4e56f789g0h1ij23kl456789",   // New Token value
                    ...
                },
                "id": "t1_txn_123abc4d567890efg1h2i34",  // New Transaction ID
                "created": "2024-09-23 17:35:18.0465",
                "modified": "2024-09-23 17:35:19.8753",
                ...
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Result: The eCheck payment is successfully submitted to the Payrix Pro platform using a customer’s new checking account as the payment method. This payment method is also successfully tokenized and associated with the customer for future eCheck payments.