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.

Setting up your account

In order to accumulate funds for transfer to third parties, you must pause the automatic transfers that Pin Payments sends to your bank account. To do this, log in to your dashboard and set your transfer schedule to “Manual” on the Transfer Schedule screen. (You can always transfer funds to yourself by specifying “self” as the recipient parameter when using the transfers API.)

Payouts

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.

1. 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>

2. 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>

3. 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');
  };
});

4. 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"

5. Create a transfer

Using the recipient just created, you can now initiate a transfer to it using the transfers API.

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

You can find out how much money is available for transfer using the balance API.
curl https://test-api.pinpayments.com/1/balance -u your-secret-api-key:
Your request to the balance API endpoint will return an object that looks like this:
{
  "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 seven days of processing.

We’ll email you in the event that one of your transfers fails. 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.

Pin Payments is owned and operated by
Southern Payment Systems Pty Ltd
ABN: 46 154 451 582
Level 1, 34 Queen St,
Melbourne VIC 3000

Privacy Policy Terms Security Status

Australia