BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Processing Transactions

Learn how to process transactions on behalf of your vendors.
If you have questions after reading this guide, check out our FAQs page.

As the Marketplace Merchant, you send transactions for processing on behalf of your vendors. Remember that a vendor must have a processing status of Active to have transactions processed.

This section covers the following topics:

Supported payment methods

  • Cards
  • Wallets (Apple Pay, Google Pay™, Visa Checkout)
  • ACH/eCheck
  • iDEAL
  • Local Bank Transfer
  • SEPA Direct Debit
  • Sofort

One-time transactions

Processing one-time transactions overview

For each vendor involved in the one-time transaction, include their vendor ID in the request (shown below). The vendor ID connects the transaction to you and your vendor(s), and it is included as part of the payout calculation.

You can link up to 500 vendors to the same transaction.

{
  "vendorsInfo": {
    "vendorInfo": [
      {"vendorId": "10398032"}
    ]
  }
  ...
}

{
  "vendorsInfo": {
    "vendorInfo": [
      {"vendorId": "10398032"}, 
      {"vendorId": "10398030"}
    ]
  }
  ...
}

<vendors-info>
    <vendor-info>
      <vendor-id>10398032</vendor-id>
    </vendor-info>
  </vendors-info>
  ...

<vendors-info>
    <vendor-info>
      <vendor-id>10398032</vendor-id>
    </vendor-info>
    <vendor-info>
      <vendor-id>10398030</vendor-id>
    </vendor-info>
  </vendors-info>
  ...

📘

Commission Split

The commission split occurs when the shopper's funds are captured.

Back to Top

Overriding commission rate in a transaction request

You can override the default commission rate (set in the Create or Update Vendor requests) of one or more vendors for a specific transaction. To override with either a percent or an amount (in the transaction currency), include commissionPercent or commissionAmount in the request, as shown below. 

{
  "vendorsInfo": {
    "vendorInfo": [
      {
        "vendorId": "10398032", 
        "commissionPercent": 30
      }
    ]
  }
  ...
}

{
  "vendorsInfo": {
    "vendorInfo": [
      {
        "vendorId": "10398032", 
        "commissionAmount": 40.75
      }
    ]
  }
  ...
}

<vendors-info>
    <vendor-info>
      <vendor-id>10398032</vendor-id>
      <commission-percent>30</commission-percent>
    </vendor-info>
  </vendors-info>
  ...

<vendors-info>
    <vendor-info>
      <vendor-id>10398032</vendor-id>
      <commission-amount>40.75</commission-amount>
    </vendor-info>
  </vendors-info>
  ...

Back to Top

Card & Wallet transactions

Auth and Capture

To do the authorization and capture in the same step, send an Auth Capture request. This payment flow is most notable for digital goods and physical goods that are in stock and are ready to be shipped immediately after the purchase. To link the transaction to one or more vendors, include vendorsInfo in the request body, as shown above in Processing one-time transactions overview.

Separate Auth and Capture

To separate the authorization and capture steps, send two separate requests: Auth Only and then Capture. You can link one or more vendors to the transaction by including vendorsInfo in the body of either request, as shown above in Processing one-time transactions overview. This payment flow is most notable if the goods or service is delivered after the time of the purchase.

Linking vendors to transaction in Auth Only request
This option is useful if you know who will deliver the goods or service right away and you plan to submit a single capture for the full authorization amount. In the Auth Only request, include vendorsInfo. In the Capture request, you can omit vendorsInfo.

Check out these examples: Auth Only - basic with vendors info and Capture - basic.

Linking vendors to transaction in Capture request
This option is useful if you need time after the initial authorization to identify who will deliver the goods or service. In the Auth Only request, omit vendorsInfo. In the Capture request, include vendorsInfo.

Check out these examples: Auth Only - basic with fraud info and Capture - with vendors info.

Note: If you include vendorsInfo in both the Auth Only and Capture requests, the vendor information sent in the Capture request overrides the information.

📘

Partial captures

To perform a partial capture with one or more vendors, include their information within vendorsInfo and include the amount to be captured within amount (see the example Capture - with amount and vendors info). If you don't pass vendor information in the Capture request, no vendors are linked to that capture and a commission split does not occur (any vendor information passed in the prior Auth Only request is ignored).

