Payees

Overview

The Payees module is an integral part of the customer API that allows users to manage their list of payees—people or organizations they need to send money to. It provides a suite of API endpoints that facilitate various operations required to maintain an up-to-date payee list for customers within the platform.

Create Payee - Allows users to add a new payee with details such as name, banking information, and address. This is essential for setting up new beneficiaries for transactions.
Edit Payee - Users can update the details of an existing payee. This endpoint is useful for making corrections or changes to the payee information, such as their bank account details or address.
Get Payee by ID - Enables a user to retrieve information about a payee by submitting the ID of the payee.
List Payees - Retrieve a list of payees associated with a customer
Delete Payee - Allows a user to delete a Payee, removing it from being an option for further transfer destinations
Initiate ACH Pull: Allows a manager to initiate an ACH pull request from a customer's payee.

Create Payee

This endpoint creates a new payee for a specific customer. A payee is essentially a destination that where one would send a payment to outside of the banking system, such as a bank account. A customer can use this feature to add a new person or company they need to send money to. The customer inputs necessary banking details and address information to set up the payee in their account

Endpoint: /api/v1/customer/payees/create
Method: POST

Create a payee for a customer

Request body:

CustomersId: customers Id
PayeeType: Payee type (Personal, Company)
RoutingNumber: Payee's routing number (required for domestic payees)
AccountNumber: Payee's account number (required)
Bic: Payee's BIC number (required for international payees)
Iban: Payee's IBAN number (required for international payees)
PayeesReference: Customer payee reference
Name: Payee's name
AddressLine1: Payee's address line 1
AddressLine2: Payee's address line 2 (optional)
TownCity: Payee's town or city
State: Payee's state (optional)
Postcode: Payee's postcode
Country: Payee's country code (required for international payees)

Response:

Id: Payee's Id
CustomersId: Customer's Id
PayeeType: Payee type
PayeesReference: Customer defined payee reference
RoutingNumber: Payee's routing number
AccountNumber: Payee's account number
Bic: Payee's BIC number
Iban: Payee's IBAN number
Name: Payee's name
AddressLine1: Payee address line 1
AddressLine2: Payee address line 2
TownCity: Payee's town or city
State: Payee's state
Postcode: Payee's postcode
Country: Payee's country

Possible validation errors:

Required
Invalid
Already_Exists (Payee with specified account and routing number already exists)
Only_One_Of_Bic_Or_RoutingNumber_Can_Be_Set
Bic_Or_Country_Invalid

POSThttp://public-api.ibanera.com/api/v1/customer/payees/create

Header parameters

Body

customersIdnullable integer (int32)

payeeTypeAvamaeTemplate.Core.Enums.PayeeTypes (enum)

routingNumbernullable string

accountNumbernullable string

bicnullable string

ibannullable string

payeesReferencenullable string

namenullable string

addressLine1nullable string

addressLine2nullable string

townCitynullable string

statenullable string

postcodenullable string

countrynullable string

bankNamenullable string

currencyCodenullable string

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.Payees.PayeeDto (object)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "payeeType": 0,
    "payeesReference": "text",
    "routingNumber": "text",
    "accountNumber": "text",
    "bic": "text",
    "iban": "text",
    "name": "text",
    "addressLine1": "text",
    "addressLine2": "text",
    "townCity": "text",
    "state": "text",
    "postcode": "text",
    "country": "text",
    "bankName": "text"
  }
}

Request Body: application/json

CustomersId (Integer, Required): The identifier for the customer.
PayeeType (String, Required): The type of payee, values can be Personal or Company.
RoutingNumber (String, Optional, For domestic payees): The routing number of the payee's bank for domestic transactions.
AccountNumber (String, Required): The bank account number of the payee.
BankName (String, Optional): The bank's name. This will be looked up based on other information if not included.
Bic (String, Optional, For international payees): The SWIFT/BIC code for international banking purposes.
Iban (String, Optional, For international payees): The International Bank Account Number for international transactions.
PayeesReference (String, Optional): A customer-defined reference for the payee.
Name (String, Required): The full name of the payee.
AddressLine1 (String, Required): The primary address line for the payee.
AddressLine2 (String, Optional): The secondary address line for the payee (if any).
TownCity (String, Required): The town or city where the payee is located.
State (String, Required): The state or region where the payee is located.
Country (String, Required): The country where the payee is located.
Postcode (String, Required): The postal code associated with the payee's address.

