BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Create ECP Transaction

post https://sandbox.bluesnap.com/services/2/alt-transactions

The Create ECP Transaction request performs a transaction (purchase) using the ACH/ECP payment method. For more information about this payment method, see ACH/ECP.

👍

Prerequisite: Enable the ECP payment method in your account

In the Merchant Portal, go to Checkout Page > Payment Methods and select Show in the menu next to the ECP payment method. Click Submit to save your change.

Try it in the API Explorer

Request Content

Send an alt-transaction object with the following:
     merchant-transaction-id string    optional
     soft-descriptor string    optional
     amount decimal    required
     currency string    required
     tax-reference string    optional
     vendors-info container    required if using marketplace vendor(s) (see vendors-info)
     payer-info container    required if vaulted-shopper-id is not sent (see payer-info)
     vaulted-shopper-id integer    required if payer-info is not sent
     pf-token     string    required if using Secured Payment Collector
     ecp-transaction container    required if pf-token is not sent (see ecp-transaction)
     authorized-by-shopper boolean    required, value must be true
     transaction-meta-data container    optional (see transaction-meta-data)
     transaction-fraud-info container    optional (see transaction-fraud-info)

Response Details

If successful, the response HTTP status code is 200 OK.
The response contains an alt-transaction resource (see alt-transaction) with the request properties plus these additions:

      transaction-id
     vaulted-shopper-id
     processing-info
     fraud-result-info
     vendors-info

Examples

Request Examples

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
   <transaction-fraud-info>
      <fraud-session-id>1234</fraud-session>
      <customer-id>121341</customer-id>
      <customer-creation-date>2021-08-05</customer-creation-date>
   </transaction-fraud-info>
</alt-transaction>'

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <vaulted-shopper-id>19563598</vaulted-shopper-id>
   <ecp-transaction />
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <merchant-transaction-id>unique_001</merchant-transaction-id>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <vendors-info>
     <vendor-info>
       <vendor-id>10398032</vendor-id>
     </vendor-info>
   </vendors-info>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <vaulted-shopper-id>19569774</vaulted-shopper-id>
   <ecp-transaction>
        <account-type>CONSUMER_SAVINGS</account-type>
        <public-account-number>99993</public-account-number>
        <public-routing-number>75151</public-routing-number>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
  <pf-token>eba795a8ec2a8e7754afe7a69b0a0869fba0e6daec01e2d81e1ccbb6771c24ab_</pf-token>
  <soft-descriptor>ABC COMPANY</soft-descriptor>
  <amount>100.00</amount>
  <currency>USD</currency>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <phone>1234567890</phone>
  </payer-info>
  <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>120.50</amount>
   <currency>USD</currency>
    <tax-reference>048deff0-a285-47e1-bc39-42f79bf0095b</tax-reference>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>'

Response Examples

<?xml version="1.0" encoding="UTF-8"?>
<alt-transaction xmlns="http://ws.plimus.com">
   <transaction-id>38504784</transaction-id>
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
  <vaulted-shopper-id>21614931</vaulted-shopper-id>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <processing-info>
      <processing-status>PENDING</processing-status>
   </processing-info>
  <fraud-result-info/>
</alt-transaction>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
    <transaction-id>38503224</transaction-id>
    <soft-descriptor>ABC COMPANY</soft-descriptor>
    <amount>1.00</amount>
    <currency>USD</currency>
    <vaulted-shopper-id>19568536</vaulted-shopper-id>
    <ecp-transaction>
        <account-number>4099999992</account-number>
        <routing-number>011075150</routing-number>
        <account-type>CONSUMER_CHECKING</account-type>
    </ecp-transaction>
    <processing-info>
        <processing-status>PENDING</processing-status>
    </processing-info>
</alt-transaction>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
    <merchant-transaction-id>unique_001</merchant-transaction-id>
    <transaction-id>38504788</transaction-id>
    <amount>100.00</amount>
    <currency>USD</currency>
    <payer-info>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <zip>12345</zip>
        <phone>1234567890</phone>
    </payer-info>
    <ecp-transaction>
        <account-number>4099999992</account-number>
        <routing-number>011075150</routing-number>
        <account-type>CONSUMER_CHECKING</account-type>
    </ecp-transaction>
    <processing-info>
        <processing-status>PENDING</processing-status>
    </processing-info>