Note: To have partial captures enabled, contact your Implementation Specialist or Merchant Support.

ACH transactions

To process an ACH/ECP transaction involving one or more vendors, include vendorsInfo in the Create ECP Transaction request, as shown above in Processing one-time transactions overview.

Local Bank Transfer transactions

To send a Local Bank Transfer transaction involving one or more vendors, include vendorsInfo in the Create Local Bank Transfer Transfer request, as shown above in Processing one-time transactions overview.

Note: If the amount received is less than the order total, this is considered a short payment. If a short payment occurs, BlueSnap splits the payment based on the original commission split.

iDEAL transactions

To process an iDEAL transaction involving one or more vendors, include vendorsInfo in the Create iDEAL Transaction request, as shown above in Processing one-time transactions overview.

SEPA Direct Debit transactions

To process a SEPA Direct Debit transaction involving one or more vendors, include vendorsInfo in the Create SEPA DD Transaction request, as shown above in Processing one-time transactions overview.

Sofort transactions

To process a Sofort transaction involving one or more vendors, include vendorsInfo in the Create Sofort Transaction request, as shown above in Processing one-time transactions overview.

Back to Top

Subscriptions

With BlueSnap's Subscription Engine, recurring transactions run automatically based on the created plan schedule. First create a plan, then create a subscription with vendorsInfo (shown above). Each time the transaction is processed, a commission split is generated and added to your BlueSnap account.

With Merchant-Managed Subscriptions, you can manage your own subscription plans and recurring billing, then easily process the payments through BlueSnap. You will include the vendors’ information with each subscription charge so they can be associated with the transaction and the established commission split can be generated. To process the initial subscription charge, send a Create Merchant-Managed Subscription request with vendorsInfo (shown above). For subsequent charges, send a Create Merchant-Managed Subscription Charge request with vendorsInfo (shown above).

📘

Overriding a vendor's default commission rate for a transaction

Refer to Overriding commission rate for details.

Back to Top

Refunds & chargebacks

Refunds

To refund a marketplace transaction, send a Refund request. You can override a vendor's portion of the refund by including vendorsRefundInfo in the request (shown below). If this property is not included, the refund is based on the original commission split of vendors. 

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039319229 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 10,
  "vendorsRefundInfo": {
    "vendorRefundInfo": [
      {
        "vendorId": 10418276,
        "vendorAmount": 5
      },
      {
        "vendorId": 10415692,
        "vendorAmount": 4
      }
    ]
  }
}'

{
  "refundTransactionId": 1039319485,
  "amount": 10,
  "vendorsRefundInfo": {
    "vendorRefundInfo": [
      {
        "vendorId": 10418276,
        "vendorAmount": 5
      },
      {
        "vendorId": 10415692,
        "vendorAmount": 4
      }
    ]
  }
}

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039320309 \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<refund xmlns="http://ws.plimus.com">
  <amount>10</amount>
  <vendors-refund-info>
    <vendor-refund-info>
      <vendor-id>10418276</vendor-id>
      <vendor-amount>5</vendor-amount>
    </vendor-refund-info>
    <vendor-refund-info>
      <vendor-id>10415692</vendor-id>
      <vendor-amount>4</vendor-amount>
    </vendor-refund-info>
  </vendors-refund-info>
</refund>'

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<refund xmlns="http://ws.plimus.com">
  <refund-transaction-id>1039320725</refund-transaction-id>
  <amount>10</amount>
  <vendors-refund-info>
    <vendor-refund-info>
      <vendor-id>10418276</vendor-id>
      <vendor-amount>5</vendor-amount>
    </vendor-refund-info>
    <vendor-refund-info>
      <vendor-id>10415692</vendor-id>
      <vendor-amount>4</vendor-amount>
    </vendor-refund-info>
  </vendors-refund-info>
</refund>

This request refunds 10 dollars of the transaction, with 5 from vendor 10418276 and 4 from vendor 10415692.

Chargebacks

If BlueSnap is notified of a chargeback, we automatically issue a refund for the transaction amount. The refund is split between the Marketplace Merchant and the associated vendors according to the original commission split. Any chargeback fees are charged to the Marketplace Merchant.

Back to Top

Next: Reporting

Now that you've learned about how to process transactions, move on to learn about our reporting capabilities.

➔ Reporting