Request Body Example:

{
    "customersId": 1004,
    "PayeeType": "Personal",
    "RoutingNumber": "",
    "AccountNumber": "521101580",
    "BankName": "My Bank",
    "Bic": "CZNBVN2XXXX",
    "Iban": "12345Test",
    "PayeesReference": "RefExample",
    "Name": "Name Surname",
    "AddressLine1": "Address Line 1",
    "TownCity": "Austin",
    "State": "TX",
    "Country": "VNM",
    "Postcode": "123ABC"
}

Response Body (Success): application/json

id (Integer): A generated ID that references the newly created payee.
details (Object): An object containing details about the newly created payee:
- id (Integer): Same as the outer id field for ease of access.
- customersId (Integer): The customer's ID for whom the payee was created.
- payeeType (String): The type of payee, Personal or Company.
- payeeReference (String): Customer defined payee reference.
- routingNumber (String): The routing number of the payee's bank.
- accountNumber (String): The bank account number of the payee.
- bic (String): The SWIFT/BIC code of the payee.
- iban (String): The International Bank Account Number of the payee.
- name (String): The full name of the payee.
- addressLine1 (String): The primary address line for the payee.
- addressLine2 (String): The secondary address line for the payee.
- townCity (String): The town or city where the payee is located.
- state (String): The state or region where the payee is located.
- postcode (String): The postal code for the payee's address.
- country (String): The country where the payee is located.
- bankName (String): The name of the payee's bank.
status (Integer): The status code, typically "1" for success.
errors (Array): An array containing any error messages related to the request.

Response Body Example:

{
    "id": 1007,
    "details": {
        "id": 1007,
        "customersId": 1004,
        "payeeType": "Personal", 
        "payeesReference": "RefExample", 
        "routingNumber": "", 
        "accountNumber": "521101580", 
        "bankName": "My Bank",
        "bic": "CZNBVN2XXXX",
        "iban": "12345Test",
        "name": "Name Surname", 
        "addressLine1": "Address Line 1", 
        "addressLine2": null, 
        "townCity": "Austin",
        "state": "TX",
        "postcode": "123ABC",
        "country": "USA"
    },
    "status": "1",
    "errors": []
}

Possible Error Response:

Required (Error Code): Indicates that a required field is missing or has a zero value.
Invalid (Error Code): Suggests that a field contains an invalid value.
Documents_Not_Verified (Error Code): This action cannot be performed for the customer due to KYC (Know Your Customer) requirements not being met.

Edit Payee

Users can update the details of someone they've set up to send payments to (a payee). They'll need to provide specific information like the account details they wish to change. Once submitted, the system updates the payee's details, confirming the updates with the user or reporting why it wasn't able to if there's an issue. Only non-null fields will be updated

Endpoint: /api/v1/customer/payees/edit
Method: PATCH

Edit payee

Request body:

CustomersId: customers Id
PayeeType: Payee type (Personal, Company) (optional)
RoutingNumber: Payee's routing number (optional)
AccountNumber: Payee's account number (optional)
Bic: Payee's BIC number (optional)
Iban: Payee's IBAN number (optional)
PayeesReference: Customer payee reference (optional)
Name: Payee's name (optional)
AddressLine1: Payee's address line 1 (optional)
AddressLine2: Payee's address line 2 (optional)
TownCity: Payee's town or city (optional)
State: Payee's state (optional)
Postcode: Payee's postcode (optional)

Response:

Id: Payee's Id
PayeeType: Payee type
PayeesReference: Customer defined payee reference
RoutingNumber: Payee's routing number
AccountNumber: Payee's account number
Bic: Payee's BIC number
Iban: Payee's IBAN number
Name: Payee's name
AddressLine1: Payee address line 1
AddressLine2: Payee address line 2
TownCity: Payee's town or city
State: Payee's state
Postcode: Payee's postcode
Country: Payee's country

Possible validation errors:

Required
Invalid
Already_Exists (Payee with specified account and routing number already exists)
Only_One_Of_Bic_Or_RoutingNumber_Can_Be_Set
Bic_Or_Country_Invalid

