Add Recipients
Learn how to create and manage payment recipients
Overview
Recipients represent the parties who will receive payments from your users. Each recipient can have multiple payment methods (bank accounts or crypto wallets) associated with them.
Recipient Types
Sentra supports two recipient types:
- FIRST_PARTY - The recipient is the same as the user (self-transfers)
- THIRD_PARTY - The recipient is a different person or business
Entity Types
Recipients can be:
- INDIVIDUAL - Personal recipients
- BUSINESS - Business recipients
Creating a Recipient
Example Request
POST /recipients/{userId}
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key
{
"firstName": "Jane",
"lastName": "Smith",
"entityType": "INDIVIDUAL",
"type": "THIRD_PARTY",
"email": "jane.smith@example.com",
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"countryCode": "US"
},
"referenceId": "ref-12345"
}Example Response
{
"id": "rec_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"firstName": "Jane",
"middleName": null,
"lastName": "Smith",
"businessName": null,
"entityType": "INDIVIDUAL",
"type": "THIRD_PARTY",
"email": "jane.smith@example.com",
"taxIdentificationNumber": null,
"address": {
"addressLine1": "123 Main Street",
"addressLine2": "Apt 4B",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"countryCode": "US"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}Business Recipients
For business recipients, use the businessName field instead of firstName/lastName:
{
"businessName": "Acme Corporation",
"entityType": "BUSINESS",
"type": "THIRD_PARTY",
"email": "accounting@acme.com",
"taxIdentificationNumber": "12-3456789",
"address": {
"addressLine1": "456 Business Ave",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"countryCode": "US"
}
}Adding Payment Methods
Once a recipient is created, you need to add payment methods (bank accounts or crypto wallets) before they can receive payments.
Adding a Bank Account
POST /accounts/{recipientId}
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key
{
"bankName": "Chase Bank",
"currency": "USD",
"type": "CHECKING",
"accountNumber": "123456789",
"routingNumber": "021000021",
"address": {
"countryCode": "US"
}
}Adding a Crypto Wallet
POST /wallets/{recipientId}
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key
{
"address": "0x7434...5238",
"chain": "ETHEREUM"
}Managing Recipients
Update a Recipient
PUT /recipients/{id}
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key
{
"phoneNumber": "+1234567890",
"phoneCountryCode": "+1"
}Get a Recipient
GET /recipients/{id}
X-API-KEY: sk_dev_your_api_keyGet All Recipients for a User
GET /recipients/user/{userId}
X-API-KEY: sk_dev_your_api_keyBank Account Requirements
Different countries and currencies require different bank account fields. Use the requirements endpoint to check what's needed:
GET /accounts/requirements?currencyCode=EUR&bankCountryCode=DE
X-API-KEY: sk_dev_your_api_keyExample Response
{
"requiredFields": ["iban", "bicSwift"],
"optionalFields": ["bankName", "accountNumber"]
}