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": "2012-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": "2012-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": "2012-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": "2012-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": "2012-06-20T03:10:49Z",
      "paid_at": "2012-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."
}

Southern Payment Systems Pty Ltd
t/a Pin Payments
ABN: 46 154 451 582
Level 4, 356 Collins St,
Melbourne VIC 3000

A Checkout.com company

Privacy Policy Terms Security Status