Recipients

As the name suggests, recipients are a core part of WePay — the very reason WePay exists is so you can have secure transactions with your recipients. On this page, we'll dive into the different recipient endpoints you can use to manage recipients programmatically. We'll look at how to query, create, update, and delete recipients.

API Base URL: https://staging.wepay.to — Use this in all code examples below.
Support: admin@wepay.to

The recipient model

The recipient model contains all the information about your recipients, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the recipient and information about when they were last active on WePay.

Properties

Field	Type	Description
`id`	string	Unique identifier for the recipient.
`name`	string	The name for the recipient.
`recipientType`	string	The type of recipient. This can be either Individual or Business.
`email`	string	The recipient email address.
`organizationId`	string	Unique identifier for the organization associated with the recipient.
`userId`	string	Unique identifier for the user associated with the recipient.
`createdAt`	timestamp	Timestamp of when the recipient was created.
`updatedAt`	timestamp	Timestamp of when the recipient was last updated.
`bank`	array	The bank account information for the recipient. Array object with the Bank property.
`city`	string	City of the recipient.
`address`	string	Address of the recipient.
`postCode`	string	Post code of the recipient.
`reference`	string	Reference of the recipient.

GET/v1/recipient

List all recipients

This endpoint allows you to retrieve a paginated list of all your recipients. By default, a maximum of ten recipients are shown per page.

Query Params attributes

Field	Type	Description
`limit`	integer	Limit the number of recipients returned.
`sort`	string	Sort the recipients by a specific field. You can sort by createdAt or updatedAt. By default, recipients are sorted by createdAt. You can also sort in reverse order by adding a hyphen (-) before the field you want to sort by.
`search`	string	Search for a recipient by name or email.
`country`	string	Filter recipients by bank country and currency.
`currency`	string	Filter recipients by bank country and currency.

Request

GET

/v1/recipient

curl -G "https://staging.wepay.to/v1/recipient?search=example&limit=10&currency=INR&page=1&sort=-createdAt" \
    -H "X-Signature: YOUR_SIGNATURE" \
    -H "X-Timestamp: YOUR_TIMESTAMP" \
    -H "X-Client-ID: YOUR_CLIENT_ID"

Response

{
    "statusCode": 200,
    "message": "getQueryRecipient executed successfully",
    "data": {
        "docs": [
            {
                "name": "XXXXXX",
                "recipientType": "Individual",
                "email": "XXXXXX@example.com",
                "bank": [
                    {
                        "accountName": "XXXXXX",
                        "bankName": "XXXXXX XXXXXX",
                        "accountNumber": 12345678910,
                        "paymentCode": "XXXXXX",
                        "currency": "SGD",
                        "country": "SINGAPORE",
                        "achNumber": "1",
                        "fedwireNumber": "1",
                        "ibanNumber": "1",
                        "accountType": "Checking",
                        "_id": "XXXXXX"
                    }
                ],
                "organizationId": "XXXXXX",
                "userId": "XXXXXX",
                "createdAt": "2023-09-27T09:47:58.526Z",
                "updatedAt": "2023-09-27T09:47:58.526Z",
                "address": "XXXXXX",
                "city": "XXXXXX",
                "postCode": "XXXXXX",
                "reference": "XXXXXX",
                "id": "XXXXXX"
            },
            {
                "name": "XXXXXX",
                "recipientType": "Individual",
                ....
            }
        ],
        "totalDocs": 9,
        "offset": 0,
        "limit": 1,
        "totalPages": 9,
        "page": 1,
        "pagingCounter": 1,
        "hasPrevPage": false,
        "hasNextPage": true,
        "prevPage": null,
        "nextPage": 2
    }
  }

GET/v1/recipient/:id

Get Detail recipients

This endpoint allows you to retrieve a detailed recipient.

Params attributes

Field	Type	Description
`id`	string	Id of the recipient.

Request

GET

/v1/recipient/:id

curl -G "https://staging.wepay.to/v1/recipient/:id" \
-H "X-Signature: YOUR_SIGNATURE" \
-H "X-Timestamp: YOUR_TIMESTAMP" \
-H "X-Client-ID: YOUR_CLIENT_ID"

Response

{
    "statusCode": 200,
    "message": "getQueryRecipient executed successfully",
    "data": {
        {
            "name": "XXXXXX",
            "recipientType": "Individual",
            "email": "XXXXXX@example.com",
            "bank": [
                {
                    "accountName": "XXXXXX",
                    "bankName": "XXXXXX XXXXXX",
                    "accountNumber": 12345678910,
                    "paymentCode": "XXXXXX",
                    "currency": "SGD",
                    "country": "SINGAPORE",
                    "achNumber": "1",
                    "fedwireNumber": "1",
                    "ibanNumber": "1",
                    "accountType": "Checking",
                    "_id": "XXXXXX"
                }
            ],
            "organizationId": "XXXXXX",
            "userId": "XXXXXX",
            "createdAt": "2023-09-27T09:47:58.526Z",
            "updatedAt": "2023-09-27T09:47:58.526Z",
            "address": "XXXXXX",
            "city": "XXXXXX",
            "postCode": "XXXXXX",
            "reference": "XXXXXX",
            "id": "XXXXXX"
        }
    }
  }

POST/v1/recipient

Create a recipient

This endpoint allows you to add a new recipient to your recipient list in WePay. To add a recipient, you must provide their WePay name and email also bank country and currency.

Read the statusCode field in the response body rather than the HTTP status code.

For recipient that use for disbursement, you can get bank information from the banks endpoint.

