API Reference

Recipients API

The recipients API allows you to store transfer recipient details and retrieve a token that you can safely store in your application. You can send funds to recipients using the transfers API.

POST /recipients

Creates a new recipient and returns its details.

Parameters

email The email address of the recipient.
Optional name A name for this recipient (e.g. Pin Payments or Mr Roland Robot).

and one of the following:

bank_account The full details of the bank account to be stored {...}. 
{
  "name": "Mr Roland Robot",
  "bsb": "123456",
  "number": "987654321"
}
See the bank accounts API for a description of each bank account parameter.
bank_account_token The token of the bank account to be stored, as returned from the bank accounts API.

Example

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[name]=Mr Roland Robot" \
 -d "bank_account[bsb]=123456" \
 -d "bank_account[number]=987654321"
201 Created 
{
  "response": {
    "token": "rp_a98a4fafROQCOT5PdwLkQ",
    "name": "Mr Roland Robot",
    "email": "roland@pinpayments.com",
    "created_at": "2023-06-22T06:27:33Z",
    "bank_account": {
      "token": "ba_nytGw7koRg23EEp9NTmz9w",
      "name": "Mr Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321",
      "bank_name": "",
      "branch": ""
    }
  }
}

Error Responses

422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "param": "email",
      "code": "email_invalid",
      "message": "Email is not formatted properly"
    }
  ]
}

GET /recipients

Returns a paginated list of all recipients.

Example

curl https://test-api.pinpayments.com/1/recipients -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "token": "rp_a98a4fafROQCOT5PdwLkQ",
      "name": "Mr Roland Robot",
      "email": "roland@pinpayments.com",
      "created_at": "2023-06-22T06:27:33Z",
      "bank_account": {
        "token": "ba_nytGw7koRg23EEp9NTmz9w",
        "name": "Mr Roland Robot",
        "bsb": "123456",
        "number": "XXXXXX321",
        "bank_name": "",
        "branch": ""
      }
    }
  ],
  "count": 1,
  "pagination": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 25,
    "pages": 1,
    "count": 1
  }
}

GET /recipients/recipient-token

Returns the details of a recipient.

Example

curl https://test-api.pinpayments.com/1/recipients/rp_a98a4fafROQCOT5PdwLkQ -u your-secret-api-key:
200 OK 
{
  "response": {
    "token": "rp_a98a4fafROQCOT5PdwLkQ",
    "name": "Mr Roland Robot",
    "email": "roland@pinpayments.com",
    "created_at": "2023-06-22T06:27:33Z",
    "bank_account": {
      "token": "ba_nytGw7koRg23EEp9NTmz9w",
      "name": "Mr Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321",
      "bank_name": "",
      "branch": ""
    }
  }
}

Error Responses

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

PUT /recipients/recipient-token

Updates the details of a recipient and returns its new details.

Parameters

Any of the following:

email The email address of the recipient.
bank_account The full details of the bank account to be stored {...}. 
{
  "name": "Mr Roland Robot",
  "bsb": "123456",
  "number": "987654321"
}
See the bank accounts API for a description of each bank account parameter.
bank_account_token The token of the bank account to be stored, as returned from the bank accounts API.

Example

curl https://test-api.pinpayments.com/1/recipients/rp_a98a4fafROQCOT5PdwLkQ -u your-secret-api-key: -X PUT \
 -d "email=roland@pinpayments.com" \
 -d "name=Mr Roland Robot" \
 -d "bank_account[name]=Mr Roland Robot" \
 -d "bank_account[bsb]=123456" \
 -d "bank_account[number]=987654321"
200 OK 
{
  "response": {
    "token": "rp_a98a4fafROQCOT5PdwLkQ",
    "name": "Mr Roland Robot",
    "email": "roland@pinpayments.com",
    "created_at": "2023-06-22T06:27:33Z",
    "bank_account": {
      "token": "ba_nytGw7koRg23EEp9NTmz9w",
      "name": "Mr Roland Robot",
      "bsb": "123456",
      "number": "XXXXXX321",
      "bank_name": "",
      "branch": ""
    }
  }
}

Error Responses

404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}
422 invalid_resource {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters were missing or invalid",
  "messages": [
    {
      "param": "email",
      "code": "email_invalid",
      "message": "Email is not formatted properly"
    }
  ]
}

GET /recipients/recipient-token/transfers

Returns a paginated list of a recipient’s transfers.

Example

curl https://test-api.pinpayments.com/1/recipients/rp_a98a4fafROQCOT5PdwLkQ/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
  }
}

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.