PATCHhttp://public-api.ibanera.com/api/v1/customer/payees/edit

Header parameters

Body

idnullable integer (int32)

payeeTypeAvamaeTemplate.Core.Enums.PayeeTypes (enum)

routingNumbernullable string

accountNumbernullable string

bicnullable string

ibannullable string

payeesReferencenullable string

namenullable string

addressLine1nullable string

addressLine2nullable string

townCitynullable string

statenullable string

countrynullable string

postcodenullable string

bankNamenullable string

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.Payees.PayeeDto (object)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/edit', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "payeeType": 0,
    "payeesReference": "text",
    "routingNumber": "text",
    "accountNumber": "text",
    "bic": "text",
    "iban": "text",
    "name": "text",
    "addressLine1": "text",
    "addressLine2": "text",
    "townCity": "text",
    "state": "text",
    "postcode": "text",
    "country": "text",
    "bankName": "text"
  }
}

Request Body Parameters: application/json

Only non-null fields will be updated!

Id (Integer, Required): The ID of the payee to be edited.
PayeeType (String, Optional): The type of payee, values can be Personal or Company.
RoutingNumber (String, Optional): The routing number of the payee's bank for domestic transactions.
AccountNumber (String, Optional): The bank account number of the payee.
BankName (String, Optional): The bank's name, which will be looked up based on other information if not included.
Bic (String, Optional): The SWIFT/BIC code for international banking purposes.
Iban (String, Optional): The International Bank Account Number for international transactions.
PayeesReference (String, Optional): A customer-defined reference for the payee.
Name (String, Optional): The full name of the payee.
AddressLine1 (String, Optional): The primary address line for the payee.
AddressLine2 (String, Optional): The secondary address line for the payee (if any).
TownCity (String, Optional): The town or city where the payee is located.
State (String, Optional): The state or region where the payee is located.
Country (String, Optional): The country where the payee is located.
Postcode (String, Optional): The postal code associated with the payee's address.

Request Body Example:

{
    "id": 1001,
    "PayeeType": "Personal",
    "RoutingNumber": "",
    "AccountNumber": "521101580",
    "BankName": "My Bank",
    "Bic": "CZNBVN2XXXX",
    "Iban": "12345Test",
    "PayeesReference": "RefExample",
    "Name": "Name Surname",
    "AddressLine1": "Address Line 1",
    "TownCity": "Austin",
    "State": "TX",
    "Country": "VNM",
    "Postcode": "123ABC"
}

Response Body Parameters: application/json

id (Integer): A reference ID for the payee; not used in the example.
details (Object): An object containing updated details about the payee, including:
- id (Integer): The ID of the payee that was edited.
- customersId (Integer): The customer's ID associated with the edited payee.
- payeeType (String): The updated type of payee, Personal or Company.
- payeesReference (String): The updated customer defined payee reference.
- routingNumber (String): The updated routing number of the payee's bank.
- accountNumber (String): The updated bank account number of the payee.
- bic (String): The updated SWIFT/BIC code of the payee.
- iban (String): The updated International Bank Account Number of the payee.
- name (String): The updated name of the payee.
- addressLine1 (String): The updated address line for the payee.
- addressLine2 (String, Nullable): The updated address line 2 for the payee.
- townCity (String): The updated town or city where the payee is located.
- state (String): The updated state or region where the payee is located.
- postcode (String): The updated postal code for the payee's address.
- country (String): The updated country where the payee is located.
- bankName (String): The updated bank name of the payee.

Success Response Example:

{
  "id": 1004,
  "details": {
    "id": 1004,
    "customersId": 1004,
    "payeeType": "Personal",
    "payeesReference": "MyPayee123",
    "routingNumber": "011000536",
    "accountNumber": "1234566798",
    "bankName": "Example Bank",
    "bic": "EXAMPL33XXX",
    "iban": "GB29NWBK60161331926819",
    "name": "Jane Doe",
    "addressLine1": "789 Maple St",
    "addressLine2": null,
    "townCity": "Dallas",
    "state": "TX",
    "postcode": "987ZYX",
    "country": "USA"
  },
  "status": "1",
  "errors": []
}

Error Codes:

