Skip to main content

Transfer Funds to Sellers

In this guide, we will show how marketplaces and other exchanges can transfer funds to and from seller accounts.

PublicSquare offers two transaction types for this use case:

TypeDescription
payment_transferPayment transfers are used to send funds to seller accounts from an existing payment. For instance, if you charge a customer $300, you can transfer $100 to three different sellers.
refund_transferRefund transfers are used to retrieve funds from seller accounts from an existing refund referencing the original payment_transfer. For instance, if you refund a customer $300, you can transfer $100 from three different sellers.

Getting Started​

To get started, you will need a PublicSquare Account.

Get your Secret Key​

Next you will need your Secret Key. Go to your Developers section and click Reveal for your Secret Key and copy the value.

Save the Secret Key as it will be used in the next steps of this guide.

Transfer Funds to Sellers​

In order to move money from our captured payment to a seller's account, we will need a payment transfer. Each payment may have exactly one payment transfer, whose total amount cannot exceed the payment's captured amount.

We will be using information from our Process Card Payments and Onboard Sellers guides:

First, grab the payment id:

Payment
{
  "id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  ...
}

Also our seller account id:

Seller Account
{
  "id": "acc_w6dogDaHuU6h1N5e5vfXLUYf",
  "name": "Test Seller",
  "type": "seller",
  ...
}

Create a Payment Transfer​

We will make a call to the Create Payment Transfer endpoint:

Create a Payment Transfer
curl 'https://api.publicsquare.com/payment-transfers' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "payment_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
  "currency": "USD",
  "items": [{
    "seller_account_id": "acc_w6dogDaHuU6h1N5e5vfXLUYf",
    "amount": 1000,
    "transfer_fee": 100
  }]
}'
The amount is provided in cents. 1000 is the equivalent of $10.00

Payment Transfer Response​

You should see a payment transfer result similar to:

{
  "id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  "status": "successful",
  "payment_id": "pmt_2YKewBonG4tgk12MheY3PiHDy",
  "transaction_id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
  "total_amount": 1000,
  "currency": "USD",
  "items": [{
    "id": "trfi_7yFLQWACr3DYDSz1xpoEAVfdq",
    "seller_account_id": "acc_w6dogDaHuU6h1N5e5vfXLUYf",
    "amount": 1000,
    "transfer_fee": 100
  }],
  "transaction": {
    "id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
    "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
    "environment": "test",
    "status": "successful",
    "amount": -1000,
    "fee_amount": 100,
    "net_amount": -900,
    "currency": "USD",
    "type_id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
    "type": "payment_transfer",
    "processor": "nuvei",
    "processor_id": "7110000000010554769",
    "created_at": "2024-06-30T01:02:29.212Z",
    "modified_at": "2024-06-30T01:02:29.212Z"
  },
  "created_at": "2024-06-30T01:02:29.212Z",
  "modified_at": "2024-06-30T01:02:29.212Z"
}
For each item in the payment transfer, a payment transaction will be created in the seller's account.

Transfer Funds from Sellers​

After you have refunded a customer, you may need to transfer funds from a seller back into your account. In order to do this, we will create a refund transfer. Each refund may have exactly one refund transfer, who's total amount cannot exceed the refund amount.

We will be using information from our Refund Payment guide:

To start, let's get the refund id:

Refund
{
  "id": "rfd_2YKewBonG4tgk12MheY3PiHDy",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  ...
}

We will also be referencing our payment transfer's id and each item's id:

Payment Transfer
{
  "id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  ...
  "items": [{
    "id": "trfi_7yFLQWACr3DYDSz1xpoEAVfdq",
    "seller_account_id": "acc_w6dogDaHuU6h1N5e5vfXLUYf",
    "amount": 1000,
    "transfer_fee": 100
  }]
}

Create a Refund Transfer​

We will make a call to the Create Refund Transfer endpoint:

Create a Refund Transfer
curl 'https://api.publicsquare.com/refund-transfers' \
-X 'POST' \
-H 'X-API-KEY: <SECRET_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
  "refund_id": "rfd_2YKewBonG4tgk12MheY3PiHDy",
  "payment_transfer_id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
  "items": [{
    "payment_transfer_item_id": "trfi_7yFLQWACr3DYDSz1xpoEAVfdq",
    "amount": 1000,
    "transfer_fee": 100
  }]
}'
The amount is provided in cents. 1000 is the equivalent of $10.00

Refund Transfer Response​

You should see a refund transfer result similar to:

{
  "id": "trnf_6Qy74FeCJxoJeXetcyTvbSnVF",
  "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
  "environment": "test",
  "status": "successful",
  "refund_id": "rfd_2YKewBonG4tgk12MheY3PiHDy",
  "payment_transfer_id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
  "transaction_id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
  "total_amount": 1000,
  "currency": "USD",
  "items": [{
    "id": "trfi_4iarm41gZ1qyxDoGfEEMXyryJ",
    "seller_account_id": "acc_w6dogDaHuU6h1N5e5vfXLUYf",
    "payment_transfer_item_id": "trfi_7yFLQWACr3DYDSz1xpoEAVfdq",
    "amount": 1000,
    "transfer_fee": 100
  }],
  "transaction": {
    "id": "trx_95rvMJvAVeG68W4NtLdfkN3LG",
    "account_id": "acc_B518niGwGYKzig6vtrRVZGGGV",
    "environment": "test",
    "status": "successful",
    "amount": 1000,
    "fee_amount": 100,
    "net_amount": 900,
    "currency": "USD",
    "type_id": "trnf_7yFLQWACr3DYDSz1xpoEAVfdq",
    "type": "refund_transfer",
    "processor": "nuvei",
    "processor_id": "7110000000010554769",
    "created_at": "2024-06-30T01:02:29.212Z",
    "modified_at": "2024-06-30T01:02:29.212Z"
  },
  "created_at": "2024-06-30T01:02:29.212Z",
  "modified_at": "2024-06-30T01:02:29.212Z"
}
For each item in the refund transfer, a refund transaction will be created in the seller's account.

Conclusion​

Following this guide, you have successfully moved funds to and from a seller's account.

Follow these guides to learn more: