Marketplaces

Payouts is a collection of APIs for sending cash to bank accounts. Payouts can be used to create marketplace platforms and other systems that require funds to be sent programmatically.

Overview

Sellers on your marketplace aren’t required to have their own Pin Payments account, they will be represented as a Recipient. Running a marketplace using Pin Payments works like this:

1. You collect the marketplace seller’s or stakeholder’s details, including their BSB and bank account number, and create a Recipient to represent them.
2. After you process card transactions from customers, the proceeds are attributed to your Pin Payments account balance.
3. Using the Transfers API, your marketplace transfers the appropriate amount of funds to the recipient, and optionally an amount to your own bank account.

1. Roland Robot
   8765 4321
   645 312
   

2. $75

3. $72

Setting up your account

In order to accumulate funds for transfer to third parties (recipients), you must pause the automatic transfers that Pin Payments sends to your bank account. To do this log in to your account and set your transfer schedule to Manual from the Transfers area of your dashboard.

Funding your account balance

The only way to accumulate funds in your Pin Payments balance is by processing charges with credit or debit cards (we recommend using our Hosted Fields integration for securely handling your customer’s card data). Your account will be credited with the nett proceeds from each sale, and funds attributed to your available balance according to your settlement schedule.

Note: We also offer a free Subscriptions API which allows you to set up payment plans and charge customers’ cards on a recurring basis, if this forms part of your marketplace model.

Defining rules for your marketplace

Since every marketplace is different, the logic for splitting payments and the schedule for transferring funds will vary.

Pin Payments provides your marketplace with the means to charge customers cards and transfer funds to sellers bank accounts. It’s your responsibility to keep track of the amount your sellers are entitled to receive by creating transfers.

You can transfer funds to recipients as frequently as every day, but you may prefer to run this task less frequently, such as every week.

Transferring funds to a third party

This example uses Pin.js to securely store bank account details and receive an identifying token. Bank account tokens are not required to create recipients, but we recommend that you use them to provide additional security around your users’ bank account details.

Include Pin.js

Place the following code in the head section of the web page that collects the bank account details:

<script src='https://cdn.pinpayments.com/pin.v2.js'></script>

Create a bank account form

This form is what your recipients use to create a bank account token for payouts. The lack of name attributes on the input elements prevents them from being submitted to your server.

<form action='/url_to_your_server_to_create_a_recipient' class='pin' method='post'>
  <div class='errors' style='display:none'>
    <h3></h3>
    <ul></ul>
  </div>
  <fieldset>
    <legend>Bank Account Details</legend>
    <!--
      The lack of 'name' attributes on these inputs prevents
      the browser from submitting them to your server
    -->
    <label for='name'>Name</label>
    <input id='name'>
    <label for='bsb'>BSB</label>
    <input id='bsb'>
    <label for='number'>Account Number</label>
    <input id='number'>
  </fieldset>
  <input type='submit' value='Update bank account details'>
</form>

Add the submit event handler

The submit handler prevents default submission, retrieves a bank account token from Pin Payments, adds the token to the form, and then re-submits the form to your server. This example uses jQuery, but you don’t have to—Pin.js itself does not depend on any front-end library.

// 1. Wait for the page to load
$(function() {

  // 2. Create an API object with your publishable api key, and
  // specifying 'test' or 'live'.
  //
  // Be sure to use your live publishable key with the live api, and
  // your test publishable key with the test api.
  var pinApi = new Pin.Api('your publishable key', 'test');

  var form = $('form.pin'),
      submitButton = form.find(":submit"),
      errorContainer = form.find('.errors'),
      errorList = errorContainer.find('ul'),
      errorHeading = errorContainer.find('h3');

  // 3. Add a submit handler to the form which calls Pin.js to
  // retrieve a bank account token, and then add that token to the form and
  // submit the form to your server.
  form.submit(function(e) {
    e.preventDefault();

    // Clear previous errors
    errorList.empty();
    errorHeading.empty();
    errorContainer.hide();

    // Disable the submit button to prevent multiple clicks
    submitButton.attr({disabled: true});

    // Fetch details required for the createBankAccountToken call to Pin Payments
    var bank_account = {
      name:   $('#name').val(),
      bsb:    $('#bsb').val(),
      number: $('#number').val()
    };

    // Request a token for the bank account from Pin Payments
    pinApi.createBankAccountToken(bank_account).then(onSuccess, onError).done();
  });

  function onSuccess(bankAccount) {
    // Add the bank account token to the form.
    //
    // Once you have the bank account token on your server you can use your
    // private key and the recipients API to save the recipient details.
    $('<input>')
      .attr({type: 'hidden', name: 'bank_account_token'})
      .val(bankAccount.token)
      .appendTo(form);

    // Resubmit the form to the server
    //
    // Only the bank_account_token input will be submitted to your server.
    // The browser ignores the original form inputs because they don't
    // have their 'name' attribute set.
    form.get(0).submit();
  }

  function onError(response) {
    errorHeading.text(response.error_description);

    if (response.messages) {
      $.each(response.messages, function(index, paramError) {
        $('<li>')
          .text(paramError.param + ": " + paramError.message)
          .appendTo(errorList);
      });
    }

    errorContainer.show();

    // Re-enable the submit button
    submitButton.removeAttr('disabled');
  };
});

Create or update a recipient

Now that you have the bank account token, it can be used to either create a new recipient or update an existing recipient using the recipients API.

curl https://test-api.pinpayments.com/1/recipients -u your-secret-api-key: \
 -d "email=roland@pinpayments.com" \
 -d "name=Mr Roland Robot" \
 -d "bank_account_token=ba_nytGw7koRg23EEp9NTmz9w"

Transferring funds to yourself

To use Payouts, your Pin Payments account must be configured to use manual transfers, meaning you will no longer receive automated daily transfers into your designated bank account. Depending on your business model, you (the platform owner) might retain a percentage of sales. To access funds in the balance of your Pin Payments account, you will have to initiate a transfer to yourself.

Checking your balance

curl https://test-api.pinpayments.com/1/balance -u your-secret-api-key:

{
  "response": {
    "available": [
      {
        "amount": 400,
        "currency": "AUD"
      }
    ],
    "pending": [
      {
        "amount": 1200,
        "currency": "AUD"
      }
    ]
  }
}

In this example, there is $4.00 AUD available for transfers. The pending amount isn’t available as it’s still during your settlement delay.

Transfer funds to your bank account

To send funds to your designated bank account, simply initiate a transfer using the transfers API and set the recipient parameter to “self”. Pin Payments will then initiate the transfer to your bank account.

curl https://test-api.pinpayments.com/1/transfers -u your-secret-api-key: \
 -d "amount=400" \
 -d "currency=AUD" \
 -d "description=Transferring remaining balance" \
 -d "recipient=self"

Dealing with failed transfers

Our banking partners inform us of failed transfers (due to an invalid bank account number, for example) within fourteen days of processing.

We’ll email you in the event that one of your transfers fails, and your balance will be credited the returned funds. Generally you’ll want to contact your user and have them provide updated bank account details, at which point you can create a new transfer through the API.