Required (Error Code): Indicates that a required field is missing or has a zero value.
Invalid (Error Code): Suggests that a field contains an invalid value.
Documents_Not_Verified (Error Code): The action cannot be performed for the customer due to KYC (Know Your Customer) requirements not being met.

Error Response Example:

{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "errorType": "BadRequest",
      "fieldName": "PayeeType",
      "messageCode": "Invalid"
    }
  ]
}

Get Payee by ID

Users can retrieve the details of someone they've set up to send payments to (a payee). They'll need to provide the specific ID of the payee to retrieve information.

Endpoint: /api/v1/customer/payees/get
Method: GET

Get payee by Id

Request query:

Id: Payee's Id

Response:

Id: Payee's Id
CustomersId: Customer's Id
PayeeType: Payee type
PayeesReference: Customer defined payee reference
RoutingNumber: Payee's routing number
AccountNumber: Payee's account number
Bic: Payee's BIC number
Iban: Payee's IBAN number
Name: Payee's name
AddressLine1: Payee address line 1
AddressLine2: Payee address line 2
TownCity: Payee's town or city
State: Payee's state
Postcode: Payee's postcode
Country: Payee's country

Possible validation errors:

Required,
Invalid

GEThttp://public-api.ibanera.com/api/v1/customer/payees/get

Query parameters

Header parameters

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.Payees.PayeeDto (object)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/get', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "payeeType": 0,
    "payeesReference": "text",
    "routingNumber": "text",
    "accountNumber": "text",
    "bic": "text",
    "iban": "text",
    "name": "text",
    "addressLine1": "text",
    "addressLine2": "text",
    "townCity": "text",
    "state": "text",
    "postcode": "text",
    "country": "text",
    "bankName": "text"
  }
}

List Payees

Retrieve a list of payees associated with a customer

Endpoint: /api/v1/customer/payees/list
Method: GET

List all payees

Request query:

CustomersId: Customer Id filter
PayeesReference: Payee reference filter
RoutingNumber: routing number filter
AccountNumber: account number filter
Bic: BIC number filter
Iban: IBAN number filter
Country: Country code filter
PageNumber: list page number (optional, default = 1)
PageSize: list page size (optional, default = 10)

Response:

array of
- Id: Payee's Id
- CustomersId: Customer's Id
- PayeeType: Payee type
- PayeesReference: Customer defined payee reference
- RoutingNumber: Payee's routing number
- AccountNumber: Payee's account number
- Bic: Payee's BIC number
- Iban: Payee's IBAN number
- Name: Payee's name
- AddressLine1: Payee address line 1
- AddressLine2: Payee address line 2
- TownCity: Payee's town or city
- State: Payee's state
- Postcode: Payee's postcode
- Country: Payee's country

GEThttp://public-api.ibanera.com/api/v1/customer/payees/list

Query parameters

Header parameters

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsnullable array of AvamaeTemplate.Core.Types.Dtos.CustomerRole.Payees.PayeeDto (object)

pageSizenullable integer (int32)

pageNumbernullable integer (int32)

numberOfPagesnullable integer (int32)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/list', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": [
    {
      "payeeType": 0,
      "payeesReference": "text",
      "routingNumber": "text",
      "accountNumber": "text",
      "bic": "text",
      "iban": "text",
      "name": "text",
      "addressLine1": "text",
      "addressLine2": "text",
      "townCity": "text",
      "state": "text",
      "postcode": "text",
      "country": "text",
      "bankName": "text"
    }
  ]
}

Delete Payee

Allows a user to delete a Payee, removing it from being an option for further transfer destinations

Endpoint: /api/v1/customer/payees/delete
Method: DELETE

Delete payee

Request body:

Id: Payee's Id

Possible validation errors:

Required,
Invalid

DELETEhttp://public-api.ibanera.com/api/v1/customer/payees/delete

Header parameters

Body

idnullable integer (int32)

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int32)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/delete', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ]
}

Initiate ACH Pull

Allows a manager to initiate an ACH pull request from a customer's payee.

Endpoint: /api/v1/customer/payees/pullfunds
Method: POST

Pull funds from a Plaid payee.

Possible validation errors:

Required
Invalid
Screening_Failed
Funding_Already_Pending

POSThttp://public-api.ibanera.com/api/v1/customer/payees/pullfunds

Header parameters

Body

payeesIdnullable integer (int32)

amountnullable number (double)

customerAssetAccountsIdnullable integer (int32)

referenceSetternullable string

referencenullable string

Response

Success

Body

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.Payees.SaveAchPullDto (object)

Request

const response = await fetch('http://public-api.ibanera.com/api/v1/customer/payees/pullfunds', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text",
  "errors": [
    {
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "amount": 0,
    "description": "text",
    "dateTime": "2024-05-09T12:06:05.568Z",
    "bPending": false,
    "bApproved": false
  }
}

Request Body Parameters: application/json

Request Body Paramerer	Format	Description	Required
PayeesId	Integer	PayeesId where the bank can pull funds from	Yes
Amount	Decimal	Amount to be pulled from payee	Yes
CustomerAssetAccountsId	Integer	The destination customer account id	Yes
Reference	String	For pooled account this should be the reference of the pooled account. Maximum 15 characters allowed	Yes

Request Body Paramerer

Format

Description

Required

PayeesId

Integer

PayeesId where the bank can pull funds from

Yes

Amount

Decimal

Amount to be pulled from payee

Yes

CustomerAssetAccountsId

Integer

The destination customer account id

Yes

Reference

String

For pooled account this should be the reference of the pooled account.

Maximum 15 characters allowed

Yes

Request Body Example

{
        "PayeesId":1204,
        "Amount":100,
        "CustomerAssetAccountsId":2141,
        "Reference":"REF2141"
}

Response Body

Response Body Parameter	Format	Description
id	Integer	Transfer Id
details.
details.id	Integer	Transaction Id
details.accountsId	Integer	Transaction account Id
details.fromTransactionsId	Integer	Nullable linked from transaction Id
details.fromAccountsId	Integer	Nullable linked from account Id
details.toTransactionsId	Integer	Nullable linked to transaction Id
details.toAccountsId	Integer	Nullable linked to account Id
details.amount	Decimal	Transaction amount
details.description	String	Transaction description
details.dateTime	ISO 8601	Transaction date
details.bPending	Bool	Is transaction pending
details.bApproved	Bool	Is screening approved

Response Body Parameter

Format

Description

Integer

Transfer Id

details.

details.id

Integer

Transaction Id

details.accountsId

Integer

Transaction account Id

details.fromTransactionsId

Integer

Nullable linked from transaction Id

details.fromAccountsId

Integer

Nullable linked from account Id

details.toTransactionsId

Integer

Nullable linked to transaction Id

details.toAccountsId

Integer

Nullable linked to account Id

details.amount

Decimal

Transaction amount

details.description

String

Transaction description

details.dateTime

ISO 8601

Transaction date

details.bPending

Bool

Is transaction pending

details.bApproved

Bool

Is screening approved

Request Body Example

{
    "id": 22117,
    "details": {
        "id": 31605,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": 100.000000000000000000,
        "description": "Funding Ibanera USD Account",
        "dateTime": "2024-04-15T11:21:08.8533333+00:00",
        "bPending": true,
        "bApproved": true
    },
    "status": "1",
    "errors": []
}

Potential Error Codes

Error message code example	Description
Required	Required field not provided
Invalid	Provided destination account is invalid or provided payee id is invalid
Funding_Already_Pending	If there is already some pull funds are pending on the destination customer account, not allowed to do another pull to the account.
Invalid_Source_Account	Provided source account is invalid
Invalid_Asset	Asset associated with the account is not fiat currency or both account have different assets.
Ach_limit_exceed_5000	The requested amount is greater than the allowed ach limit
Invalid_Reference_For_FBO_Account	For pooled destination account, given reference should match with the destination account reference
Internal_Error	Any unknown error

Error message code example

Description

Required

Required field not provided

Invalid

Provided destination account is invalid or provided payee id is invalid

Funding_Already_Pending

If there is already some pull funds are pending on the destination customer account, not allowed to do another pull to the account.

Invalid_Source_Account

Provided source account is invalid

Invalid_Asset

Asset associated with the account is not fiat currency or both account have different assets.

Ach_limit_exceed_5000

The requested amount is greater than the allowed ach limit

Invalid_Reference_For_FBO_Account

For pooled destination account, given reference should match with the destination account reference

Internal_Error

Any unknown error

PreviousExchanges NextTransfers

Last updated 15 days ago