Required attributes

Field	Type	Description
`name`	string	The name for the recipient.
`email`	string	The recipient email address.
`address`	string	The address of recipient.
`city`	string	The city of recipient.
`postCode`	string	The post code of recipient.
`bank.accountName`	string	The name of the bank account holder.
`bank.currency`	string	The currency of the bank account.
`bank.country`	string	The country of the bank account.

Optional attributes

Field	Type	Description
`recipientType`	string	The name for the recipient.
`organizationId`	string	Unique identifier for the organization associated with the recipient.
`reference`	string	The reference of recipient, you can fill to anything you want to, this fields is only for additional information
`bank.bankName`	string	The name of the bank.
`bank.accountNumber`	string	The bank account number.
`bank.paymentCode`	string	The payment code for the bank account.
`bank.achNumber`	string	The ACH number for the bank account.
`bank.fedwireNumber`	string	The Fedwire number for the bank account.
`bank.ibanNumber`	string	The IBAN number for the bank account.
`bank.accountType`	string	The type of bank account. This can be either Checking or Savings.

Request

POST

/v1/recipient

curl -X POST "https://staging.wepay.to/v1/recipient" \
-H "Content-Type: application/json" \
-H "X-Signature: YOUR_SIGNATURE" \
-H "X-Timestamp: YOUR_TIMESTAMP" \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-d '{
    "name": "XXXXX",
    "recipientType": "Individual",
    "email": "XXXXX@example.com",
    "organizationId": "XXXXX",
    "bank": {
        "currency": "USD",
        "country": "UNITED STATES",
        "accountNumber": "23123232123",
        "accountName": "XXXXX",
        "paymentCode": "XXXXX",
        "bankName": "XXXXX",
        "ifsc": "",
        "ibanNumber": "1",
        "achNumber": "1",
        "fedwireNumber": "1",
        "accountType": "Checking"
    },
    "city": "New York",
    "postCode": "1234",
    "address": "NY Street 123",
    "reference": "XXXXX"
}'

Response

{
    "statusCode": 200,
    "message": "Recipient created successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@example.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "id": "XXXXXX",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
    },
  }

PATCH/v1/recipient/:id

Update a recipient

This endpoint allows you to perform an update on a recipient. Currently, the only attribute that can be updated on recipients is the name attribute which controls how a recipient appears in your recipient list in WePay.

Required attributes

Field	Type	Description
`name`	string	The name for the recipient.
`email`	string	The recipient email address.
`address`	string	The address of recipient. (can't be empty)
`city`	string	The city of recipient. (can't be empty)
`postCode`	string	The post code of recipient. (can't be empty)
`bank.accountName`	string	The name of the bank account holder.

Optional attributes

Field	Type	Description
`reference`	string	The reference of recipient.
`bank.currency`	string	The currency of the bank account.
`bank.country`	string	The country of the bank account.
`recipientType`	string	The name for the recipient.
`organizationId`	string	Unique identifier for the organization associated with the recipient.
`bank.bankName`	string	The name of the bank.
`bank.accountNumber`	string	The bank account number.
`bank.paymentCode`	string	The payment code for the bank account.
`bank.achNumber`	string	The ACH number for the bank account.
`bank.fedwireNumber`	string	The Fedwire number for the bank account.
`bank.ibanNumber`	string	The IBAN number for the bank account.
`bank.accountType`	string	The type of bank account. This can be either Checking or Savings.

Request

PATCH

/v1/contacts/6511281bc3bfaa8e0df5ff26

curl -X PATCH "https://staging.wepay.to/v1/recipient" \
-H "Content-Type: application/json" \
-H "X-Signature: YOUR_SIGNATURE" \
-H "X-Timestamp: YOUR_TIMESTAMP" \
-H "X-Client-ID: YOUR_CLIENT_ID" \
-d '{
    "name": "XXXXX",
    "bank": {
        "currency": "USD"
    }
}'

Response

{
    "statusCode": 200,
    "message": "Recipient updated successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@example.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
      "id": "XXXXXX"
    },
}

DELETE/v1/recipient/:id

Delete a recipient

This endpoint allows you to delete recipient from your recipient list in WePay.

Request

DELETE

/v1/recipient/651602581033ce187867a766

curl -X DELETE "https://staging.wepay.to/v1/recipient?id=651602581033ce187867a766"
-H "Content-Type: application/json" \
-H "X-Signature: YOUR_SIGNATURE" \
-H "X-Timestamp: YOUR_TIMESTAMP" \
-H "X-Client-ID: YOUR_CLIENT_ID"

Response

{
    "statusCode": 200,
    "message": "Recipient deleted successfully",
    "data": {
      "name": "XXXXXX",
      "recipientType": "Individual",
      "email": "XXXXXX@example.com",
      "bank": [
          {
              "accountName": "XXXXXX",
              "bankName": "XXXXXX XXXXXX",
              "accountNumber": 12345678910,
              "paymentCode": "XXXXXX",
              "currency": "SGD",
              "country": "SINGAPORE",
              "achNumber": "1",
              "fedwireNumber": "1",
              "ibanNumber": "1",
              "accountType": "Checking",
              "_id": "XXXXXX"
          }
      ],
      "organizationId": "XXXXXX",
      "userId": "XXXXXX",
      "createdAt": "2023-09-27T09:47:58.526Z",
      "updatedAt": "2023-09-27T09:47:58.526Z",
      "city": "New York",
      "postCode": "1234",
      "address": "NY Street 123",
      "reference": "XXXXX"
      "id": "XXXXXX"
    },
}