</alt-transaction>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
  <transaction-id>1015601047</transaction-id>
  <vendor-info>
    <vendor-id>10398032</vendor-id>
    <commission-percent>20</commission-percent>
  </vendor-info>
  <vendors-info>
    <vendor-info>
      <vendor-id>10398032</vendor-id>
      <commission-percent>20</commission-percent>
    </vendor-info>
  </vendors-info>
  <soft-descriptor>ABC COMPANY</soft-descriptor>
  <amount>100.00</amount>
  <currency>USD</currency>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <zip>12345</zip>
    <phone>1234567890</phone>
  </payer-info>
  <vaulted-shopper-id>22327453</vaulted-shopper-id>
  <ecp-transaction>
    <account-number>4099999992</account-number>
    <routing-number>011075150</routing-number>
    <account-type>CONSUMER_CHECKING</account-type>
  </ecp-transaction>
  <processing-info>
    <processing-status>PENDING</processing-status>
  </processing-info>
</alt-transaction>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
    <transaction-id>38505326</transaction-id>
    <soft-descriptor>ABC COMPANY</soft-descriptor>
    <amount>100.00</amount>
    <currency>USD</currency>
    <payer-info>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <zip>12345</zip>
        <phone>1234567890</phone>
    </payer-info>
    <vaulted-shopper-id>19570138</vaulted-shopper-id>
    <ecp-transaction>
        <account-type>CONSUMER_CHECKING</account-type>
        <public-account-number>99992</public-account-number>
        <public-routing-number>75150</public-routing-number>
    </ecp-transaction>
    <processing-info>
        <processing-status>PENDING</processing-status>
    </processing-info>
</alt-transaction>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<alt-transaction xmlns="http://ws.plimus.com">
    <transaction-id>38504834</transaction-id>
    <soft-descriptor>ABC COMPANY</soft-descriptor>
    <amount>100.00</amount>
    <currency>USD</currency>
    <vaulted-shopper-id>19569774</vaulted-shopper-id>
    <ecp-transaction>
        <public-account-number>99993</public-account-number>
        <public-routing-number>75151</public-routing-number>
        <account-type>CONSUMER_SAVINGS</account-type>
    </ecp-transaction>
    <processing-info>
        <processing-status>PENDING</processing-status>
    </processing-info>
</alt-transaction>

Back to Top

Example Descriptions

Create basic ECP transaction with payer info

This example shows a basic create ECP Transaction request, including the minimum required fields to process an ACH/ECP transaction with basic information about the shopper.

For all ACH transactions, you must obtain permission from the shopper to debit their account, for example by showing a checkbox with the following wording on your checkout page. "I authorize this Electronic Check (ACH) transaction and agree to this debit of my account."

Include the authorized-by-shopper element with the value set to true to indicate that you have obtained the shopper's permission.

Create ECP transaction with vaulted shopper

To perform a Create ECP Transaction with an existing vaulted shopper (with saved ECP account details), you must include the vaulted-shopper-id property within the alt-transaction resource in your request.

Above is an example of a Create ECP Transaction request with an existing vaulted shopper with the ID 19563598. When you use a vaulted shopper, the ecp-transaction property can be left empty, as shown in the example.

Create ECP transaction with Merchant Transaction ID

You may wish to assign your own ID to each transaction, for example in order to track the transactions in your own internal systems. To do this, you must include the merchant-transaction-id property within the alt-transaction resource in your request.

Above is an example of a request that includes a Merchant Transaction ID.

Create ECP transaction with Vendors Info

This example shows a Create ECP transaction request within a marketplace. Include vendors-info in the request to process a transaction involving one or more vendors. For more details, see Processing Transactions.

Create ECP transaction with multiple vaulted ACH

This example shows a Create ECP transaction request when the customer has more than one ACH account. When your vaulted shopper has multiple ACH accounts use ecpTransaction to identify which ACH account to use for the transaction.

Create ECP transaction with a token

This example shows a Create ECP transaction request with tokenized bank details. When you use BlueSnap's Secured Payment Collector, you can securely capture and tokenize the shopper's sensitive banking details. After the shopper's banking details have been submitted to BlueSnap and associated with the token, you can process the transaction by including the token within the pf-token property.


Back to Top

API Explorer

To test out a call, click the Test in the API Explorer button below.
Then just paste in the XML portion of the request and click Try it!

Tip: Copy the XML portion from one of the examples above, or use the XML code below as a starting point. You can enter different parameters to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.

<alt-transaction xmlns="http://ws.plimus.com">
   <soft-descriptor>ABC COMPANY</soft-descriptor>
   <amount>100.00</amount>
   <currency>USD</currency>
   <payer-info>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <zip>12345</zip>
      <phone>1234567890</phone>
   </payer-info>
   <ecp-transaction>
      <account-number>4099999992</account-number>
      <routing-number>011075150</routing-number>
      <account-type>CONSUMER_CHECKING</account-type>
   </ecp-transaction>
   <authorized-by-shopper>true</authorized-by-shopper>
</alt-transaction>
Language
Credentials
:
Click Try It! to start a request and see the response here!