API Reference

Transfers API

The transfers API allows you to send money to Australian bank accounts and retrieve details of previous transfers.

POST /transfers

Creates a new transfer and returns its details.

Parameters

description A description of the amount being transfered (e.g. Earnings for may). This description is intended for your records and will not be displayed on the recipient’s bank statement.
amount The amount to transfer in the currency’s base unit (e.g. cents for AUD, yen for JPY). Must be greater than or equal to 0.
currency The currency to transfer. Currently, only AUD is supported.
recipient The recipient’s token (as returned from the recipients API) or self. If self is passed, the funds will be transferred to your own bank account.

Example

curl https://test-api.pinpayments.com/1/transfers -u your-secret-api-key: \
 -d "amount=400" \
 -d "currency=AUD" \
 -d "description=Earnings for may" \
 -d "recipient=rp_a98a4fafROQCOT5PdwLkQ"
201 Created 
{
  "response": {
    "token": "tfer_lfUYEBK14zotCTykezJkfg",
    "status": "succeeded",
    "currency": "AUD",
    "description": "Earnings for may",
    "amount": 400,
    "total_debits": 200,
    "total_credits": 600,
    "created_at": "2023-06-20T03:10:49Z",
    "paid_at": "2023-06-20T03:10:49Z",
    "reference": "Test Business",
    "line_items_count": 2,
    "bank_account": {
      "token": "ba_nytGw7koRg23EEp9NTmz9w",
      "name": "Mr Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321",
      "bank_name": "",
      "branch": ""
    },
    "recipient": "rp_a98a4fafROQCOT5PdwLkQ"
  }
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "code": "description_invalid",
      "message": "Description can't be blank",
      "param": "description"
    }
  ]
}
402 insufficient_pin_balance {...} 
[
  {
    "error": "insufficient_pin_balance",
    "error_description": "There are not enough funds available to process this transfer"
  }
]

GET /transfers

Returns a paginated list of all transfers.

Example

curl https://test-api.pinpayments.com/1/transfers -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "tfer_lfUYEBK14zotCTykezJkfg",
      "status": "succeeded",
      "currency": "AUD",
      "description": "Earnings for may",
      "amount": 400,
      "total_debits": 200,
      "total_credits": 600,
      "created_at": "2023-06-20T03:10:49Z",
      "paid_at": "2023-06-20T03:10:49Z",
      "reference": "Test Business",
      "line_items_count": 2,
      "bank_account": {
        "token": "ba_nytGw7koRg23EEp9NTmz9w",
        "name": "Mr Roland Robot",
        "bsb": "123456",
        "number": "XXXXXX321",
        "bank_name": "",
        "branch": ""
      },
      "recipient": "rp_a98a4fafROQCOT5PdwLkQ"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /transfers/search

Returns a paginated list of transfers matching the search criteria.

Optional query Return only transfers whose token, description, amount or recipient details match the supplied query.
Optional start_date Return only transfers created on or after this date (e.g. 2012/12/25).
Optional end_date Return only transfers created before this date (e.g. 2013/12/25).
Optional sort The field used to sort the transfers (only option: paid_at). Default value is paid_at.
Optional direction The direction in which to sort the transfers (1 for ascending or -1 for descending). Default value is 1.

Example

curl https://test-api.pinpayments.com/1/transfers/search -u your-secret-api-key: -X GET \
 -d "query=Earnings"
200 OK 
{
  "response": [
    {
      "token": "tfer_lfUYEBK14zotCTykezJkfg",
      "status": "succeeded",
      "currency": "AUD",
      "description": "Earnings for may",
      "amount": 400,
      "total_debits": 200,
      "total_credits": 600,
      "created_at": "2023-06-20T03:10:49Z",
      "paid_at": "2023-06-20T03:10:49Z",
      "reference": "Test Business",
      "line_items_count": 2,
      "bank_account": {
        "token": "ba_nytGw7koRg23EEp9NTmz9w",
        "name": "Mr Roland Robot",
        "bsb": "123456",
        "number": "XXXXXX321",
        "bank_name": "",
        "branch": ""
      },
      "recipient": "rp_a98a4fafROQCOT5PdwLkQ"
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /transfers/transfer-token

Returns the details of the specified transfer.

Example

curl https://test-api.pinpayments.com/1/transfers/tfer_bZ3RhJnIUZ8HhfvH8CCvfA -u your-secret-api-key:
200 OK 
{
  "response": {
    "token": "tfer_lfUYEBK14zotCTykezJkfg",
    "status": "succeeded",
    "currency": "AUD",
    "description": "Earnings for may",
    "amount": 400,
    "total_debits": 200,
    "total_credits": 600,
    "created_at": "2023-06-20T03:10:49Z",
    "paid_at": "2023-06-20T03:10:49Z",
    "reference": "Test Business",
    "line_items_count": 2,
    "bank_account": {
      "token": "ba_nytGw7koRg23EEp9NTmz9w",
      "name": "Mr Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321",
      "bank_name": "",
      "branch": ""
    },
    "recipient": "rp_a98a4fafROQCOT5PdwLkQ"
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

GET /transfers/transfer-token/line_items

Returns a paginated list of line items associated with the specified transfer.

Example

curl https://test-api.pinpayments.com/1/transfers/tfer_bZ3RhJnIUZ8HhfvH8CCvfA/line_items -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "type": "charge_merchant_entitlement",
      "amount": 400,
      "currency": "AUD",
      "created_at": "2023-06-18T09:00:29Z",
      "object": "charge",
      "token": "ch_lfUYEBK14zotCTykezJkfg",
      "record": {
        "description": "test charge",
        "amount": 400,
        "total_fees": 62,
        "merchant_entitlement": 338
      }
    },
    {
      "type": "adjustment",
      "amount": 30,
      "currency": "AUD",
      "created_at": "2023-06-19T15:22:45Z"
    }
  ],
  "count": 2,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 2
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.