Skip to main content
POST
/
api
/
partner
/
v2
/
receivers
cURL
curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/receivers \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --data '
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "receiverType": "INDIVIDUAL",
  "email": "john.doe@example.com",
  "taxId": "RFC123456789",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "businessName": "<string>",
  "dateOfConstitution": "<string>",
  "phoneNumber": "<string>",
  "isPep": true,
  "hasBeneficialOwner": true,
  "hasResourceProvider": true
}
'
{
  "success": true,
  "data": {
    "id": "9486244c-ff7d-4c22-9984-797179d7deaa",
    "userId": "1234567c-ff7d-4c22-9984-797179d7deaa",
    "receiverType": "INDIVIDUAL",
    "email": "john.doe@example.com",
    "disabled": false,
    "createdAt": "2024-04-05T13:45:27.063Z",
    "updatedAt": "2024-04-05T13:45:27.063Z"
  }
}
Creates a receiver for third-party payments. Receivers represent individuals or businesses who can receive funds through off-ramp or cross-ramp transactions on behalf of a user.

​
Field Relationships

  • Set receiverType to INDIVIDUAL or BUSINESS — this determines which fields are required.
  • INDIVIDUAL requires: firstName, lastName, countryOfBirth.
  • BUSINESS requires: businessName, countryOfConstitution.
  • pepInfo is required only when isPep is true.

​
Use Cases

  • Third-party payments: Create receivers so users can send off-ramp payouts to other individuals or businesses.
  • Payroll: Set up employees or contractors as receivers for automated payouts.

​
Error Codes

​
Common Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”API Key is missing”
401UNAUTHORIZED”Invalid API Key format”
401UNAUTHORIZED”Invalid API Key”
403INVALID_PARTNER_FLOW”The partner has an invalid flow.”

​
User Ownership Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”Partner information is required for this operation”
401UNAUTHORIZED”User is not associated with the partner”

​
Endpoint-Specific Errors

HTTP StatusCodeMessage
400INVALID_USER_INPUT_ERROR”Invalid User Input”
400BAD_REQUEST”Provided email is not valid”
500RECEIVER_CREATION_FAILED”Failed to create receiver. Please try again later.”

Headers

​
partner-api-key
string
required

Api key for the affiliated partner that is performing the request

Body

application/json
​
userId
string
required

User ID who owns this receiver

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
receiverType
enum<string>
required

Type of receiver (INDIVIDUAL or BUSINESS)

Available options:
INDIVIDUAL,
BUSINESS
Example:

"INDIVIDUAL"

​
email
string
required

Email address of the receiver

Example:

"john.doe@example.com"

​
taxId
string
required

Tax identification number

Example:

"RFC123456789"

​
firstName
string

First name (required for INDIVIDUAL)

​
lastName
string

Last name (required for INDIVIDUAL)

​
countryOfBirth
enum<string>

Country of birth (required for INDIVIDUAL)

Available options:
MX,
DO,
US,
AT,
BE,
BG,
HR,
CY,
CZ,
DK,
EE,
FI,
FR,
DE,
GR,
HU,
IE,
IT,
LV,
LT,
LU,
MT,
NL,
PL,
PT,
RO,
SK,
SI,
ES,
SE,
IS,
LI,
NO,
CH,
GB,
MC,
SM,
AD,
VA
​
dateOfBirth
string

Date of birth (ISO date format)

​
businessName
string

Legal name (required for BUSINESS)

​
countryOfConstitution
enum<string>

Country of constitution (required for BUSINESS)

Available options:
MX,
DO,
US,
AT,
BE,
BG,
HR,
CY,
CZ,
DK,
EE,
FI,
FR,
DE,
GR,
HU,
IE,
IT,
LV,
LT,
LU,
MT,
NL,
PL,
PT,
RO,
SK,
SI,
ES,
SE,
IS,
LI,
NO,
CH,
GB,
MC,
SM,
AD,
VA
​
dateOfConstitution
string

Date of constitution (ISO date format)

​
phoneNumber
string

Phone number

​
isPep
boolean

Whether the receiver is a Politically Exposed Person

​
hasBeneficialOwner
boolean

Declaration of beneficial owner existence

​
hasResourceProvider
boolean

Declaration of resource provider existence

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object